Mention in-pipeline uses of `(...)`, the grouping operator

[mklement0]

Prerequisites

• Existing Issue: Search the existing issues for this repository. If there is an issue that fits your needs do not file a new one. Subscribe, react, or comment on that issue instead.
• Descriptive Title: Write the title for this issue as a short synopsis. If possible, provide context. For example, "Typo in Get-Foo cmdlet" instead of "Typo."
• Verify Version: If there is a mismatch between documentation and the behavior on your system, ensure that the version you are using is the same as the documentation. Check this box if they match or the issue you are reporting is not version specific.

Links

https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_Operators?view=powershell-7.4#grouping-operator--

Summary

(...) is not only necessary to change operation precedence in expressions and in order for commands to participate in expressions, it is also useful in pipelines, namely in the following scenarios:

• To force up-front collection of a command's output, so that subsequent object-by-object processing cannot interfere with the enumeration the command uses to produce its output.

  • An example is (Get-ChildItem ...) | Rename-Item -NewName { ... } - the (...) enclosure prevents the Get-ChildItem enumeration from being affected by the subsequent renaming.

  • Note: Strictly speaking, this is no longer necessary in PS Core, due to an implementation detail, but it applies to WinPS, and similar scenarios with other (potentially custom) cmdlets may exist.

• To force enumeration of a command's output, in case it (unexpectedly) outputs collections as a whole, instead of streaming elements one by one.

  • An example - again no longer directly applicable to PS Core, but other scenarios may exist - is to force ConvertFrom-Json to output the elements of a JSON array one by one (in WinPS, a single object of type [object[]] is output, (...) forces its enumeration):

    (ConvertFrom-Json '[1, 2]') | ForEach-Object { ... }
    

It's worth mentioning these scenarios, given that use of (...) in these cases is a concise technique that is a less verbose alternative to capturing command output in an aux. variable in a separate step.

Details

No response

Suggested Fix

No response