Create Parameter Set Tools
Closed this issue · 6 comments
This is going to be based upon a function created by KirkMunro on thread: Add / amend syntax displayed from Get-Command -syntax. (PS, need to make sure to credit KirkMunro in the documentation).
The output generated by this function is difficulkt to read, we need to sprinkle some Krayon magic dust on it and pretty up the out put, in particular highlighting the parameter set name, so they can be easily picked out by eye.
I would like to develop this into a fully fledged ParameterSet debugging tool. One nice addition would be enable the user to specify a function and a parameter list to see which parameter set is invoked. I know you can effectively do this by invoking the function for real, but we might not want to do this especially if the function is a state changing one.
When PowerShell can't determine the parameter set for a particular invoke set, we need to see the list of parameter sets that PowerShell doesnt have enough information for to choose which one.
We also need functionality that will show if there are any parameter sets that have the same set of parameters, this will also help in debugging parameter set issues.
Might have to split this functionality out into different commands depending on further analysis.
See Cmdlet parameter sets for more information regarding the rules for parameters ets.
Some notes:
For both of these, the type is optional, switch parameters don't have any type
[-Pattern] <type>: optional parameter
-underscore <type>: mandatory parameter
Syntax colour scheme
- punctuation ([], <>) not inclduing - which marks the param name => yellow (krayola.META-COLOURS)
- type, anyting inside <> - type-colour
Table colour scheme
- mandatory param name => krayola.AFFIRM-COLOURS
- optional param name => krayola.VALUE-COLOURS
- command name => green
- parameter set name => dark green
- table column titles => krayola.KEY-COLOURS
- table column titles => krayola.KEY-COLOURS
- table mandatory param value => krayola.AFFIRM-COLOURS
- table optional param value => krayola.VALUE-COLOURS
- table value default => gray
A couple of artciles regarding proprty expansion/parameter-set processing:
other functions to create:
- Test-CommandInvoke: identifies the parameter set for an invoke, if ambiguous should show candidate list. This would require the user to provide actual parameters.
Add the following extra parameters to Get-ParameterSetInfo:
- Sets: an array of parameter set names: provides a filtering mechanism
- Indentical: switch to show which parameter sets have the same set of parameters and are thus a cause of errors
I just noticed a potential bug in the -syntax property of Get-Command. So far, I've only notived this on Rename-Many, but it might be prevalent on other commands; the inconsistency of the type psotion may also be related to this issue. This was made more noticeable by the fact that Get-ParameterSetInfo colours its output:
If you look closely, you'll notice the following points
- The type info for each parameter in the syntax statement is inconsistently displayed. For 'Pattern' its of the form [-Param ] (because Get-ParameterSetInfo fixes it) but with gcm its [-Param] <type>; ie the type is outside of the square brackets
- The syntax statement shows that Pattern is optional (its written in white and it is surrounded in square brackets. However, this is wrong because for this particular parameter set, Pattern is mandatory. This is confirmed by the contets of the table displayed. In it, Pattern is highlighted in red and the Mandatory flag is set
My initial thought is that there is a problem in the code that generates the syntax statement, because its not in sync with underlying parameter info.
If you run:
gcm Rename-Many -syntax
you'll see this:
λ gcm rename-many -Syntax
Rename-Many [-Pattern] <array> -underscore <FileSystemInfo> [-Copy <array>] [-With <string>] [-Start] [-End] [-Paste <string>] [-Drop <string>] [-File] [-Directory] [-Except <string>] [-Include <string>] [-Whole <string>] [-Condition <scriptblock>] [-Top <int>] [-Transform <scriptblock>] [-Context <psobject>] [-Diagnose] [-WhatIf] [-Confirm] [<CommonParameters>]
Rename-Many [-Pattern] <array> -underscore <FileSystemInfo> -End [-With <string>] [-Paste <string>] [-Drop <string>] [-File] [-Directory] [-Except <string>] [-Include <string>] [-Whole <string>] [-Condition <scriptblock>] [-Top <int>] [-Transform <scriptblock>] [-Context <psobject>] [-Diagnose] [-WhatIf] [-Confirm] [<CommonParameters>]
Rename-Many [-Pattern] <array> -underscore <FileSystemInfo> -Start [-With <string>] [-Paste <string>] [-Drop <string>] [-File] [-Directory] [-Except <string>] [-Include <string>] [-Whole <string>] [-Condition <scriptblock>] [-Top <int>] [-Transform <scriptblock>] [-Context <psobject>] [-Diagnose] [-WhatIf] [-Confirm] [<CommonParameters>]
Rename-Many [-Pattern] <array> -underscore <FileSystemInfo> -Anchor <array> [-Relation <string>] [-Copy <array>] [-With <string>] [-Paste <string>] [-Drop <string>] [-File] [-Directory] [-Except <string>] [-Include <string>] [-Whole <string>] [-Condition <scriptblock>] [-Top <int>] [-Transform <scriptblock>] [-Context <psobject>] [-Diagnose] [-WhatIf] [-Confirm] [<CommonParameters>]
Rename-Many -underscore <FileSystemInfo> -Append <string> [-Copy <array>] [-File] [-Directory] [-Except <string>] [-Include <string>] [-Whole <string>] [-Condition <scriptblock>] [-Top <int>] [-Transform <scriptblock>] [-Context <psobject>] [-Diagnose] [-WhatIf] [-Confirm] [<CommonParameters>]
Rename-Many -underscore <FileSystemInfo> -Prepend <string> [-Copy <array>] [-File] [-Directory] [-Except <string>] [-Include <string>] [-Whole <string>] [-Condition <scriptblock>] [-Top <int>] [-Transform <scriptblock>] [-Context <psobject>] [-Diagnose] [-WhatIf] [-Confirm] [<CommonParameters>]
But the problem with this is that these parameter sets are not decorated with the parameter name; hence me building these parameter sets tools.
If you run Get-CommandDetails (only the 'ReplaceWith' parameter set is shown):
'Rename-Many' | Get-CommandDetail
Parameter Set: ReplaceWith (Default)
Syntax: Rename-Many [-Pattern] <array> -underscore <FileSystemInfo> [-Copy <array>] [-With <string>] [-Start] [-End] [-Paste <string>] [-Drop <string>] [-File] [-Directory] [-Except <string>] [-Include <string>] [-Whole <string>] [-Condition <scriptblock>] [-Top <int>] [-Transform <scriptblock>] [-Context <psobject>] [-Diagnose] [-WhatIf] [-Confirm] [<CommonParameters>]
Parameters:
Name Type Mandatory Pos PipeValue PipeName Alias
---- ---- --------- --- --------- -------- -----
Pattern Array True 0 False False
underscore FileSystemInfo True named True False
Copy Array False named False False
With String False named False False
Start SwitchParameter False named False False
End SwitchParameter False named False False
Paste String False named False False
Drop String False named False False
File SwitchParameter False named False False
Directory SwitchParameter False named False False
Except String False named False False x
Include String False named False False i
Whole String False named False False
Condition ScriptBlock False named False False
Top Int32 False named False False
Transform ScriptBlock False named False False
Context PSObject False named False False
Diagnose SwitchParameter False named False False
you can see the errorneous way that Pattern is displayed:
[-Pattern] <array>
ie the type is outside of the square brackets.
Get-ParameterSetInfo recognises this and repairs the output.
Argh, Get-ParameterSetInfo should be called Show-ParameterSetInfo.