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

[mklement0]

^{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.

[iSazonov]

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

[ThomasNieto]

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>]

[vexx32]

Nice! I'm torn kind of between that (very clear) and @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.

[ThomasNieto]

@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

[vexx32]

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

[ThomasNieto]

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

[iSazonov]

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

[vexx32]

What do you mean exactly @iSazonov? 🤔

[mklement0]

@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.

[iSazonov]

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

[ThomasNieto]

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

[iSazonov]

@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.