Function: `replace-regexp`

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

Signature

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

Documentation

Replace things after point matching REGEXP with TO-STRING.

Preserve case in each match if case-replace and case-fold-search are non-nil and REGEXP has no uppercase letters.

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

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.

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.

Arguments BACKWARD and REGION-NONCONTIGUOUS-P are passed to perform-replace (which see).

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.
\? lets you edit the replacement text in the minibuffer
at the given position for each replacement.

In interactive calls, the replacement text may contain \, followed by a Lisp expression used as part of the replacement text. Inside of that expression, \& is a string denoting the whole match, \N a partial match, \#& and \#N the respective numeric values from string-to-number, and \# itself for replace-count, the number of replacements occurred so far, starting from zero.

If your Lisp expression is an identifier and the next letter in the replacement string would be interpreted as part of it, you can wrap it with an expression like \,(or \#). Incidentally, for this particular case you may also enter \# in the replacement text directly.

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.

Use M-n (next-history-element) to pull the last incremental search regexp to the minibuffer that reads REGEXP.

This function is usually the wrong thing to use in a Lisp program. What you probably want is a loop like this:
(while (re-search-forward REGEXP nil t)
(replace-match TO-STRING nil nil))
which will run faster and will not set the mark or print anything.

View in manual

Probably introduced at or before Emacs version 21.1.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/replace.el.gz
(defun replace-regexp (regexp to-string &optional delimited start end backward region-noncontiguous-p)
  "Replace things after point matching REGEXP with TO-STRING.
Preserve case in each match if `case-replace' and `case-fold-search'
are non-nil and REGEXP has no uppercase letters.

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'

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.

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.

Arguments BACKWARD and REGION-NONCONTIGUOUS-P are passed
to `perform-replace' (which see).

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.
`\\?' lets you edit the replacement text in the minibuffer
at the given position for each replacement.

In interactive calls, the replacement text may contain `\\,'
followed by a Lisp expression used as part of the replacement
text.  Inside of that expression, `\\&' is a string denoting the
whole match, `\\N' a partial match, `\\#&' and `\\#N' the respective
numeric values from `string-to-number', and `\\#' itself for
`replace-count', the number of replacements occurred so far, starting
from zero.

If your Lisp expression is an identifier and the next letter in
the replacement string would be interpreted as part of it, you
can wrap it with an expression like `\\,(or \\#)'.  Incidentally,
for this particular case you may also enter `\\#' in the
replacement text directly.

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.

Use \\<minibuffer-local-map>\\[next-history-element] \
to pull the last incremental search regexp to the minibuffer
that reads REGEXP.

This function is usually the wrong thing to use in a Lisp program.
What you probably want is a loop like this:
  (while (re-search-forward REGEXP nil t)
    (replace-match TO-STRING nil nil))
which will run faster and will not set the mark or print anything."
  (declare (interactive-only
	    "use `re-search-forward' and `replace-match' instead.")
	   (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 "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)
	   (use-region-beginning) (use-region-end)
	   (nth 3 common)
	   (use-region-noncontiguous-p))))
  (perform-replace regexp to-string nil t delimited nil nil start end backward region-noncontiguous-p))

Function: replace-regexp

Signature

Documentation

Key Bindings

Source Code

Function: `replace-regexp`