20.9.2 Regexp Replacement

The M-x replace-string command replaces exact matches for a single string. The similar command M-x replace-regexp replaces any match for a specified pattern.

M-x replace-regexp <RET> regexp <RET> newstring <RET>

Replace every match for regexp with newstring.

In replace-regexp, the newstring need not be constant: it can refer to all or part of what is matched by the regexp. ‘\&’ in newstring stands for the entire match being replaced. ‘\d’ in newstring, where d is a digit, stands for whatever matched the dth parenthesized grouping in regexp. ‘\#’ refers to the count of replacements already made in this command, as a decimal number. In the first replacement, ‘\#’ stands for ‘0’; in the second, for ‘1’; and so on. For example,

     M-x replace-regexp <RET> c[ad]+r <RET> \&-safe <RET>

replaces (for example) ‘cadr’ with ‘cadr-safe’ and ‘cddr’ with ‘cddr-safe’.

     M-x replace-regexp <RET> \(c[ad]+r\)-safe <RET> \1 <RET>

performs the inverse transformation. To include a ‘\’ in the text to replace with, you must enter ‘\\’.

If you want to enter part of the replacement string by hand each time, use ‘\?’ in the replacement string. Each replacement will ask you to edit the replacement string in the minibuffer, putting point where the ‘\?’ was.

The remainder of this subsection is intended for specialized tasks and requires knowledge of Lisp. Most readers can skip it.

You can use Lisp expressions to calculate parts of the replacement string. To do this, write ‘\,’ followed by the expression in the replacement string. Each replacement calculates the value of the expression and converts it to text without quoting (if it's a string, this means using the string's contents), and uses it in the replacement string in place of the expression itself. If the expression is a symbol, one space in the replacement string after the symbol name goes with the symbol name, so the value replaces them both.

Inside such an expression, you can use some special sequences. ‘\&’ and ‘\n’ refer here, as usual, to the entire match as a string, and to a submatch as a string. n may be multiple digits, and the value of ‘\n’ is nil if subexpression n did not match. You can also use ‘\#&’ and ‘\#n’ to refer to those matches as numbers (this is valid when the match or submatch has the form of a numeral). ‘\#’ here too stands for the number of already-completed replacements.

Repeating our example to exchange ‘x’ and ‘y’, we can thus do it also this way:

     M-x replace-regexp <RET> \(x\)\|y <RET>
     \,(if \1 "y" "x") <RET>

For computing replacement strings for ‘\,’, the format function is often useful (see Formatting Strings). For example, to add consecutively numbered strings like ‘ABC00042’ to columns 73 to 80 (unless they are already occupied), you can use

     M-x replace-regexp <RET> ^.\{0,72\}$ <RET>
     \,(format "%-72sABC%05d" \& \#) <RET>