If you want to find all matches for a regexp in part of the buffer,
and replace them, the best way is to write an explicit loop using
replace-match, like this:
(while (re-search-forward "foo[ \t]+bar" nil t) (replace-match "foobar"))
See Replacing the Text that Matched, for a
However, replacing matches in a string is more complex, especially if you want to do it efficiently. So Emacs provides a function to do this.
This function copies string and searches it for matches for regexp, and replaces them with rep. It returns the modified copy. If start is non-
nil, the search for matches starts at that index in string, so matches starting before that index are not changed.
This function uses
replace-matchto do the replacement, and it passes the optional arguments fixedcase, literal and subexp along to
Instead of a string, rep can be a function. In that case,
replace-regexp-in-stringcalls rep for each match, passing the text of the match as its sole argument. It collects the value rep returns and passes that to
replace-matchas the replacement string. The match-data at this point are the result of matching regexp against a substring of string.
If you want to write a command along the lines of
you can use
perform-replace to do the work.
This function is the guts of
query-replaceand related commands. It searches for occurrences of from-string in the text between positions start and end and replaces some or all of them. If start is
nil(or omitted), point is used instead, and the end of the buffer's accessible portion is used for end.
If query-flag is
nil, it replaces all occurrences; otherwise, it asks the user what to do about each one.
If regexp-flag is non-
nil, then from-string is considered a regular expression; otherwise, it must match literally. If delimited-flag is non-
nil, then only replacements surrounded by word boundaries are considered.
The argument replacements specifies what to replace occurrences with. If it is a string, that string is used. It can also be a list of strings, to be used in cyclic order.
If replacements is a cons cell,
), this means to call function after each match to get the replacement text. This function is called with two arguments: data, and the number of replacements already made.
If repeat-count is non-
nil, it should be an integer. Then it specifies how many times to use each of the strings in the replacements list before advancing cyclically to the next one.
If from-string contains upper-case letters, then
nil, and it uses the
replacementswithout altering the case of them.
Normally, the keymap
query-replace-mapdefines the possible user responses for queries. The argument map, if non-
nil, specifies a keymap to use instead of
This function uses one of two functions to search for the next occurrence of from-string. These functions are specified by the values of two variables:
replace-search-function. The former is called when the argument regexp-flag is non-
nil, the latter when it is
This variable holds a special keymap that defines the valid user responses for
perform-replaceand the commands that use it, as well as
map-y-or-n-p. This map is unusual in two ways:
- The “key bindings” are not commands, just symbols that are meaningful to the functions that use this map.
- Prefix keys are not supported; each key binding must be for a single-event key sequence. This is because the functions don't use
read-key-sequenceto get the input; instead, they read a single event and look it up “by hand.”
Here are the meaningful “bindings” for
Several of them are meaningful only for
y-or-n-pand related functions use this answer.
This variable holds a keymap that extends
query-replace-mapby providing additional keybindings that are useful in multi-buffer replacements.
This variable specifies a function that
perform-replacecalls to search for the next string to replace. Its default value is
search-forward. Any other value should name a function of 3 arguments: the first 3 arguments of
search-forward(see String Search).
This variable specifies a function that
perform-replacecalls to search for the next regexp to replace. Its default value is
re-search-forward. Any other value should name a function of 3 arguments: the first 3 arguments of
re-search-forward(see Regexp Search).