GNU Info

(elisp)Search and Replace

---

Next: Match Data Prev: POSIX Regexps Up: Searching and Matching

---

Enter node , (file) or (file)node

Search and Replace
==================

 - Function: perform-replace from-string replacements start end
          query-flag regexp-flag delimited-flag &optional repeat-count
          map
     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', point is used instead, and the buffer's end 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 cyclicly 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 the case of them.

     Normally, the keymap `query-replace-map' defines the possible user
     responses for queries.  The argument MAP, if non-`nil', is a
     keymap to use instead of `query-replace-map'.

 - Variable: query-replace-map
     This variable holds a special keymap that defines the valid user
     responses for `query-replace' and related functions, as well as
     `y-or-n-p' and `map-y-or-n-p'.  It 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."

`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.

`delete-and-edit'
     Delete the text being considered, then enter a recursive edit to
     replace it.

`recenter'
     Redisplay and center the window, then ask the same question again.

`quit'
     Perform a quit right away.  Only `y-or-n-p' and related functions
     use this answer.

`help'
     Display some help, then ask again.