Skip to content

Suggestion: make it easier to discover which cmdlet parameters accept wildcard patterns, via the syntax diagram #4715

Closed

Description

Related: #4135 and #4626.

Currently, it is not easy to discover which of a given cmdlet's / advanced function's parameters accept wildcard patterns as arguments

Using the example of Get-Item:

  • You can use Get-Help Get-Item -Full and then browse the entire topic for Accept wildcard characters? lines.

  • To query wildcard support for a given parameter, you can use:
    Get-Help Get-Item -Parameter Path and read the description - however, due to a separate issue, most cmdlets do not allow programmatic discovery of wildcard-supporting parameters.

Neither option is convenient.

Perhaps the syntax diagrams could be enhanced with symbols that reflect support for wildcard patterns?

Something along the lines of (these are mere examples; the idea is to be concise):

-Param* <type>

Applied to the Get-Item example:

Get-Item [-Path*] <string[]> [-Filter <string>] [-Include* <string[]>] [-Exclude* <string[]>] [-Force] [-Credential <pscredential>] [-Stream <string[]>] [<CommonParameters>]

Get-Item -LiteralPath <string[]> [-Filter <string>] [-Include* <string[]>] [-Exclude* <string[]>] [-Force] [-Credential <pscredential>] [-Stream <string[]>] [<CommonParameters>]

Note: While the -Filter parameter supports wildcards for the FileSystem provider, this may not be true for all providers - what the -Filter parameter accepts is entirely provider-dependent; case in point: the wildcard-pattern language supported by the FileSystem provider differs (is less powerful than) PowerShell's wildcard-pattern language.

Written as of PowerShell Core v6.0.0-beta.6.

Activity

  1. changed the title [-]Suggestion: make it easier to discover which cmdlet parameters accept wildcard patterns[/-] [+]Suggestion: make it easier to discover which cmdlet parameters accept wildcard patterns, via the syntax diagram[/+] on Aug 31, 2017
  2. iSazonov commented on Aug 31, 2017

    @iSazonov
    Collaborator

    Get-Item [-Path] <wildcard string[]>

  3. ThomasNieto commented on Aug 5, 2020

    @ThomasNieto
    Contributor

    While I was working on #4716 I implemented this issue. Its been a while since this issue was updated is this something we still want to do?

    NAME
        Get-Item
    
    SYNOPSIS
        Gets the item at the specified location.
    
    
    SYNTAX
        Get-Item [-Stream <wildcard String[]>] [-Credential <wildcard PSCredential>] [-Exclude <wildcard String[]>]
        [-Filter <wildcard String>] [-Force] [-Include <wildcard String[]>] -LiteralPath <wildcard String[]>
        [<CommonParameters>]
    
        Get-Item [-Path] <wildcard String[]> [-Stream <wildcard String[]>] [-Credential <wildcard PSCredential>] [-Exclude
        <wildcard String[]>] [-Filter <wildcard String>] [-Force] [-Include <wildcard String[]>] [<CommonParameters>]
  4. vexx32 commented on Aug 5, 2020

    @vexx32
    Collaborator

    Nice! I'm torn kind of between that (very clear) and Michael Klement (@mklement0)'s original idea (very concise).

    Maybe some kind of in between?

    -ParamName <String>* / -ParamName <String[]>*

    I'm hesitant to put the indicator inside the angle brackets, as that kind of implies it's somehow part of the type itself, and we don't actually have a StringWildcard type ^^

    Were this pre-PS v1.0 I might actually suggest just drop the attribute and just have all wildcard parameters use WildcardPattern as the actual input type; clear, saves a conversion later, etc. But there are internal APIs that probably would need overloads added, it's not a straightforward switch over. And you can't get the original string back out of those if you do need it, it'd need more changes than it's probably worth at this point.

  5. ThomasNieto commented on Aug 5, 2020

    @ThomasNieto
    Contributor

    Rain Sallow (/u/ta11ow) (@vexx32) I like the concise version as well. Having wildcard spelled out is easy to understand but can get overwhelming when every parameter has it enabled. Maybe we can use your suggestion with a legend below the syntax.

    NAME
        Get-Item
    
    SYNOPSIS
        Gets the item at the specified location.
    
    
    SYNTAX
        Get-Item [-Stream <String[]>*] [-Credential <PSCredential>*] [-Exclude <String[]>*]
        [-Filter <String>*] [-Force] [-Include <String[]>*] -LiteralPath <String[]>*
        [<CommonParameters>]
    
        Get-Item [-Path] <String[]>* [-Stream <String[]>*] [-Credential <PSCredential>*] [-Exclude
        <String[]>*] [-Filter <String>*] [-Force] [-Include <String[]>*] [<CommonParameters>]
    
        * Denotes wildcard support
  6. vexx32 commented on Aug 5, 2020

    @vexx32
    Collaborator

    I like it, that does hit both points very effectively! 🙂

  7. ThomasNieto commented on Aug 5, 2020

    @ThomasNieto
    Contributor

    That does bring up something with the syntax view that is confusing for new users. They don't know what the symbols mean. This might need to be in its own issue but maybe we should add an optional legend view describing each symbol.

    NAME
        Get-Item
    
    SYNOPSIS
        Gets the item at the specified location.
    
    
    SYNTAX
        Get-Item [-Stream <String[]>*] [-Credential <PSCredential>*] [-Exclude <String[]>*]
        [-Filter <String>*] [-Force] [-Include <String[]*>] -LiteralPath <String[]*>
        [<CommonParameters>]
    
        Get-Item [-Path] <String[]*> [-Stream <String[]*>] [-Credential <PSCredential>*] [-Exclude
        <String[]*>] [-Filter <String>*] [-Force] [-Include <String[]*>] [<CommonParameters>]
    
    LEGEND
        [-Parameter]    Positional parameter, does not require parameter name
        <>              Type of object accepted
        []              Parameter accepts multiple values
        {Item | Item2}  Valid parameter values
        *               Wildcard Support
  8. iSazonov commented on Aug 5, 2020

    @iSazonov
    Collaborator

    Shouldn't we stick to a stricter normalized notation?
    In notations, this '*' sign has a special meaning that can be misleading in the proposal.

  9. vexx32 commented on Aug 5, 2020

    @vexx32
    Collaborator

    What do you mean exactly Ilya (@iSazonov)? 🤔

  10. mklement0 commented on Aug 5, 2020

    @mklement0
    ContributorAuthor

    Ilya (@iSazonov), this is about a format that is human-friendly, not a strict notation for machine parsing.

    While there is some potential for confusion with the BNF-style * duplication symbol (0 or more times) - given that we've borrowed the notation for optional elements from there ([...], which already clashes with our type-literal notation) - I don't think something like <String>* would be a problem in practice, especially if we also offer a legend, as proposed.

    Speaking of: For brevity, the legend should probably only be shown with -Full and -Detailed.

  11. iSazonov commented on Aug 6, 2020

    @iSazonov
    Collaborator

    I feel we need a strong notation to overcome limitations in definition of parameter sets. Syntax diagram would follow the notation.

  12. ThomasNieto commented on Aug 6, 2020

    @ThomasNieto
    Contributor

    Ilya (@iSazonov) do you have an example of what that might look like?

  13. iSazonov commented on Aug 7, 2020

    @iSazonov
    Collaborator

    Thomas Nieto (@ThomasNieto) Perhaps we need something like BNF-style. Perhaps there is a better option. Today it is easy to define 2-3 parameter sets with 1 level optional parameters after mandatory ones. But creating more complex parameters sets turns into a big headache. Alternative - dynamic parameters but it does not allow discovering and syntax diagram generating.

  14. microsoft-github-policy-service commented on Nov 16, 2023

    @microsoft-github-policy-service
    Contributor

    This issue has not had any activity in 6 months, if this is a bug please try to reproduce on the latest version of PowerShell and reopen a new issue and reference this issue if this is still a blocker for you.

  15. microsoft-github-policy-service commented on Nov 16, 2023

    @microsoft-github-policy-service
    Contributor

    This issue has not had any activity in 6 months, if this is a bug please try to reproduce on the latest version of PowerShell and reopen a new issue and reference this issue if this is still a blocker for you.

  16. microsoft-github-policy-service commented on Nov 16, 2023

    @microsoft-github-policy-service
    Contributor

    This issue has not had any activity in 6 months, if this is a bug please try to reproduce on the latest version of PowerShell and reopen a new issue and reference this issue if this is still a blocker for you.

  17. microsoft-github-policy-service commented on Nov 23, 2023

    @microsoft-github-policy-service
    Contributor

    This issue has been marked as "No Activity" as there has been no activity for 6 months. It has been closed for housekeeping purposes.

  18. cpdaatc commented on Sep 5, 2025

    @cpdaatc

    I like it, that does hit both points very effectively! 🙂

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

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

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions