Next: Replacement and Lax Matches, Previous: Unconditional Replace, Up: Replace [Contents][Index]

#### 15.10.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 regular expression pattern (see Regexps).

`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 starting from 1, stands for whatever matched the dth parenthesized grouping in regexp. (This is called a “back reference”.) ‘`\#`’ 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 in The Emacs Lisp Reference Manual). 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

Next: Replacement and Lax Matches, Previous: Unconditional Replace, Up: Replace [Contents][Index]