kakoune

Fork of kakoune, an acceptable text editor
git clone git://git.laack.co/kakoune.git
Log | Files | Refs

regex.asciidoc (8166B)


      1 = Regex
      2 
      3 == Regex syntax
      4 
      5 Kakoune's regex syntax is inspired by ECMAScript, as defined by the
      6 ECMA-262 standard (see <<regex#compatibility,:doc regex compatibility>>).
      7 
      8 Kakoune's regex always runs on Unicode codepoint sequences, not on bytes.
      9 
     10 == Literals
     11 
     12 Every character except the syntax characters `\^$.*+?[]{}|().` match
     13 themselves. Syntax characters can be escaped with a backslash so that
     14 `\$` will match a literal `$`, and `\\` will match a literal `\`.
     15 
     16 Some literals are available as escape sequences:
     17 
     18 * `\f` matches the form feed character.
     19 * `\n` matches the newline character.
     20 * `\r` matches the carriage return character.
     21 * `\t` matches the tabulation character.
     22 * `\v` matches the vertical tabulation character.
     23 * `\0` matches the null character.
     24 * `\cX` matches the control-`X` character (`X` can be in `[A-Za-z]`).
     25 * `\xXX` matches the character whose codepoint is `XX` (in hexadecimal).
     26 * `\uXXXXXX` matches the character whose codepoint is `XXXXXX` (in hexadecimal).
     27 
     28 == Character classes
     29 
     30 The `[` character introduces a character class, matching one character
     31 from a set of characters.
     32 
     33 A character class contains a list of literals, character ranges,
     34 and character class escapes surrounded by `[` and `]`.
     35 
     36 If the first character inside a character class is `^`, then the character
     37 class is negated, meaning that it matches every character not specified
     38 in the character class.
     39 
     40 Literals match themselves, including syntax characters, so `^`
     41 does not need to be escaped in a character class. `[\*+]` matches both
     42 the `\*` character and the `+` character. Literal escape sequences are
     43 supported, so `[\n\r]` matches both the newline and carriage return
     44 characters.
     45 
     46 The `]` character needs to be escaped for it to match a literal `]`
     47 instead of closing the character class.
     48 
     49 Character ranges are written as `<start character>-<end character>`, so
     50 `[A-Z]` matches all uppercase basic letters. `[A-Z0-9]` will match all
     51 uppercase basic letters and all basic digits.
     52 
     53 The `-` characters in a character class that are not specifying a
     54 range are treated as literal `-`, so `[A-Z-+]` matches all upper case
     55 characters, the `-` character, and the `+` character.
     56 
     57 Supported character class escapes are:
     58 
     59 * `\d` which matches digits 0-9.
     60 * `\w` which matches word characters A-Z, a-z, 0-9 and underscore
     61     (ignoring the `extra_word_chars` option).
     62 * `\s` which matches all Unicode whitespace characters.
     63 * `\h` which matches whitespace except Vertical Tab and line-breaks.
     64 
     65 Using an upper case letter instead of a lower case one will negate
     66 the character class. For example, `\D` will match every non-digit
     67 character.
     68 
     69 Character class escapes can be used outside of a character class, `\d`
     70 is equivalent to `[\d]`.
     71 
     72 == Any character
     73 
     74 `.` matches any character, including newlines, by default.
     75 (see <<regex#modifiers,:doc regex modifiers>> on how to change it)
     76 
     77 `\N` matches any character but newlines (not affected by modifiers).
     78 
     79 == Groups
     80 
     81 Regex atoms can be grouped using `(` and `)` or `(?:` and `)`. If `(` is
     82 used, the group will be a capturing group, which means the positions from
     83 the subject strings that matched between `(` and `)` will be recorded.
     84 
     85 Capture groups are numbered starting at 1. They are numbered in the
     86 order of appearance of their `(` in the regex. A special capture group
     87 0 is for the whole sequence that matched.
     88 
     89 * `(?:` introduces a non capturing group, which will not record the
     90 matching positions.
     91 
     92 * `(?<name>` introduces a named capturing group, which, in addition to
     93 being referred by number, can be, in certain contexts, referred by the
     94 given name.
     95 
     96 == Alternations
     97 
     98 The `|` character introduces an alternation, which will either match
     99 its left-hand side, or its right-hand side (preferring the left-hand side)
    100 
    101 For example, `foo|bar` matches either `foo` or `bar`, `foo(bar|baz|qux)`
    102 matches `foo` followed by either `bar`, `baz` or `qux`.
    103 
    104 == Quantifier
    105 
    106 Literals, character classes, any characters, and groups can be followed
    107 by a quantifier, which specifies the number of times they can match.
    108 
    109 * `?` matches zero, or one time.
    110 * `*` matches zero or more times.
    111 * `+` matches one or more times.
    112 * `{n}` matches exactly `n` times.
    113 * `{n,}` matches `n` or more times.
    114 * `{n,m}` matches `n` to `m` times.
    115 * `{,m}` matches zero to `m` times.
    116 
    117 By default, quantifiers are *greedy*, which means they will prefer to
    118 match more characters if possible. Suffixing a quantifier with `?` will
    119 make it non-greedy, meaning it will prefer to match as few characters
    120 as possible.
    121 
    122 == Zero width assertions
    123 
    124 Assertions do not consume any character, but they will prevent the regex
    125 from matching if their specific property is not true at the current
    126 position.
    127 
    128 * `^` matches at the start of a line; that is, the current position is
    129       immediately after a newline character, or at the first character
    130       in the subject string (unless the subject is a selection that
    131       begins part-way through a line).
    132 * `$` matches at the end of a line; that is, the current position is at
    133       a newline character, or after the last character in the subject
    134       string (unless the subject is a selection that ends part-way
    135       through a line).
    136 * `\b` matches at a word boundary; that is, the current position is at a
    137        word character and immediately after a non-word character (or the
    138        other way around).
    139 * `\B` matches at a word non-boundary; that is, the current position is
    140        at a word character and immediately after a word character, or
    141        both are non-word characters.
    142 * `\A` matches if the current position is at the first character in the
    143        subject string.
    144 * `\z` matches if the current position is after the last character in
    145        the subject string. This cannot match at any position in the
    146        subject string; use `.\z` to match the subject's last character.
    147 * `\K` matches at any position, and resets the start position of capture
    148        group 0 to the current position.
    149 
    150 More complex assertions can be expressed with lookarounds:
    151 
    152 * `(?=...)` is a lookahead; it will match if its content matches the
    153             text starting at the current position.
    154 * `(?!...)` is a negative lookahead; it will match if its content does
    155             not match the text starting at the current position.
    156 * `(?<=...)` is a lookbehind; it will match if its content matches
    157              the text preceding the current position.
    158 * `(?<!...)` is a negative lookbehind; it will match if its content does
    159              not match the text preceding the current position.
    160 
    161 For performance reasons, lookaround contents must be a sequence of
    162 literals, character classes, or any character (`.`); quantifiers are not
    163 supported.
    164 
    165 For example, `(?<!bar)(?=foo).` will match any character which is not
    166 preceded by `bar` and where `foo` matches from the current position
    167 (which means the character has to be an `f`).
    168 
    169 == Modifiers
    170 
    171 Some modifiers can control the matching behavior of the atoms following
    172 them:
    173 
    174 * `(?i)` starts case-insensitive matching.
    175 * `(?I)` starts case-sensitive matching (default).
    176 * `(?s)` allows `.` to match newlines (default).
    177 * `(?S)` prevents `.` from matching newlines.
    178 
    179 == Quoting
    180 
    181 `\Q` will start a quoted sequence, where every character is treated as
    182 a literal. That quoted sequence will continue until either the end of
    183 the regex, or the appearance of `\E`.
    184 
    185 For example, `.\Q.^$\E$` will match any character followed by the
    186 literal string `.^$`, followed by an end of line.
    187 
    188 == Compatibility
    189 
    190 Kakoune's syntax tries to follow the ECMAScript regex syntax, as defined
    191 by <https://www.ecma-international.org/ecma-262/8.0/>; some divergence
    192 exists for ease of use, or performance reasons:
    193 
    194 * Lookarounds are not arbitrary, but lookbehind is supported.
    195 * `\K`, `\N`, `\Q..\E`, `\A`, `\h` and `\z` are added.
    196 * Stricter handling of escaping, as we introduce additional escapes;
    197   identity escapes like `\X` with `X` being a non-special character
    198   are not accepted, to avoid confusions between `\h` meaning literal
    199   `h` in ECMAScript, and horizontal blank in Kakoune.
    200 * `\uXXXXXX` uses 6 digits to cover all of Unicode, instead of relying
    201   on ECMAScript UTF-16 surrogate pairs with 4 digits.