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.