Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
mklement0 opened this issue Feb 5, 2020 · 1 comment
Labels

Comments

@mklement0
Copy link
Contributor

@mklement0 mklement0 commented Feb 5, 2020

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

@sdwheeler

This comment has been minimized.

Copy link
Collaborator

@sdwheeler sdwheeler commented Feb 5, 2020

PR submissions would be helpful.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
2 participants
You can’t perform that action at this time.