Skip to content

Suggestion: make it easier to discover which cmdlet parameters accept pipeline input, via the syntax diagram #4135

@mklement0

Description

@mklement0

Related: #4715 and #4626.

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 -Full and then browse the entire topic for Accept 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Issue-Enhancementthe issue is more of a feature request than a bugResolution-No ActivityIssue has had no activity for 6 months or moreWG-Interactive-HelpSystemhelp infrastructure and formatting of help

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions