diff options
Diffstat (limited to 'devdocs/elisp/rx-constructs.html')
| -rw-r--r-- | devdocs/elisp/rx-constructs.html | 290 |
1 files changed, 290 insertions, 0 deletions
diff --git a/devdocs/elisp/rx-constructs.html b/devdocs/elisp/rx-constructs.html new file mode 100644 index 00000000..dcd69b38 --- /dev/null +++ b/devdocs/elisp/rx-constructs.html @@ -0,0 +1,290 @@ + <h4 class="subsubsection">Constructs in rx regexps</h4> <p>The various forms in <code>rx</code> regexps are described below. The shorthand <var>rx</var> represents any <code>rx</code> form, and <var>rx</var>… means zero or more <code>rx</code> forms. These are all valid arguments to the <code>rx</code> macro. Where the corresponding string regexp syntax is given, <var>A</var>, <var>B</var>, … are string regexp subexpressions. </p> <h4 class="subsubheading">Literals</h4> <dl compact> <dt><code>"some-string"</code></dt> <dd> +<p>Match the string ‘<samp>some-string</samp>’ literally. There are no characters with special meaning, unlike in string regexps. </p> </dd> <dt><code>?C</code></dt> <dd><p>Match the character ‘<samp>C</samp>’ literally. </p></dd> </dl> <h4 class="subsubheading">Sequence and alternative</h4> <dl compact> <dt><code>(seq <var>rx</var>…)</code></dt> <dt><code>(sequence <var>rx</var>…)</code></dt> <dt><code>(: <var>rx</var>…)</code></dt> <dt><code>(and <var>rx</var>…)</code></dt> <dd> + <p>Match the <var>rx</var>s in sequence. Without arguments, the expression matches the empty string. Corresponding string regexp: ‘<samp><var>A</var><var>B</var>…</samp>’ (subexpressions in sequence). </p> </dd> <dt><code>(or <var>rx</var>…)</code></dt> <dt><code>(| <var>rx</var>…)</code></dt> <dd> + <p>Match exactly one of the <var>rx</var>s. If all arguments are strings, characters, or <code>or</code> forms so constrained, the longest possible match will always be used. Otherwise, either the longest match or the first (in left-to-right order) will be used. Without arguments, the expression will not match anything at all. Corresponding string regexp: ‘<samp><var>A</var>\|<var>B</var>\|…</samp>’. </p> </dd> <dt><code>unmatchable</code></dt> <dd> + <p>Refuse any match. Equivalent to <code>(or)</code>. See <a href="regexp-functions#regexp_002dunmatchable">regexp-unmatchable</a>. </p> +</dd> </dl> <h4 class="subsubheading">Repetition</h4> <p>Normally, repetition forms are greedy, in that they attempt to match as many times as possible. Some forms are non-greedy; they try to match as few times as possible (see <a href="regexp-special#Non_002dgreedy-repetition">Non-greedy repetition</a>). </p> <dl compact> <dt><code>(zero-or-more <var>rx</var>…)</code></dt> <dt><code>(0+ <var>rx</var>…)</code></dt> <dd> + <p>Match the <var>rx</var>s zero or more times. Greedy by default. Corresponding string regexp: ‘<samp><var>A</var>*</samp>’ (greedy), ‘<samp><var>A</var>*?</samp>’ (non-greedy) </p> </dd> <dt><code>(one-or-more <var>rx</var>…)</code></dt> <dt><code>(1+ <var>rx</var>…)</code></dt> <dd> + <p>Match the <var>rx</var>s one or more times. Greedy by default. Corresponding string regexp: ‘<samp><var>A</var>+</samp>’ (greedy), ‘<samp><var>A</var>+?</samp>’ (non-greedy) </p> </dd> <dt><code>(zero-or-one <var>rx</var>…)</code></dt> <dt><code>(optional <var>rx</var>…)</code></dt> <dt><code>(opt <var>rx</var>…)</code></dt> <dd> + <p>Match the <var>rx</var>s once or an empty string. Greedy by default. Corresponding string regexp: ‘<samp><var>A</var>?</samp>’ (greedy), ‘<samp><var>A</var>??</samp>’ (non-greedy). </p> </dd> <dt><code>(* <var>rx</var>…)</code></dt> <dd> + <p>Match the <var>rx</var>s zero or more times. Greedy. Corresponding string regexp: ‘<samp><var>A</var>*</samp>’ </p> </dd> <dt><code>(+ <var>rx</var>…)</code></dt> <dd> + <p>Match the <var>rx</var>s one or more times. Greedy. Corresponding string regexp: ‘<samp><var>A</var>+</samp>’ </p> </dd> <dt><code>(? <var>rx</var>…)</code></dt> <dd> + <p>Match the <var>rx</var>s once or an empty string. Greedy. Corresponding string regexp: ‘<samp><var>A</var>?</samp>’ </p> </dd> <dt><code>(*? <var>rx</var>…)</code></dt> <dd> + <p>Match the <var>rx</var>s zero or more times. Non-greedy. Corresponding string regexp: ‘<samp><var>A</var>*?</samp>’ </p> </dd> <dt><code>(+? <var>rx</var>…)</code></dt> <dd> + <p>Match the <var>rx</var>s one or more times. Non-greedy. Corresponding string regexp: ‘<samp><var>A</var>+?</samp>’ </p> </dd> <dt><code>(?? <var>rx</var>…)</code></dt> <dd> + <p>Match the <var>rx</var>s or an empty string. Non-greedy. Corresponding string regexp: ‘<samp><var>A</var>??</samp>’ </p> </dd> <dt><code>(= <var>n</var> <var>rx</var>…)</code></dt> <dt><code>(repeat <var>n</var> <var>rx</var>)</code></dt> <dd> +<p>Match the <var>rx</var>s exactly <var>n</var> times. Corresponding string regexp: ‘<samp><var>A</var>\{<var>n</var>\}</samp>’ </p> </dd> <dt><code>(>= <var>n</var> <var>rx</var>…)</code></dt> <dd> + <p>Match the <var>rx</var>s <var>n</var> or more times. Greedy. Corresponding string regexp: ‘<samp><var>A</var>\{<var>n</var>,\}</samp>’ </p> </dd> <dt><code>(** <var>n</var> <var>m</var> <var>rx</var>…)</code></dt> <dt><code>(repeat <var>n</var> <var>m</var> <var>rx</var>…)</code></dt> <dd> + <p>Match the <var>rx</var>s at least <var>n</var> but no more than <var>m</var> times. Greedy. Corresponding string regexp: ‘<samp><var>A</var>\{<var>n</var>,<var>m</var>\}</samp>’ </p> +</dd> </dl> <p>The greediness of some repetition forms can be controlled using the following constructs. However, it is usually better to use the explicit non-greedy forms above when such matching is required. </p> <dl compact> <dt><code>(minimal-match <var>rx</var>)</code></dt> <dd> + <p>Match <var>rx</var>, with <code>zero-or-more</code>, <code>0+</code>, <code>one-or-more</code>, <code>1+</code>, <code>zero-or-one</code>, <code>opt</code> and <code>optional</code> using non-greedy matching. </p> </dd> <dt><code>(maximal-match <var>rx</var>)</code></dt> <dd> + <p>Match <var>rx</var>, with <code>zero-or-more</code>, <code>0+</code>, <code>one-or-more</code>, <code>1+</code>, <code>zero-or-one</code>, <code>opt</code> and <code>optional</code> using greedy matching. This is the default. </p> +</dd> </dl> <h4 class="subsubheading">Matching single characters</h4> <dl compact> <dt><code>(any <var>set</var>…)</code></dt> <dt><code>(char <var>set</var>…)</code></dt> <dt><code>(in <var>set</var>…)</code></dt> <dd> + <p>Match a single character from one of the <var>set</var>s. Each <var>set</var> is a character, a string representing the set of its characters, a range or a character class (see below). A range is either a hyphen-separated string like <code>"A-Z"</code>, or a cons of characters like <code>(?A . ?Z)</code>. </p> <p>Note that hyphen (<code>-</code>) is special in strings in this construct, since it acts as a range separator. To include a hyphen, add it as a separate character or single-character string. Corresponding string regexp: ‘<samp>[…]</samp>’ </p> </dd> <dt><code>(not <var>charspec</var>)</code></dt> <dd> + <p>Match a character not included in <var>charspec</var>. <var>charspec</var> can be a character, a single-character string, an <code>any</code>, <code>not</code>, <code>or</code>, <code>intersection</code>, <code>syntax</code> or <code>category</code> form, or a character class. If <var>charspec</var> is an <code>or</code> form, its arguments have the same restrictions as those of <code>intersection</code>; see below. Corresponding string regexp: ‘<samp>[^…]</samp>’, ‘<samp>\S<var>code</var></samp>’, ‘<samp>\C<var>code</var></samp>’ </p> </dd> <dt><code>(intersection <var>charset</var>…)</code></dt> <dd> + <p>Match a character included in all of the <var>charset</var>s. Each <var>charset</var> can be a character, a single-character string, an <code>any</code> form without character classes, or an <code>intersection</code>, <code>or</code> or <code>not</code> form whose arguments are also <var>charset</var>s. </p> </dd> <dt> +<code>not-newline</code>, <code>nonl</code> +</dt> <dd> + <p>Match any character except a newline. Corresponding string regexp: ‘<samp>.</samp>’ (dot) </p> </dd> <dt> +<code>anychar</code>, <code>anything</code> +</dt> <dd> + <p>Match any character. Corresponding string regexp: ‘<samp>.\|\n</samp>’ (for example) </p> </dd> <dt>character class</dt> <dd> + <p>Match a character from a named character class: </p> <dl compact> <dt> +<code>alpha</code>, <code>alphabetic</code>, <code>letter</code> +</dt> <dd> +<p>Match alphabetic characters. More precisely, match characters whose Unicode ‘<samp>general-category</samp>’ property indicates that they are alphabetic. </p> </dd> <dt> +<code>alnum</code>, <code>alphanumeric</code> +</dt> <dd> +<p>Match alphabetic characters and digits. More precisely, match characters whose Unicode ‘<samp>general-category</samp>’ property indicates that they are alphabetic or decimal digits. </p> </dd> <dt> +<code>digit</code>, <code>numeric</code>, <code>num</code> +</dt> <dd> +<p>Match the digits ‘<samp>0</samp>’–‘<samp>9</samp>’. </p> </dd> <dt> +<code>xdigit</code>, <code>hex-digit</code>, <code>hex</code> +</dt> <dd> +<p>Match the hexadecimal digits ‘<samp>0</samp>’–‘<samp>9</samp>’, ‘<samp>A</samp>’–‘<samp>F</samp>’ and ‘<samp>a</samp>’–‘<samp>f</samp>’. </p> </dd> <dt> +<code>cntrl</code>, <code>control</code> +</dt> <dd> +<p>Match any character whose code is in the range 0–31. </p> </dd> <dt><code>blank</code></dt> <dd> +<p>Match horizontal whitespace. More precisely, match characters whose Unicode ‘<samp>general-category</samp>’ property indicates that they are spacing separators. </p> </dd> <dt> +<code>space</code>, <code>whitespace</code>, <code>white</code> +</dt> <dd> +<p>Match any character that has whitespace syntax (see <a href="syntax-class-table">Syntax Class Table</a>). </p> </dd> <dt> +<code>lower</code>, <code>lower-case</code> +</dt> <dd> +<p>Match anything lower-case, as determined by the current case table. If <code>case-fold-search</code> is non-nil, this also matches any upper-case letter. </p> </dd> <dt> +<code>upper</code>, <code>upper-case</code> +</dt> <dd> +<p>Match anything upper-case, as determined by the current case table. If <code>case-fold-search</code> is non-nil, this also matches any lower-case letter. </p> </dd> <dt> +<code>graph</code>, <code>graphic</code> +</dt> <dd> +<p>Match any character except whitespace, <acronym>ASCII</acronym> and non-<acronym>ASCII</acronym> control characters, surrogates, and codepoints unassigned by Unicode, as indicated by the Unicode ‘<samp>general-category</samp>’ property. </p> </dd> <dt> +<code>print</code>, <code>printing</code> +</dt> <dd> +<p>Match whitespace or a character matched by <code>graph</code>. </p> </dd> <dt> +<code>punct</code>, <code>punctuation</code> +</dt> <dd> +<p>Match any punctuation character. (At present, for multibyte characters, anything that has non-word syntax.) </p> </dd> <dt> +<code>word</code>, <code>wordchar</code> +</dt> <dd> +<p>Match any character that has word syntax (see <a href="syntax-class-table">Syntax Class Table</a>). </p> </dd> <dt><code>ascii</code></dt> <dd> +<p>Match any <acronym>ASCII</acronym> character (codes 0–127). </p> </dd> <dt><code>nonascii</code></dt> <dd><p>Match any non-<acronym>ASCII</acronym> character (but not raw bytes). </p></dd> </dl> <p>Corresponding string regexp: ‘<samp>[[:<var>class</var>:]]</samp>’ </p> </dd> <dt><code>(syntax <var>syntax</var>)</code></dt> <dd> + <p>Match a character with syntax <var>syntax</var>, being one of the following names: </p> <table> <thead><tr> +<th>Syntax name</th> +<th>Syntax character</th> +</tr></thead> <tr> +<td><code>whitespace</code></td> +<td><code>-</code></td> +</tr> <tr> +<td><code>punctuation</code></td> +<td><code>.</code></td> +</tr> <tr> +<td><code>word</code></td> +<td><code>w</code></td> +</tr> <tr> +<td><code>symbol</code></td> +<td><code>_</code></td> +</tr> <tr> +<td><code>open-parenthesis</code></td> +<td><code>(</code></td> +</tr> <tr> +<td><code>close-parenthesis</code></td> +<td><code>)</code></td> +</tr> <tr> +<td><code>expression-prefix</code></td> +<td><code>'</code></td> +</tr> <tr> +<td><code>string-quote</code></td> +<td><code>"</code></td> +</tr> <tr> +<td><code>paired-delimiter</code></td> +<td><code>$</code></td> +</tr> <tr> +<td><code>escape</code></td> +<td><code>\</code></td> +</tr> <tr> +<td><code>character-quote</code></td> +<td><code>/</code></td> +</tr> <tr> +<td><code>comment-start</code></td> +<td><code><</code></td> +</tr> <tr> +<td><code>comment-end</code></td> +<td><code>></code></td> +</tr> <tr> +<td><code>string-delimiter</code></td> +<td><code>|</code></td> +</tr> <tr> +<td><code>comment-delimiter</code></td> +<td><code>!</code></td> +</tr> </table> <p>For details, see <a href="syntax-class-table">Syntax Class Table</a>. Please note that <code>(syntax punctuation)</code> is <em>not</em> equivalent to the character class <code>punctuation</code>. Corresponding string regexp: ‘<samp>\s<var>char</var></samp>’ where <var>char</var> is the syntax character. </p> </dd> <dt><code>(category <var>category</var>)</code></dt> <dd> + <p>Match a character in category <var>category</var>, which is either one of the names below or its category character. </p> <table> <thead><tr> +<th>Category name</th> +<th>Category character</th> +</tr></thead> <tr> +<td><code>space-for-indent</code></td> +<td>space</td> +</tr> <tr> +<td><code>base</code></td> +<td><code>.</code></td> +</tr> <tr> +<td><code>consonant</code></td> +<td><code>0</code></td> +</tr> <tr> +<td><code>base-vowel</code></td> +<td><code>1</code></td> +</tr> <tr> +<td><code>upper-diacritical-mark</code></td> +<td><code>2</code></td> +</tr> <tr> +<td><code>lower-diacritical-mark</code></td> +<td><code>3</code></td> +</tr> <tr> +<td><code>tone-mark</code></td> +<td><code>4</code></td> +</tr> <tr> +<td><code>symbol</code></td> +<td><code>5</code></td> +</tr> <tr> +<td><code>digit</code></td> +<td><code>6</code></td> +</tr> <tr> +<td><code>vowel-modifying-diacritical-mark</code></td> +<td><code>7</code></td> +</tr> <tr> +<td><code>vowel-sign</code></td> +<td><code>8</code></td> +</tr> <tr> +<td><code>semivowel-lower</code></td> +<td><code>9</code></td> +</tr> <tr> +<td><code>not-at-end-of-line</code></td> +<td><code><</code></td> +</tr> <tr> +<td><code>not-at-beginning-of-line</code></td> +<td><code>></code></td> +</tr> <tr> +<td><code>alpha-numeric-two-byte</code></td> +<td><code>A</code></td> +</tr> <tr> +<td><code>chinese-two-byte</code></td> +<td><code>C</code></td> +</tr> <tr> +<td><code>greek-two-byte</code></td> +<td><code>G</code></td> +</tr> <tr> +<td><code>japanese-hiragana-two-byte</code></td> +<td><code>H</code></td> +</tr> <tr> +<td><code>indian-two-byte</code></td> +<td><code>I</code></td> +</tr> <tr> +<td><code>japanese-katakana-two-byte</code></td> +<td><code>K</code></td> +</tr> <tr> +<td><code>strong-left-to-right</code></td> +<td><code>L</code></td> +</tr> <tr> +<td><code>korean-hangul-two-byte</code></td> +<td><code>N</code></td> +</tr> <tr> +<td><code>strong-right-to-left</code></td> +<td><code>R</code></td> +</tr> <tr> +<td><code>cyrillic-two-byte</code></td> +<td><code>Y</code></td> +</tr> <tr> +<td><code>combining-diacritic</code></td> +<td><code>^</code></td> +</tr> <tr> +<td><code>ascii</code></td> +<td><code>a</code></td> +</tr> <tr> +<td><code>arabic</code></td> +<td><code>b</code></td> +</tr> <tr> +<td><code>chinese</code></td> +<td><code>c</code></td> +</tr> <tr> +<td><code>ethiopic</code></td> +<td><code>e</code></td> +</tr> <tr> +<td><code>greek</code></td> +<td><code>g</code></td> +</tr> <tr> +<td><code>korean</code></td> +<td><code>h</code></td> +</tr> <tr> +<td><code>indian</code></td> +<td><code>i</code></td> +</tr> <tr> +<td><code>japanese</code></td> +<td><code>j</code></td> +</tr> <tr> +<td><code>japanese-katakana</code></td> +<td><code>k</code></td> +</tr> <tr> +<td><code>latin</code></td> +<td><code>l</code></td> +</tr> <tr> +<td><code>lao</code></td> +<td><code>o</code></td> +</tr> <tr> +<td><code>tibetan</code></td> +<td><code>q</code></td> +</tr> <tr> +<td><code>japanese-roman</code></td> +<td><code>r</code></td> +</tr> <tr> +<td><code>thai</code></td> +<td><code>t</code></td> +</tr> <tr> +<td><code>vietnamese</code></td> +<td><code>v</code></td> +</tr> <tr> +<td><code>hebrew</code></td> +<td><code>w</code></td> +</tr> <tr> +<td><code>cyrillic</code></td> +<td><code>y</code></td> +</tr> <tr> +<td><code>can-break</code></td> +<td><code>|</code></td> +</tr> </table> <p>For more information about currently defined categories, run the command <kbd>M-x describe-categories <span class="key">RET</span></kbd>. For how to define new categories, see <a href="categories">Categories</a>. Corresponding string regexp: ‘<samp>\c<var>char</var></samp>’ where <var>char</var> is the category character. </p> +</dd> </dl> <h4 class="subsubheading">Zero-width assertions</h4> <p>These all match the empty string, but only in specific places. </p> <dl compact> <dt> +<code>line-start</code>, <code>bol</code> +</dt> <dd> + <p>Match at the beginning of a line. Corresponding string regexp: ‘<samp>^</samp>’ </p> </dd> <dt> +<code>line-end</code>, <code>eol</code> +</dt> <dd> + <p>Match at the end of a line. Corresponding string regexp: ‘<samp>$</samp>’ </p> </dd> <dt> +<code>string-start</code>, <code>bos</code>, <code>buffer-start</code>, <code>bot</code> +</dt> <dd> + <p>Match at the start of the string or buffer being matched against. Corresponding string regexp: ‘<samp>\`</samp>’ </p> </dd> <dt> +<code>string-end</code>, <code>eos</code>, <code>buffer-end</code>, <code>eot</code> +</dt> <dd> + <p>Match at the end of the string or buffer being matched against. Corresponding string regexp: ‘<samp>\'</samp>’ </p> </dd> <dt><code>point</code></dt> <dd> + <p>Match at point. Corresponding string regexp: ‘<samp>\=</samp>’ </p> </dd> <dt> +<code>word-start</code>, <code>bow</code> +</dt> <dd> + <p>Match at the beginning of a word. Corresponding string regexp: ‘<samp>\<</samp>’ </p> </dd> <dt> +<code>word-end</code>, <code>eow</code> +</dt> <dd> + <p>Match at the end of a word. Corresponding string regexp: ‘<samp>\></samp>’ </p> </dd> <dt><code>word-boundary</code></dt> <dd> + <p>Match at the beginning or end of a word. Corresponding string regexp: ‘<samp>\b</samp>’ </p> </dd> <dt><code>not-word-boundary</code></dt> <dd> + <p>Match anywhere but at the beginning or end of a word. Corresponding string regexp: ‘<samp>\B</samp>’ </p> </dd> <dt><code>symbol-start</code></dt> <dd> + <p>Match at the beginning of a symbol. Corresponding string regexp: ‘<samp>\_<</samp>’ </p> </dd> <dt><code>symbol-end</code></dt> <dd> + <p>Match at the end of a symbol. Corresponding string regexp: ‘<samp>\_></samp>’ </p> +</dd> </dl> <h4 class="subsubheading">Capture groups</h4> <dl compact> <dt><code>(group <var>rx</var>…)</code></dt> <dt><code>(submatch <var>rx</var>…)</code></dt> <dd> + <p>Match the <var>rx</var>s, making the matched text and position accessible in the match data. The first group in a regexp is numbered 1; subsequent groups will be numbered one above the previously highest-numbered group in the pattern so far. Corresponding string regexp: ‘<samp>\(…\)</samp>’ </p> </dd> <dt><code>(group-n <var>n</var> <var>rx</var>…)</code></dt> <dt><code>(submatch-n <var>n</var> <var>rx</var>…)</code></dt> <dd> + <p>Like <code>group</code>, but explicitly assign the group number <var>n</var>. <var>n</var> must be positive. Corresponding string regexp: ‘<samp>\(?<var>n</var>:…\)</samp>’ </p> </dd> <dt><code>(backref <var>n</var>)</code></dt> <dd> + <p>Match the text previously matched by group number <var>n</var>. <var>n</var> must be in the range 1–9. Corresponding string regexp: ‘<samp>\<var>n</var></samp>’ </p> +</dd> </dl> <h4 class="subsubheading">Dynamic inclusion</h4> <dl compact> <dt><code>(literal <var>expr</var>)</code></dt> <dd> + <p>Match the literal string that is the result from evaluating the Lisp expression <var>expr</var>. The evaluation takes place at call time, in the current lexical environment. </p> </dd> <dt><code>(regexp <var>expr</var>)</code></dt> <dt><code>(regex <var>expr</var>)</code></dt> <dd> + <p>Match the string regexp that is the result from evaluating the Lisp expression <var>expr</var>. The evaluation takes place at call time, in the current lexical environment. </p> </dd> <dt><code>(eval <var>expr</var>)</code></dt> <dd> + <p>Match the rx form that is the result from evaluating the Lisp expression <var>expr</var>. The evaluation takes place at macro-expansion time for <code>rx</code>, at call time for <code>rx-to-string</code>, in the current global environment. </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/Rx-Constructs.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Rx-Constructs.html</a> + </p> +</div> |