diff options
Diffstat (limited to 'devdocs/elisp/regexp-search.html')
| -rw-r--r-- | devdocs/elisp/regexp-search.html | 79 |
1 files changed, 79 insertions, 0 deletions
diff --git a/devdocs/elisp/regexp-search.html b/devdocs/elisp/regexp-search.html new file mode 100644 index 00000000..7de9198e --- /dev/null +++ b/devdocs/elisp/regexp-search.html @@ -0,0 +1,79 @@ + <h3 class="section">Regular Expression Searching</h3> <p>In GNU Emacs, you can search for the next match for a regular expression (see <a href="syntax-of-regexps">Syntax of Regexps</a>) either incrementally or not. For incremental search commands, see <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Regexp-Search.html#Regexp-Search">Regular Expression Search</a> in <cite>The GNU Emacs Manual</cite>. Here we describe only the search functions useful in programs. The principal one is <code>re-search-forward</code>. </p> <p>These search functions convert the regular expression to multibyte if the buffer is multibyte; they convert the regular expression to unibyte if the buffer is unibyte. See <a href="text-representations">Text Representations</a>. </p> <dl> <dt id="re-search-forward">Command: <strong>re-search-forward</strong> <em>regexp &optional limit noerror count</em> +</dt> <dd> +<p>This function searches forward in the current buffer for a string of text that is matched by the regular expression <var>regexp</var>. The function skips over any amount of text that is not matched by <var>regexp</var>, and leaves point at the end of the first match found. It returns the new value of point. </p> <p>If <var>limit</var> is non-<code>nil</code>, it must be a position in the current buffer. It specifies the upper bound to the search. No match extending after that position is accepted. If <var>limit</var> is omitted or <code>nil</code>, it defaults to the end of the accessible portion of the buffer. </p> <p>What <code>re-search-forward</code> does when the search fails depends on the value of <var>noerror</var>: </p> <dl compact> <dt><code>nil</code></dt> <dd><p>Signal a <code>search-failed</code> error. </p></dd> <dt><code>t</code></dt> <dd><p>Do nothing and return <code>nil</code>. </p></dd> <dt>anything else</dt> <dd><p>Move point to <var>limit</var> (or the end of the accessible portion of the buffer) and return <code>nil</code>. </p></dd> </dl> <p>The argument <var>noerror</var> only affects valid searches which fail to find a match. Invalid arguments cause errors regardless of <var>noerror</var>. </p> <p>If <var>count</var> is a positive number <var>n</var>, the search is done <var>n</var> times; each successive search starts at the end of the previous match. If all these successive searches succeed, the function call succeeds, moving point and returning its new value. Otherwise the function call fails, with results depending on the value of <var>noerror</var>, as described above. If <var>count</var> is a negative number -<var>n</var>, the search is done <var>n</var> times in the opposite (backward) direction. </p> <p>In the following example, point is initially before the ‘<samp>T</samp>’. Evaluating the search call moves point to the end of that line (between the ‘<samp>t</samp>’ of ‘<samp>hat</samp>’ and the newline). </p> <div class="example"> <pre class="example">---------- Buffer: foo ---------- +I read "∗The cat in the hat +comes back" twice. +---------- Buffer: foo ---------- +</pre> + +<pre class="example">(re-search-forward "[a-z]+" nil t 5) + ⇒ 27 + +---------- Buffer: foo ---------- +I read "The cat in the hat∗ +comes back" twice. +---------- Buffer: foo ---------- +</pre> +</div> </dd> +</dl> <dl> <dt id="re-search-backward">Command: <strong>re-search-backward</strong> <em>regexp &optional limit noerror count</em> +</dt> <dd> +<p>This function searches backward in the current buffer for a string of text that is matched by the regular expression <var>regexp</var>, leaving point at the beginning of the first text found. </p> <p>This function is analogous to <code>re-search-forward</code>, but they are not simple mirror images. <code>re-search-forward</code> finds the match whose beginning is as close as possible to the starting point. If <code>re-search-backward</code> were a perfect mirror image, it would find the match whose end is as close as possible. However, in fact it finds the match whose beginning is as close as possible (and yet ends before the starting point). The reason for this is that matching a regular expression at a given spot always works from beginning to end, and starts at a specified beginning position. </p> <p>A true mirror-image of <code>re-search-forward</code> would require a special feature for matching regular expressions from end to beginning. It’s not worth the trouble of implementing that. </p> +</dd> +</dl> <dl> <dt id="string-match">Function: <strong>string-match</strong> <em>regexp string &optional start</em> +</dt> <dd> +<p>This function returns the index of the start of the first match for the regular expression <var>regexp</var> in <var>string</var>, or <code>nil</code> if there is no match. If <var>start</var> is non-<code>nil</code>, the search starts at that index in <var>string</var>. </p> <p>For example, </p> <div class="example"> <pre class="example">(string-match + "quick" "The quick brown fox jumped quickly.") + ⇒ 4 +</pre> +<pre class="example">(string-match + "quick" "The quick brown fox jumped quickly." 8) + ⇒ 27 +</pre> +</div> <p>The index of the first character of the string is 0, the index of the second character is 1, and so on. </p> <p>If this function finds a match, the index of the first character beyond the match is available as <code>(match-end 0)</code>. See <a href="match-data">Match Data</a>. </p> <div class="example"> <pre class="example">(string-match + "quick" "The quick brown fox jumped quickly." 8) + ⇒ 27 +</pre> + +<pre class="example">(match-end 0) + ⇒ 32 +</pre> +</div> </dd> +</dl> <dl> <dt id="string-match-p">Function: <strong>string-match-p</strong> <em>regexp string &optional start</em> +</dt> <dd><p>This predicate function does what <code>string-match</code> does, but it avoids modifying the match data. </p></dd> +</dl> <dl> <dt id="looking-at">Function: <strong>looking-at</strong> <em>regexp</em> +</dt> <dd> +<p>This function determines whether the text in the current buffer directly following point matches the regular expression <var>regexp</var>. “Directly following” means precisely that: the search is “anchored” and it can succeed only starting with the first character following point. The result is <code>t</code> if so, <code>nil</code> otherwise. </p> <p>This function does not move point, but it does update the match data. See <a href="match-data">Match Data</a>. If you need to test for a match without modifying the match data, use <code>looking-at-p</code>, described below. </p> <p>In this example, point is located directly before the ‘<samp>T</samp>’. If it were anywhere else, the result would be <code>nil</code>. </p> <div class="example"> <pre class="example">---------- Buffer: foo ---------- +I read "∗The cat in the hat +comes back" twice. +---------- Buffer: foo ---------- + +(looking-at "The cat in the hat$") + ⇒ t +</pre> +</div> </dd> +</dl> <dl> <dt id="looking-back">Function: <strong>looking-back</strong> <em>regexp limit &optional greedy</em> +</dt> <dd> +<p>This function returns <code>t</code> if <var>regexp</var> matches the text immediately before point (i.e., ending at point), and <code>nil</code> otherwise. </p> <p>Because regular expression matching works only going forward, this is implemented by searching backwards from point for a match that ends at point. That can be quite slow if it has to search a long distance. You can bound the time required by specifying a non-<code>nil</code> value for <var>limit</var>, which says not to search before <var>limit</var>. In this case, the match that is found must begin at or after <var>limit</var>. Here’s an example: </p> <div class="example"> <pre class="example">---------- Buffer: foo ---------- +I read "∗The cat in the hat +comes back" twice. +---------- Buffer: foo ---------- + +(looking-back "read \"" 3) + ⇒ t +(looking-back "read \"" 4) + ⇒ nil +</pre> +</div> <p>If <var>greedy</var> is non-<code>nil</code>, this function extends the match backwards as far as possible, stopping when a single additional previous character cannot be part of a match for <var>regexp</var>. When the match is extended, its starting position is allowed to occur before <var>limit</var>. </p> <p>As a general recommendation, try to avoid using <code>looking-back</code> wherever possible, since it is slow. For this reason, there are no plans to add a <code>looking-back-p</code> function. </p> +</dd> +</dl> <dl> <dt id="looking-at-p">Function: <strong>looking-at-p</strong> <em>regexp</em> +</dt> <dd><p>This predicate function works like <code>looking-at</code>, but without updating the match data. </p></dd> +</dl> <dl> <dt id="search-spaces-regexp">Variable: <strong>search-spaces-regexp</strong> +</dt> <dd> +<p>If this variable is non-<code>nil</code>, it should be a regular expression that says how to search for whitespace. In that case, any group of spaces in a regular expression being searched for stands for use of this regular expression. However, spaces inside of constructs such as ‘<samp>[…]</samp>’ and ‘<samp>*</samp>’, ‘<samp>+</samp>’, ‘<samp>?</samp>’ are not affected by <code>search-spaces-regexp</code>. </p> <p>Since this variable affects all regular expression search and match constructs, you should bind it temporarily for as small as possible a part of the 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/Regexp-Search.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Regexp-Search.html</a> + </p> +</div> |