diff options
Diffstat (limited to 'devdocs/elisp/search-and-replace.html')
| -rw-r--r-- | devdocs/elisp/search-and-replace.html | 54 |
1 files changed, 54 insertions, 0 deletions
diff --git a/devdocs/elisp/search-and-replace.html b/devdocs/elisp/search-and-replace.html new file mode 100644 index 00000000..ebcd0d38 --- /dev/null +++ b/devdocs/elisp/search-and-replace.html @@ -0,0 +1,54 @@ + <h3 class="section">Search and Replace</h3> <p>If you want to find all matches for a regexp in part of the buffer and replace them, the most flexible way is to write an explicit loop using <code>re-search-forward</code> and <code>replace-match</code>, like this: </p> <div class="example"> <pre class="example">(while (re-search-forward "foo[ \t]+bar" nil t) + (replace-match "foobar")) +</pre> +</div> <p>See <a href="replacing-match">Replacing the Text that Matched</a>, for a description of <code>replace-match</code>. </p> <p>It may be more convenient to limit the replacements to a specific region. The function <code>replace-regexp-in-region</code> does that. </p> <dl> <dt id="replace-regexp-in-region">Function: <strong>replace-regexp-in-region</strong> <em>regexp replacement &optional start end</em> +</dt> <dd> +<p>This function replaces all the occurrences of <var>regexp</var> with <var>replacement</var> in the region of buffer text between <var>start</var> and <var>end</var>; <var>start</var> defaults to position of point, and <var>end</var> defaults to the last accessible position of the buffer. The search for <var>regexp</var> is case-sensitive, and <var>replacement</var> is inserted without changing its letter-case. The <var>replacement</var> string can use the same special elements starting with ‘<samp>\</samp>’ as <code>replace-match</code> does. The function returns the number of replaced occurrences, or <code>nil</code> if <var>regexp</var> is not found. The function preserves the position of point. </p> <div class="example"> <pre class="example">(replace-regexp-in-region "foo[ \t]+bar" "foobar") +</pre> +</div> </dd> +</dl> <dl> <dt id="replace-string-in-region">Function: <strong>replace-string-in-region</strong> <em>string replacement &optional start end</em> +</dt> <dd><p>This function works similarly to <code>replace-regexp-in-region</code>, but searches for, and replaces, literal <var>string</var>s instead of regular expressions. </p></dd> +</dl> <p>Emacs also has special functions for replacing matches in a string. </p> <dl> <dt id="replace-regexp-in-string">Function: <strong>replace-regexp-in-string</strong> <em>regexp rep string &optional fixedcase literal subexp start</em> +</dt> <dd> +<p>This function copies <var>string</var> and searches it for matches for <var>regexp</var>, and replaces them with <var>rep</var>. It returns the modified copy. If <var>start</var> is non-<code>nil</code>, the search for matches starts at that index in <var>string</var>, and the returned value does not include the first <var>start</var> characters of <var>string</var>. To get the whole transformed string, concatenate the first <var>start</var> characters of <var>string</var> with the return value. </p> <p>This function uses <code>replace-match</code> to do the replacement, and it passes the optional arguments <var>fixedcase</var>, <var>literal</var> and <var>subexp</var> along to <code>replace-match</code>. </p> <p>Instead of a string, <var>rep</var> can be a function. In that case, <code>replace-regexp-in-string</code> calls <var>rep</var> for each match, passing the text of the match as its sole argument. It collects the value <var>rep</var> returns and passes that to <code>replace-match</code> as the replacement string. The match data at this point are the result of matching <var>regexp</var> against a substring of <var>string</var>. </p> +</dd> +</dl> <dl> <dt id="string-replace">Function: <strong>string-replace</strong> <em>from-string to-string in-string</em> +</dt> <dd><p>This function replaces all occurrences of <var>from-string</var> with <var>to-string</var> in <var>in-string</var> and returns the result. It may return one of its arguments unchanged, a constant string or a new string. Case is significant, and text properties are ignored. </p></dd> +</dl> <p>If you want to write a command along the lines of <code>query-replace</code>, you can use <code>perform-replace</code> to do the work. </p> <dl> <dt id="perform-replace">Function: <strong>perform-replace</strong> <em>from-string replacements query-flag regexp-flag delimited-flag &optional repeat-count map start end backward region-noncontiguous-p</em> +</dt> <dd> +<p>This function is the guts of <code>query-replace</code> and related commands. It searches for occurrences of <var>from-string</var> in the text between positions <var>start</var> and <var>end</var> and replaces some or all of them. If <var>start</var> is <code>nil</code> (or omitted), point is used instead, and the end of the buffer’s accessible portion is used for <var>end</var>. (If the optional argument <var>backward</var> is non-<code>nil</code>, the search starts at <var>end</var> and goes backward.) </p> <p>If <var>query-flag</var> is <code>nil</code>, it replaces all occurrences; otherwise, it asks the user what to do about each one. </p> <p>If <var>regexp-flag</var> is non-<code>nil</code>, then <var>from-string</var> is considered a regular expression; otherwise, it must match literally. If <var>delimited-flag</var> is non-<code>nil</code>, then only replacements surrounded by word boundaries are considered. </p> <p>The argument <var>replacements</var> 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. </p> <p>If <var>replacements</var> is a cons cell, <code>(<var>function</var> . <var>data</var>)</code>, this means to call <var>function</var> after each match to get the replacement text. This function is called with two arguments: <var>data</var>, and the number of replacements already made. </p> <p>If <var>repeat-count</var> is non-<code>nil</code>, it should be an integer. Then it specifies how many times to use each of the strings in the <var>replacements</var> list before advancing cyclically to the next one. </p> <p>If <var>from-string</var> contains upper-case letters, then <code>perform-replace</code> binds <code>case-fold-search</code> to <code>nil</code>, and it uses the <var>replacements</var> without altering their case. </p> <p>Normally, the keymap <code>query-replace-map</code> defines the possible user responses for queries. The argument <var>map</var>, if non-<code>nil</code>, specifies a keymap to use instead of <code>query-replace-map</code>. </p> <p>Non-<code>nil</code> <var>region-noncontiguous-p</var> means that the region between <var>start</var> and <var>end</var> is composed of noncontiguous pieces. The most common example of this is a rectangular region, where the pieces are separated by newline characters. </p> <p>This function uses one of two functions to search for the next occurrence of <var>from-string</var>. These functions are specified by the values of two variables: <code>replace-re-search-function</code> and <code>replace-search-function</code>. The former is called when the argument <var>regexp-flag</var> is non-<code>nil</code>, the latter when it is <code>nil</code>. </p> +</dd> +</dl> <dl> <dt id="query-replace-map">Variable: <strong>query-replace-map</strong> +</dt> <dd> +<p>This variable holds a special keymap that defines the valid user responses for <code>perform-replace</code> and the commands that use it, as well as <code>y-or-n-p</code> and <code>map-y-or-n-p</code>. This map is unusual in two ways: </p> <ul> <li> The key bindings are not commands, just symbols that are meaningful to the functions that use this map. </li> +<li> Prefix keys are not supported; each key binding must be for a single-event key sequence. This is because the functions don’t use <code>read-key-sequence</code> to get the input; instead, they read a single event and look it up “by hand”. </li> +</ul> </dd> +</dl> <p>Here are the meaningful bindings for <code>query-replace-map</code>. Several of them are meaningful only for <code>query-replace</code> and friends. </p> <dl compact> <dt><code>act</code></dt> <dd> +<p>Do take the action being considered—in other words, “yes”. </p> </dd> <dt><code>skip</code></dt> <dd> +<p>Do not take action for this question—in other words, “no”. </p> </dd> <dt><code>exit</code></dt> <dd> +<p>Answer this question “no”, and give up on the entire series of questions, assuming that the answers will be “no”. </p> </dd> <dt><code>exit-prefix</code></dt> <dd> +<p>Like <code>exit</code>, but add the key that was pressed to <code>unread-command-events</code> (see <a href="event-input-misc">Event Input Misc</a>). </p> </dd> <dt><code>act-and-exit</code></dt> <dd> +<p>Answer this question “yes”, and give up on the entire series of questions, assuming that subsequent answers will be “no”. </p> </dd> <dt><code>act-and-show</code></dt> <dd> +<p>Answer this question “yes”, but show the results—don’t advance yet to the next question. </p> </dd> <dt><code>automatic</code></dt> <dd> +<p>Answer this question and all subsequent questions in the series with “yes”, without further user interaction. </p> </dd> <dt><code>backup</code></dt> <dd> +<p>Move back to the previous place that a question was asked about. </p> </dd> <dt><code>undo</code></dt> <dd> +<p>Undo last replacement and move back to the place where that replacement was performed. </p> </dd> <dt><code>undo-all</code></dt> <dd> +<p>Undo all replacements and move back to the place where the first replacement was performed. </p> </dd> <dt><code>edit</code></dt> <dd> +<p>Enter a recursive edit to deal with this question—instead of any other action that would normally be taken. </p> </dd> <dt><code>edit-replacement</code></dt> <dd> +<p>Edit the replacement for this question in the minibuffer. </p> </dd> <dt><code>delete-and-edit</code></dt> <dd> +<p>Delete the text being considered, then enter a recursive edit to replace it. </p> </dd> <dt><code>recenter</code></dt> <dt><code>scroll-up</code></dt> <dt><code>scroll-down</code></dt> <dt><code>scroll-other-window</code></dt> <dt><code>scroll-other-window-down</code></dt> <dd> +<p>Perform the specified window scroll operation, then ask the same question again. Only <code>y-or-n-p</code> and related functions use this answer. </p> </dd> <dt><code>quit</code></dt> <dd> +<p>Perform a quit right away. Only <code>y-or-n-p</code> and related functions use this answer. </p> </dd> <dt><code>help</code></dt> <dd><p>Display some help, then ask again. </p></dd> </dl> <dl> <dt id="multi-query-replace-map">Variable: <strong>multi-query-replace-map</strong> +</dt> <dd> +<p>This variable holds a keymap that extends <code>query-replace-map</code> by providing additional keybindings that are useful in multi-buffer replacements. The additional bindings are: </p> <dl compact> <dt><code>automatic-all</code></dt> <dd> +<p>Answer this question and all subsequent questions in the series with “yes”, without further user interaction, for all remaining buffers. </p> </dd> <dt><code>exit-current</code></dt> <dd><p>Answer this question “no”, and give up on the entire series of questions for the current buffer. Continue to the next buffer in the sequence. </p></dd> </dl> </dd> +</dl> <dl> <dt id="replace-search-function">Variable: <strong>replace-search-function</strong> +</dt> <dd><p>This variable specifies a function that <code>perform-replace</code> calls to search for the next string to replace. Its default value is <code>search-forward</code>. Any other value should name a function of 3 arguments: the first 3 arguments of <code>search-forward</code> (see <a href="string-search">String Search</a>). </p></dd> +</dl> <dl> <dt id="replace-re-search-function">Variable: <strong>replace-re-search-function</strong> +</dt> <dd><p>This variable specifies a function that <code>perform-replace</code> calls to search for the next regexp to replace. Its default value is <code>re-search-forward</code>. Any other value should name a function of 3 arguments: the first 3 arguments of <code>re-search-forward</code> (see <a href="regexp-search">Regexp Search</a>). </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/Search-and-Replace.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Search-and-Replace.html</a> + </p> +</div> |