If you want to find all matches for a regexp in part of the buffer
and replace them, the most flexible way is to write an explicit loop
using re-search-forward
and replace-match
, like this:
(while (re-search-forward "foo[ \t]+bar" nil t) (replace-match "foobar"))
See Replacing the Text that Matched, for a
description of replace-match
.
It may be more convenient to limit the replacements to a specific
region. The function replace-regexp-in-region
does that.
This function replaces all the occurrences of regexp with
replacement in the region of buffer text between start and
end; start defaults to position of point, and end
defaults to the last accessible position of the buffer. The search
for regexp is case-sensitive, and replacement is inserted
without changing its letter-case. The replacement string can
use the same special elements starting with ‘\’ as
replace-match
does. The function returns the number of
replaced occurrences, or nil
if regexp is not found. The
function preserves the position of point.
(replace-regexp-in-region "foo[ \t]+bar" "foobar")
This function works similarly to replace-regexp-in-region
,
but searches for, and replaces, literal strings instead of
regular expressions.
Emacs also has special functions for replacing matches in a string.
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, and the returned value
does not include the first start characters of string.
To get the whole transformed string, concatenate the first
start characters of string with the return value.
This function uses replace-match
to do the replacement, and it
passes the optional arguments fixedcase, literal and
subexp along to replace-match
.
Instead of a string, rep can be a function. In that case,
replace-regexp-in-string
calls 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-match
as the
replacement string. The match data at this point are the result
of matching regexp against a substring of string.
This function replaces all occurrences of from-string with to-string in in-string and returns the result. It may return one of its arguments unchanged, a constant string or a new string. Case is significant, and text properties are ignored.
If you want to write a command along the lines of query-replace
,
you can use perform-replace
to do the work.
This function is the guts of query-replace
and 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 the optional argument backward is
non-nil
, the search starts at end and goes backward.)
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, (function . data)
, 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
perform-replace
binds case-fold-search
to nil
, and
it uses the replacements without altering their case.
Normally, the keymap query-replace-map
defines the possible
user responses for queries. The argument map, if
non-nil
, specifies a keymap to use instead of
query-replace-map
.
Non-nil
region-noncontiguous-p means that the region
between start and end is composed of noncontiguous pieces.
The most common example of this is a rectangular region, where the
pieces are separated by newline characters.
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-re-search-function
and
replace-search-function
. The former is called when the
argument regexp-flag is non-nil
, the latter when it is
nil
.
This variable holds a special keymap that defines the valid user
responses for perform-replace
and the commands that use it, as
well as y-or-n-p
and map-y-or-n-p
. This map is unusual
in two ways:
read-key-sequence
to get the input; instead, they read a single
event and look it up “by hand”.
Here are the meaningful bindings for query-replace-map
.
Several of them are meaningful only for query-replace
and
friends.
act
Do take the action being considered—in other words, “yes”.
skip
Do not take action for this question—in other words, “no”.
exit
Answer this question “no”, and give up on the entire series of questions, assuming that the answers will be “no”.
exit-prefix
Like exit
, but add the key that was pressed to
unread-command-events
(see Miscellaneous Event Input Features).
act-and-exit
Answer this question “yes”, and give up on the entire series of questions, assuming that subsequent answers will be “no”.
act-and-show
Answer this question “yes”, but show the results—don’t advance yet to the next question.
automatic
Answer this question and all subsequent questions in the series with “yes”, without further user interaction.
backup
Move back to the previous place that a question was asked about.
undo
Undo last replacement and move back to the place where that replacement was performed.
undo-all
Undo all replacements and move back to the place where the first replacement was performed.
edit
Enter a recursive edit to deal with this question—instead of any other action that would normally be taken.
edit-replacement
Edit the replacement for this question in the minibuffer.
delete-and-edit
Delete the text being considered, then enter a recursive edit to replace it.
recenter
scroll-up
scroll-down
scroll-other-window
scroll-other-window-down
Perform the specified window scroll operation, then ask the same
question again. Only y-or-n-p
and related functions use this
answer.
quit
Perform a quit right away. Only y-or-n-p
and related functions
use this answer.
help
Display some help, then ask again.
This variable holds a keymap that extends query-replace-map
by
providing additional key bindings that are useful in multi-buffer
replacements. The additional bindings are:
automatic-all
Answer this question and all subsequent questions in the series with “yes”, without further user interaction, for all remaining buffers.
exit-current
Answer this question “no”, and give up on the entire series of questions for the current buffer. Continue to the next buffer in the sequence.
This variable specifies a function that perform-replace
calls
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 Searching for Strings).
This variable specifies a function that perform-replace
calls
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 Regular Expression Searching).