diff options
Diffstat (limited to 'devdocs/elisp/replacing-match.html')
| -rw-r--r-- | devdocs/elisp/replacing-match.html | 15 |
1 files changed, 15 insertions, 0 deletions
diff --git a/devdocs/elisp/replacing-match.html b/devdocs/elisp/replacing-match.html new file mode 100644 index 00000000..776076fc --- /dev/null +++ b/devdocs/elisp/replacing-match.html @@ -0,0 +1,15 @@ + <h4 class="subsection">Replacing the Text that Matched</h4> <p>This function replaces all or part of the text matched by the last search. It works by means of the match data. </p> <dl> <dt id="replace-match">Function: <strong>replace-match</strong> <em>replacement &optional fixedcase literal string subexp</em> +</dt> <dd> +<p>This function performs a replacement operation on a buffer or string. </p> <p>If you did the last search in a buffer, you should omit the <var>string</var> argument or specify <code>nil</code> for it, and make sure that the current buffer is the one in which you performed the last search. Then this function edits the buffer, replacing the matched text with <var>replacement</var>. It leaves point at the end of the replacement text. </p> <p>If you performed the last search on a string, pass the same string as <var>string</var>. Then this function returns a new string, in which the matched text is replaced by <var>replacement</var>. </p> <p>If <var>fixedcase</var> is non-<code>nil</code>, then <code>replace-match</code> uses the replacement text without case conversion; otherwise, it converts the replacement text depending upon the capitalization of the text to be replaced. If the original text is all upper case, this converts the replacement text to upper case. If all words of the original text are capitalized, this capitalizes all the words of the replacement text. If all the words are one-letter and they are all upper case, they are treated as capitalized words rather than all-upper-case words. </p> <p>If <var>literal</var> is non-<code>nil</code>, then <var>replacement</var> is inserted exactly as it is, the only alterations being case changes as needed. If it is <code>nil</code> (the default), then the character ‘<samp>\</samp>’ is treated specially. If a ‘<samp>\</samp>’ appears in <var>replacement</var>, then it must be part of one of the following sequences: </p> <dl compact> <dt>‘<samp>\&</samp>’</dt> <dd> + <p>This stands for the entire text being replaced. </p> </dd> <dt>‘<samp>\<var>n</var></samp>’, where <var>n</var> is a digit</dt> <dd> + <p>This stands for the text that matched the <var>n</var>th subexpression in the original regexp. Subexpressions are those expressions grouped inside ‘<samp>\(…\)</samp>’. If the <var>n</var>th subexpression never matched, an empty string is substituted. </p> </dd> <dt>‘<samp>\\</samp>’</dt> <dd> + <p>This stands for a single ‘<samp>\</samp>’ in the replacement text. </p> </dd> <dt>‘<samp>\?</samp>’</dt> <dd><p>This stands for itself (for compatibility with <code>replace-regexp</code> and related commands; see <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Regexp-Replace.html#Regexp-Replace">Regexp Replace</a> in <cite>The GNU Emacs Manual</cite>). </p></dd> </dl> <p>Any other character following ‘<samp>\</samp>’ signals an error. </p> <p>The substitutions performed by ‘<samp>\&</samp>’ and ‘<samp>\<var>n</var></samp>’ occur after case conversion, if any. Therefore, the strings they substitute are never case-converted. </p> <p>If <var>subexp</var> is non-<code>nil</code>, that says to replace just subexpression number <var>subexp</var> of the regexp that was matched, not the entire match. For example, after matching ‘<samp>foo \(ba*r\)</samp>’, calling <code>replace-match</code> with 1 as <var>subexp</var> means to replace just the text that matched ‘<samp>\(ba*r\)</samp>’. </p> +</dd> +</dl> <dl> <dt id="match-substitute-replacement">Function: <strong>match-substitute-replacement</strong> <em>replacement &optional fixedcase literal string subexp</em> +</dt> <dd><p>This function returns the text that would be inserted into the buffer by <code>replace-match</code>, but without modifying the buffer. It is useful if you want to present the user with actual replacement result, with constructs like ‘<samp>\<var>n</var></samp>’ or ‘<samp>\&</samp>’ substituted with matched groups. Arguments <var>replacement</var> and optional <var>fixedcase</var>, <var>literal</var>, <var>string</var> and <var>subexp</var> have the same meaning as for <code>replace-match</code>. </p></dd> +</dl><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br> + <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Replacing-Match.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Replacing-Match.html</a> + </p> +</div> |