Function: `query-replace-regexp`

query-replace-regexp is an interactive and byte-compiled function defined in replace.el.gz.

Signature

(query-replace-regexp REGEXP TO-STRING &optional DELIMITED START END BACKWARD REGION-NONCONTIGUOUS-P)

Documentation

Replace some things after point matching REGEXP 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 C-h (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.

When invoked interactively, matching a newline with \n will not work; use C-q C-j instead. To match a tab character (\t), just press TAB.

Use M-n (next-history-element) to pull the last incremental search regexp to the minibuffer that reads REGEXP, or invoke replacements from incremental search with a key sequence like C-M-s C-M-s C-M-% to use its current search regexp as the regexp to replace.

Matching is independent of case if both case-fold-search and search-upper-case are non-nil and REGEXP 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 REGEXP. 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 REGEXP has no uppercase letters. (Transferring the case pattern means that if the old text matched is all caps, or capitalized, then its replacement is respectively upcased or capitalized.)

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-regexp-lax-whitespace is non-nil, a space or spaces in the regexp to be replaced will match a sequence of whitespace chars defined by the regexp in search-whitespace-regexp.

This function is not affected by replace-char-fold.

Third arg DELIMITED (prefix arg if interactive), if non-nil, means replace only matches surrounded by word boundaries. A negative prefix arg means replace backward.

Fourth and fifth arg START and END specify the region to operate on.

In TO-STRING, \& stands for whatever matched the whole of REGEXP, and \=\N (where N is a digit) stands for whatever matched the Nth \(...\) (1-based) in REGEXP. The \(...\) groups are counted from 1.
\? lets you edit the replacement text in the minibuffer
at the given position for each replacement.

In interactive calls, the replacement text can contain \, followed by a Lisp expression. Each replacement evaluates that expression to compute the replacement string. Inside of that expression, \& is a string denoting the whole match as a string, \N for a partial match, \#& and \#N for the whole or a partial match converted to a number with string-to-number, and \# itself for the number of replacements done so far (starting with zero).

If the replacement expression is a symbol, write a space after it to terminate it. One space there, if any, will be discarded.

When using those Lisp features interactively in the replacement text, TO-STRING is actually made a list instead of a string. Use C-x M-: (repeat-complex-command) after this command for details.

Arguments REGEXP, TO-STRING, DELIMITED, START, END, BACKWARD, and REGION-NONCONTIGUOUS-P are passed to perform-replace (which see).

Probably introduced at or before Emacs version 19.20.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/replace.el.gz
(defun query-replace-regexp (regexp to-string &optional delimited start end backward region-noncontiguous-p)
  "Replace some things after point matching REGEXP 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.

When invoked interactively, matching a newline with `\\n' will not work;
use `C-q C-j' instead.  To match a tab character (`\\t'), just press `TAB'.

Use \\<minibuffer-local-map>\\[next-history-element] \
to pull the last incremental search regexp to the minibuffer
that reads REGEXP, or invoke replacements from
incremental search with a key sequence like `C-M-s C-M-s C-M-%'
to use its current search regexp as the regexp to replace.

Matching is independent of case if both `case-fold-search'
and `search-upper-case' are non-nil and REGEXP 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 REGEXP.
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 REGEXP has no uppercase letters.  (Transferring the case pattern
means that if the old text matched is all caps, or capitalized,
then its replacement is respectively upcased or capitalized.)

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-regexp-lax-whitespace' is non-nil, a space or spaces in the regexp
to be replaced will match a sequence of whitespace chars defined by the
regexp in `search-whitespace-regexp'.

This function is not affected by `replace-char-fold'.

Third arg DELIMITED (prefix arg if interactive), if non-nil, means replace
only matches surrounded by word boundaries.  A negative prefix arg means
replace backward.

Fourth and fifth arg START and END specify the region to operate on.

In TO-STRING, `\\&' stands for whatever matched the whole of REGEXP,
and `\\=\\N' (where N is a digit) stands for whatever matched
the Nth `\\(...\\)' (1-based) in REGEXP.  The `\\(...\\)' groups are
counted from 1.
`\\?' lets you edit the replacement text in the minibuffer
at the given position for each replacement.

In interactive calls, the replacement text can contain `\\,'
followed by a Lisp expression.  Each
replacement evaluates that expression to compute the replacement
string.  Inside of that expression, `\\&' is a string denoting the
whole match as a string, `\\N' for a partial match, `\\#&' and `\\#N'
for the whole or a partial match converted to a number with
`string-to-number', and `\\#' itself for the number of replacements
done so far (starting with zero).

If the replacement expression is a symbol, write a space after it
to terminate it.  One space there, if any, will be discarded.

When using those Lisp features interactively in the replacement
text, TO-STRING is actually made a list instead of a string.
Use \\[repeat-complex-command] after this command for details.

Arguments REGEXP, TO-STRING, DELIMITED, START, END, BACKWARD, and
REGION-NONCONTIGUOUS-P are passed to `perform-replace' (which see)."
  (interactive
   (let ((common
	  (query-replace-read-args
	   (concat "Query replace"
		   (if current-prefix-arg
		       (if (eq current-prefix-arg '-) " backward" " word")
		     "")
		   " regexp"
		   (if (use-region-p) " in region" ""))
	   t)))
     (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.
	   (if (use-region-p) (region-beginning))
	   (if (use-region-p) (region-end))
	   (nth 3 common)
	   (if (use-region-p) (region-noncontiguous-p)))))
  (perform-replace regexp to-string t t delimited nil nil start end backward region-noncontiguous-p))

Function: query-replace-regexp

Signature

Documentation

Key Bindings

Source Code

Function: `query-replace-regexp`