-
Notifications
You must be signed in to change notification settings - Fork 8.2k
Suggestion: make it easier to discover which cmdlet parameters accept pipeline input, via the syntax diagram #4135
Description
Currently, it is not easy to discover which of a given cmdlet's / advanced function's parameters accept pipeline input and how (by value and/or by property name):
Using the example of Rename-Item:
-
You can use
Get-Help Rename-Item -Fulland then browse the entire topic forAccept pipeline input?lines -
You can use a nontrivial command such as the following:
Get-Help Rename-Item -Parameter * | ? pipelineInput -like 'true*' | Select-Object Name, Type, pipelineInput
The above yields:
name type pipelineInput
---- ---- -------------
Credential @{name=PSCredential; uri=} true (ByPropertyName)
LiteralPath @{name=String; uri=} true (ByPropertyName)
NewName @{name=String; uri=} true (ByPropertyName)
Path @{name=String; uri=} true (ByValue, ByPropertyName)
Neither option is convenient.
Perhaps the syntax diagrams could be enhanced with symbols that reflect pipeline-binding behavior?
Something along the lines of (these are mere examples; the idea is to be concise):
|... by value (only)⌠... by property name (only)|⌠... by both value and property name
Applied to the Rename-Item example, with the symbols placed inside (...) after the parameter (for example):
Rename-Item [-Path(|⌠)] <String> [-NewName] <String> [-Credential(⌠) <PSCredential>] [-Force] [-PassThru] [-Confirm] [-WhatIf] [-UseTransaction <SwitchParameter>]
[<CommonParameters>]
Rename-Item [-NewName(⌠)] <String> [-Credential(⌠) <PSCredential>] [-Force] [-PassThru] -LiteralPath(⌠) <String> [-Confirm] [-WhatIf] [-UseTransaction <SwitchParameter>]
[<CommonParameters>]
Note: A crucial piece missing from the above is that parameters have aliases and that binding by property name often happens via those aliases; e.g., Select-String's -LiteralPath has an alias of PSPath, and when you pipe Get-ChildItem output to Select-String, the objects bind by .PSPath, not .LiteralPath.
Written as of PowerShell Core v6.0.0-beta.3.