devdocs/elisp/regexp-functions.html


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

 <h4 class="subsection">Regular Expression Functions</h4> <p>These functions operate on regular expressions. </p>  <dl> <dt id="regexp-quote">Function: <strong>regexp-quote</strong> <em>string</em>
</dt> <dd>
<p>This function returns a regular expression whose only exact match is <var>string</var>. Using this regular expression in <code>looking-at</code> will succeed only if the next characters in the buffer are <var>string</var>; using it in a search function will succeed if the text being searched contains <var>string</var>. See <a href="regexp-search">Regexp Search</a>. </p> <p>This allows you to request an exact string match or search when calling a function that wants a regular expression. </p> <div class="example"> <pre class="example">(regexp-quote "^The cat$")
     ⇒ "\\^The cat\\$"
</pre>
</div> <p>One use of <code>regexp-quote</code> is to combine an exact string match with context described as a regular expression. For example, this searches for the string that is the value of <var>string</var>, surrounded by whitespace: </p> <div class="example"> <pre class="example">(re-search-forward
 (concat "\\s-" (regexp-quote string) "\\s-"))
</pre>
</div> <p>The returned string may be <var>string</var> itself if it does not contain any special characters. </p>
</dd>
</dl>  <dl> <dt id="regexp-opt">Function: <strong>regexp-opt</strong> <em>strings &amp;optional paren</em>
</dt> <dd>
<p>This function returns an efficient regular expression that will match any of the strings in the list <var>strings</var>. This is useful when you need to make matching or searching as fast as possible—for example, for Font Lock mode<a id="DOCF23" href="#FOOT23"><sup>23</sup></a>. </p> <p>If <var>strings</var> is the empty list, the return value is a regexp that never matches anything. </p> <p>The optional argument <var>paren</var> can be any of the following: </p> <dl compact> <dt>a string</dt> <dd>
<p>The resulting regexp is preceded by <var>paren</var> and followed by ‘<samp>\)</samp>’, e.g. use ‘<samp>"\\(?1:"</samp>’ to produce an explicitly numbered group. </p> </dd> <dt><code>words</code></dt> <dd>
<p>The resulting regexp is surrounded by ‘<samp>\&lt;\(</samp>’ and ‘<samp>\)\&gt;</samp>’. </p> </dd> <dt><code>symbols</code></dt> <dd>
<p>The resulting regexp is surrounded by ‘<samp>\_&lt;\(</samp>’ and ‘<samp>\)\_&gt;</samp>’ (this is often appropriate when matching programming-language keywords and the like). </p> </dd> <dt>non-<code>nil</code>
</dt> <dd>
<p>The resulting regexp is surrounded by ‘<samp>\(</samp>’ and ‘<samp>\)</samp>’. </p> </dd> <dt><code>nil</code></dt> <dd><p>The resulting regexp is surrounded by ‘<samp>\(?:</samp>’ and ‘<samp>\)</samp>’, if it is necessary to ensure that a postfix operator appended to it will apply to the whole expression. </p></dd> </dl> <p>The returned regexp is ordered in such a way that it will always match the longest string possible. </p> <p>Up to reordering, the resulting regexp of <code>regexp-opt</code> is equivalent to but usually more efficient than that of a simplified version: </p> <div class="example"> <pre class="example">(defun simplified-regexp-opt (strings &amp;optional paren)
 (let ((parens
        (cond
         ((stringp paren)       (cons paren "\\)"))
         ((eq paren 'words)    '("\\&lt;\\(" . "\\)\\&gt;"))
         ((eq paren 'symbols) '("\\_&lt;\\(" . "\\)\\_&gt;"))
         ((null paren)          '("\\(?:" . "\\)"))
         (t                       '("\\(" . "\\)")))))
   (concat (car parens)
           (mapconcat 'regexp-quote strings "\\|")
           (cdr parens))))
</pre>
</div> </dd>
</dl> <dl> <dt id="regexp-opt-depth">Function: <strong>regexp-opt-depth</strong> <em>regexp</em>
</dt> <dd><p>This function returns the total number of grouping constructs (parenthesized expressions) in <var>regexp</var>. This does not include shy groups (see <a href="regexp-backslash">Regexp Backslash</a>). </p></dd>
</dl> <dl> <dt id="regexp-opt-charset">Function: <strong>regexp-opt-charset</strong> <em>chars</em>
</dt> <dd>
<p>This function returns a regular expression matching a character in the list of characters <var>chars</var>. </p> <div class="example"> <pre class="example">(regexp-opt-charset '(?a ?b ?c ?d ?e))
     ⇒ "[a-e]"
</pre>
</div> </dd>
</dl> <dl> <dt id="regexp-unmatchable">Variable: <strong>regexp-unmatchable</strong>
</dt> <dd><p>This variable contains a regexp that is guaranteed not to match any string at all. It is particularly useful as default value for variables that may be set to a pattern that actually matches something. </p></dd>
</dl><div class="_attribution">
  <p class="_attribution-p">
    Copyright &copy; 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-Functions.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Regexp-Functions.html</a>
  </p>
</div>