elisp: Search and Replace
33.7 Search and Replace
=======================
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
‘re-search-forward’ and ‘replace-match’, like this:
(while (re-search-forward "foo[ \t]+bar" nil t)
(replace-match "foobar"))
Replacing the Text that Matched Replacing Match, for a
description of ‘replace-match’.
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.
-- Function: replace-regexp-in-string regexp rep string &optional
fixedcase literal subexp start
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-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.
If you want to write a command along the lines of ‘query-replace’,
you can use ‘perform-replace’ to do the work.
-- Function: perform-replace from-string replacements query-flag
regexp-flag delimited-flag &optional repeat-count map start
end
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 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’.
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’.
-- Variable: query-replace-map
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:
• 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-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’ (Event Input Misc).
‘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.
‘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.
-- Variable: multi-query-replace-map
This variable holds a keymap that extends ‘query-replace-map’ by
providing additional keybindings 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.
-- Variable: replace-search-function
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’ (String
Search).
-- Variable: replace-re-search-function
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’ (
Regexp Search).
Info Catalog
elisp: Match Data
elisp: Searching and Matching
elisp: Standard Regexps