Function: query-replace
query-replace is an interactive and byte-compiled function defined in
replace.el.gz.
Signature
(query-replace FROM-STRING TO-STRING &optional DELIMITED START END BACKWARD REGION-NONCONTIGUOUS-P)
Documentation
Replace some occurrences of FROM-STRING with TO-STRING.
As each match is found, the user must type a character saying
what to do with it. Type SPC or y to replace the match,
DEL or n to skip and go to the next match. For more directions,
type <f1> (help-command) at that time.
In Transient Mark mode, if the mark is active, operate on the contents of the region. Otherwise, operate from point to the end of the buffer's accessible portion.
In interactive use, the prefix arg (non-nil DELIMITED in non-interactive use), means replace only matches surrounded by word boundaries. A negative prefix arg means replace backward.
Use M-n (next-history-element) to pull the last incremental search string to the minibuffer
that reads FROM-STRING, or invoke replacements from
incremental search with a key sequence like \C-s C-s M-%
to use its current search string as the string to replace.
Matching is independent of case if both case-fold-search
and search-upper-case are non-nil and FROM-STRING has no
uppercase letters; if search-upper-case is nil, then
whether matching ignores case depends on case-fold-search
regardless of whether there are uppercase letters in FROM-STRING.
Replacement transfers the case pattern of the old text to the
new text, if both case-fold-search and case-replace are
non-nil and FROM-STRING has no uppercase letters.
(Transferring the case pattern means that if the old text
matched is all caps, or all of its words are capitalized, then its
replacement is respectively upcased or capitalized. For more
details about this, see replace-match.)
Ignore read-only matches if query-replace-skip-read-only is non-nil,
ignore hidden matches if search-invisible is nil, and ignore more
matches using isearch-filter-predicate.
If replace-lax-whitespace is non-nil, a space or spaces in the string
to be replaced will match a sequence of whitespace chars defined by the
regexp in search-whitespace-regexp.
If replace-char-fold is non-nil, matching uses character folding,
i.e. it ignores diacritics and other differences between equivalent
character strings.
Fourth and fifth arg START and END specify the region to operate on.
Arguments FROM-STRING, TO-STRING, DELIMITED, START, END, BACKWARD, and
REGION-NONCONTIGUOUS-P are passed to perform-replace (which see).
(TO-STRING is passed to perform-replace as REPLACEMENTS and
DELIMITED is passed as DELIMITED-FLAG.)
To customize possible responses, change the bindings in query-replace-map.
Probably introduced at or before Emacs version 1.3.
Key Bindings
Source Code
;; Defined in /usr/src/emacs/lisp/replace.el.gz
(defun query-replace (from-string to-string &optional delimited start end backward region-noncontiguous-p)
"Replace some occurrences of FROM-STRING with TO-STRING.
As each match is found, the user must type a character saying
what to do with it. Type SPC or `y' to replace the match,
DEL or `n' to skip and go to the next match. For more directions,
type \\[help-command] at that time.
In Transient Mark mode, if the mark is active, operate on the contents
of the region. Otherwise, operate from point to the end of the buffer's
accessible portion.
In interactive use, the prefix arg (non-nil DELIMITED in
non-interactive use), means replace only matches surrounded by
word boundaries. A negative prefix arg means replace backward.
Use \\<minibuffer-local-map>\\[next-history-element] \
to pull the last incremental search string to the minibuffer
that reads FROM-STRING, or invoke replacements from
incremental search with a key sequence like \\`C-s C-s M-%'
to use its current search string as the string to replace.
Matching is independent of case if both `case-fold-search'
and `search-upper-case' are non-nil and FROM-STRING has no
uppercase letters; if `search-upper-case' is nil, then
whether matching ignores case depends on `case-fold-search'
regardless of whether there are uppercase letters in FROM-STRING.
Replacement transfers the case pattern of the old text to the
new text, if both `case-fold-search' and `case-replace' are
non-nil and FROM-STRING has no uppercase letters.
\(Transferring the case pattern means that if the old text
matched is all caps, or all of its words are capitalized, then its
replacement is respectively upcased or capitalized. For more
details about this, see `replace-match'.)
Ignore read-only matches if `query-replace-skip-read-only' is non-nil,
ignore hidden matches if `search-invisible' is nil, and ignore more
matches using `isearch-filter-predicate'.
If `replace-lax-whitespace' is non-nil, a space or spaces in the string
to be replaced will match a sequence of whitespace chars defined by the
regexp in `search-whitespace-regexp'.
If `replace-char-fold' is non-nil, matching uses character folding,
i.e. it ignores diacritics and other differences between equivalent
character strings.
Fourth and fifth arg START and END specify the region to operate on.
Arguments FROM-STRING, TO-STRING, DELIMITED, START, END, BACKWARD, and
REGION-NONCONTIGUOUS-P are passed to `perform-replace' (which see).
\(TO-STRING is passed to `perform-replace' as REPLACEMENTS and
DELIMITED is passed as DELIMITED-FLAG.)
To customize possible responses, change the bindings in `query-replace-map'."
(declare (interactive-args
(start (use-region-beginning))
(end (use-region-end))
(region-noncontiguous-p (use-region-noncontiguous-p))))
(interactive
(let ((common
(query-replace-read-args
(concat "Query replace"
(if current-prefix-arg
(if (eq current-prefix-arg '-) " backward" " word")
"")
(if (use-region-p) " in region" ""))
nil)))
(list (nth 0 common) (nth 1 common) (nth 2 common)
;; These are done separately here
;; so that command-history will record these expressions
;; rather than the values they had this time.
(use-region-beginning) (use-region-end)
(nth 3 common)
(use-region-noncontiguous-p))))
(perform-replace from-string to-string t nil delimited nil nil start end backward region-noncontiguous-p))