Suggested improvements to how the -replace (replacement operator) is documented

[mklement0]

#4417 and #5415 show that it currently isn't easy to find the relevant information about the syntax of the <substitute> (replacement text / expression) operand:

• The link to the about_Regular_Expression topic at the bottom is generally easy to miss and feels like an afterthought.
• More importantly: Clicking on about_Regular_Expression is not conceptually obvious, given that the substitution operands are not regular expressions themselves, and the language used is a convention that .NET chose that applies in no other context than -replace.
• Finally, linking to the regex topic as a whole is not specific enough.

This could be helped as follows:

• Provide a link to the specific section inside about_Regular_Expressions
• in context
• of a - new - example commands that demonstrate the substitution syntax briefly.

Something like the following:

---

The <substitute> operand is allowed to contain placeholders that reference the results of the matching operation, such as $& to refer what was matched as a whole, and $1 to refer to the first capture group's match (use $$ to represent a literal $); e.g.:

"book" -replace 'b', '($&)'

(b)ook

For more examples and information about what other placeholders are supported, see
Substitutions in Regular Expressions.

---

Additionally, consider the following:

Conceptually, we have 3 fundamental forms of -replace, which are worth contrasting succinctly in the "Replacement Operator" section:

• With what the user intends to be string literals; to be able to do that, users need to know the following:

  • To treat the <original> operand as a literal (this name is confusing, incidentally), regex metachars. must be individually \-escaped, or [regex]::Escape() must be applied to the whole value.
  • To treat the <substitute> operand as a literal, $ chars. must be individually doubled, or .Replace('$', '$$') must be applied to the whole value.

• With a substitution string that contains placeholders that reference matching results (covered above).

• With a script block that allows fully dynamic substitutions.

  • This form is currently described in a separate section, which I suggest folding into the "Replacement Operator" section, so as to contrast these 3 fundamental forms directly.

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 50bd0dc3-279b-baea-5c19-823e0bc44534
• Version Independent ID: fe731c19-4f99-e680-f508-ec28126ac605
• Content: about_Comparison_Operators - PowerShell
• Content Source: reference/7.0/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md
• Product: powershell
• GitHub Login: @SteveL-MSFT
• Microsoft Alias: slee

[sdwheeler]

PR submissions would be helpful.