{"action":"opened","issue":{"url":"https://api.github.com/repos/PowerShell/PowerShell-Docs/issues/2416","repository_url":"https://api.github.com/repos/PowerShell/PowerShell-Docs","labels_url":"https://api.github.com/repos/PowerShell/PowerShell-Docs/issues/2416/labels{/name}","comments_url":"https://api.github.com/repos/PowerShell/PowerShell-Docs/issues/2416/comments","events_url":"https://api.github.com/repos/PowerShell/PowerShell-Docs/issues/2416/events","html_url":"https://github.com/PowerShell/PowerShell-Docs/issues/2416","id":321975790,"number":2416,"title":"Explain the features and syntax of the -replace operator's replacement operand ","user":{"login":"mklement0","id":588825,"avatar_url":"https://avatars2.githubusercontent.com/u/588825?v=4","gravatar_id":"","url":"https://api.github.com/users/mklement0","html_url":"https://github.com/mklement0","followers_url":"https://api.github.com/users/mklement0/followers","following_url":"https://api.github.com/users/mklement0/following{/other_user}","gists_url":"https://api.github.com/users/mklement0/gists{/gist_id}","starred_url":"https://api.github.com/users/mklement0/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mklement0/subscriptions","organizations_url":"https://api.github.com/users/mklement0/orgs","repos_url":"https://api.github.com/users/mklement0/repos","events_url":"https://api.github.com/users/mklement0/events{/privacy}","received_events_url":"https://api.github.com/users/mklement0/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":0,"created_at":"2018-05-10T15:32:44Z","updated_at":"2018-05-10T15:32:44Z","closed_at":null,"author_association":"CONTRIBUTOR","body":"PowerShell's `-replace` operator is based on the .NET `[regex]::Replace()` method, and the syntax of the replacement operand is currently not explained or linked to in [`about_Comparison_Operators`](https://github.com/PowerShell/PowerShell-Docs/blob/staging/reference/6/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md)\r\n\r\nNot only may users therefore miss out on referencing capture groups (e.g, `$1`) in the replacement operand, they may mistakenly assume that it is a _literal_ and be surprised when `$` chars. are subject to interpretation, notably a `$$` turning into a _single_ `$` (because _doubling_ `$` is what it takes to escape them).\r\n\r\n```powershell\r\nPS> 'foo' -replace 'foo', 'f$$'\r\nf$   # '$$' was interpreted as an *escaped* $\r\n```\r\n\r\nTo use an arbitrary value (supplied via variable whose value isn't known ahead of time) as the replacement operand, use the following:\r\n\r\n```powershell\r\nPS> $var = 'f$$'; 'foo' -replace 'foo', $var.Replace('$', '$$')\r\nf$$\r\n```\r\n\r\n`about_Comparison_Operators` should be updated to:\r\n\r\n* at least briefly mention the syntax and capabilities of the replacement operand\r\n* link to the .NET documentation at https://docs.microsoft.com/en-us/dotnet/standard/base-types/substitutions-in-regular-expressions\r\n* show the above technique for treating a replacement operand as a _literal_.\r\n\r\n\r\nVersion(s) of document impacted\r\n------------------------------\r\n- [x] Impacts 6.1 document\r\n- [x] Impacts 6.0 document\r\n- [x] Impacts 5.1 document\r\n- [x] Impacts 5.0 document\r\n- [x] Impacts 4.0 document\r\n- [x] Impacts 3.0 document\r\n\r\n"}}
{"actor":{"display_login":"mklement0"}}