tooldura

A replacement copied from an answer online often uses \1 instead of $1, and in JavaScript that produces a literal backslash followed by a one.

The split is historical. sed, Perl and Python's re.sub take backreferences with a backslash, because that is how the original Unix tools wrote them. JavaScript, .NET, PHP's preg_replace and most editors use the dollar form. Both conventions are older than anyone still arguing about them, and neither is going to change.

The practical consequence is that a replacement string is not portable even when the pattern is. A pattern moves between sed and JavaScript unchanged surprisingly often; its replacement almost never does. When something comes out full of backslashes and ones, this is why.

Groups are numbered by the position of their opening bracket, counting from the left. That includes nested ones, so ((a)(b)) makes three groups, not one.

The fragility is in editing. Add a group anywhere before the ones you already reference and every number after it shifts, while the replacement keeps pointing at the old positions. Nothing errors. The output is simply wrong, in a way that looks plausible enough to survive a quick glance.

Two habits avoid it. Use a non-capturing group, (?:…), whenever you need brackets only for grouping or alternation, so it never takes a number. And use named groups, (?<year>\d{4}) with $<year>, whenever the pattern is going to be edited more than once. Names survive renumbering, and a replacement that reads $<year>/$<month> tells the next person what it does, which $2/$1 never will.

A replacement string can reorder, duplicate and surround captured text. It cannot compute anything, and this is the ceiling people hit.

It cannot change case. sed has \U and \L, and JavaScript has no equivalent, so turning a captured word into uppercase is not expressible as a replacement string. It cannot do arithmetic, so incrementing a number in a matched line is out. It cannot look anything up, so mapping matched keys to values is out.

All three are ordinary work for the function form, where the second argument to replace is a function receiving the match and its groups and returning whatever you like. That is real code rather than a string, so it belongs in your editor rather than in a tool like this one.

The useful signal: if you find yourself wanting the replacement to make a decision, the replacement string is the wrong tool and no amount of cleverness in the pattern will fix it.

A substitution shows you the finished text, which is exactly the wrong thing to check first. A replacement that looks reasonable can be built from matches that are subtly wrong, and by the time you are reading the output the evidence is gone.

The order that catches mistakes is to get the matches right first, with the pattern alone, and only then write the replacement. The matches tell you what the regex actually selected, including the empty ones and the greedy quantifier that swallowed more than you intended.

Greediness is the usual culprit. Replacing <.+> intending to strip one tag will match from the first < to the last > on the line, taking everything in between. The lazy form, <.+?>, stops at the first >. In the output both look like something happened; only the match list shows which one happened.