Clarify the - limited - usefulness of `--%`, the stop-parsing token when used with PowerShell commands rather than native programs

[mklement0]

Type of issue

Missing information

Feedback

Ultimately, use of --% only makes sense when calling native (external) programs.

• Direct use of --% with native programs is by far the most common use case.

• The only scenario in which using --% when calling PowerShell commands makes sense is to relay a raw argument list to a native program, using splatting.

  • In other words: only PowerShell commands that are wrappers for external-programs can meaningfully support --%, where anything following --% is to be passed through to the external program as if --% had been used in direct invocation of said program.

---

Currently:

• about_Parsing makes no mention of the potential use of --% for indirect, PowerShell command-mediated calls to external programs.

• about_Special_Characters currently uses a PowerShell command incidentally in an effort to illustrate --%'s behavior, in a manner that is likely to cause confusion (see To avoid conceptual confusion, do not use a *PowerShell function* to demonstrate how --%, the stop-parsing token, works *fundamentally* #10889).

---

Here's an example of a PowerShell function acting as a wrapper for a native program:

function foo {
  $env:SOMEVAR = 1
  # Whatever follows --% in the invocation is captured in a *single* argument, $args[1]
  Write-Verbose -Verbose "`$arg[1]: «$($args[1])»"
  # Note: @args is needed for --% to be relayed properly
  cmd /c echo @args
  $env:SOMEVAR = $null 
}

# Invoke with --%
foo --% a( "x< %SOMEVAR%

Output:

VERBOSE: $arg[1]: «a( "x< %SOMEVAR%»
 a( "x< 1

Note:

• From the foo function's perspective, whatever follows --% is passed as a single, verbatim positional argument, in $args[1], as the verbose output demonstrates.

• It is splatting that enables relaying this verbatim content to the native program, relying on splatting recognizing the array element --% ($args[0]) as the stop-parsing token.

  • Caveat: If that element happens to be situationally [psobject]-wrapped, this logic does not work - see Splatting with arrays containing --%, the stop-parsing token, doesn't work if the array element containing that token happens to be [psobject]-wrapped PowerShell/PowerShell#21260.

Page URL

https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_parsing?view=powershell-7.5#the-stop-parsing-token

Content source URL

https://github.com/MicrosoftDocs/PowerShell-Docs/blob/main/reference/7.5/Microsoft.PowerShell.Core/About/about_Parsing.md

Author

@sdwheeler

Document Id

be402df0-6f04-9a29-5410-c54be1c11926

[sdwheeler]

@mklement0 I am making the change you suggested in #10889.

Are you saying that we need to add the PowerShell-wrapped example to about_Parsing or just add a statement about limiting the use of --% to native commands?

[mklement0]

Thanks, @sdwheeler.

After making the change proposed in #10898, I feel there's less of a need to spell out a full example in about_Parsing.

However, I suggest at least mentioning that with PowerShell commands --% only makes sense for wrapper commands for native programs, where $args (or a sub-array of it) is relayed to a native program via splatting (e.g., @args) and that the PowerShell command itself does see the --%, with all subsequent arguments collected in a single, final, string argument. It is a useful - albeit probably rare in practice - scenario.