summaryrefslogtreecommitdiff
path: root/support/highlight/README_REGEX
blob: cf7b7e1436dde9b42f769ab896a5c9a6701d6250 (plain)
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
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
-------------------------------------------------------------------------------
---  REGULAR EXPRESSIONS MANUAL -----------------------------------------------
-------------------------------------------------------------------------------

This file is based on the original API documentation of Jeffery Stuart's
Pattern class.

-------------------------------------------------------------------------------

You can use regular expressions in highlight language definitions.
Note that the expression has to be defined as regex(<RE> <, GRUP-NUM>), where
RE is the regex string, and GROUP-NUM is an optional parameter which defines
the group number whose match should be returned.

See README which definition parameters support regular expressions.


Content:
--------

- Regex rules
- Backslashes, escapes, and quoting
- Character Classes
- Groups and capturing
- Examples

-------------------------------------------------------------------------------


Regex rules:
------------

Construct       Matches

Characters

x               The character x
\\              The character \
\0nn            The character with octal ASCII value nn
\0nnn           The character with octal ASCII value nnn
\xhh            The character with hexadecimal ASCII value hh
\t              A tab character
\r              A carriage return character
\n              A new-line character


Character Classes

[abc]           Either a, b, or c
[^abc]          Any character but a, b, or c
[a-zA-Z]        Any character ranging from a thru z, or A thru Z
[^a-zA-Z]       Any character except those ranging from a thru z, or A thru Z
[a\-z]          Either a, -, or z
[a-z[A-Z]]      Same as [a-zA-Z]
[a-z&&[g-i]]    Any character in the intersection of a-z and g-i
[a-z&&[^g-i]]   Any character in a-z and not in g-i


Predefined character classes

.               Any character. Multiline matching must be compiled into the
                pattern for . to match a \r or a \n. Even if multiline matching
                is enabled, . will not match a \r\n, only a \r or a \n.
\d              [0-9]
\D              [^\d]
\s              [ \t\r\n\x0B]
\S              [^\s]
\w              [a-zA-Z0-9_]
\W              [^\w]


POSIX character classes

\p{Lower}       [a-z]
\p{Upper}       [A-Z]
\p{ASCII}       [\x00-\x7F]
\p{Alpha}       [a-zA-Z]
\p{Digit}       [0-9]
\p{Alnum}       [\w&&[^_]]
\p{Punct}       [!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~]
\p{XDigit}      [a-fA-F0-9]


Boundary Matches

^               The beginning of a line. Also matches the beginning of input.
$               The end of a line. Also matches the end of input.
\b              A word boundary
\B              A non word boundary
\A              The beginning of input
\G              The end of the previous match. Ensures that a "next" match will
                only happen if it begins with the character immediately 
                following the end of the "current" match.
\Z              The end of input. Will also match if there is a single trailing
                \r\n, a single trailing \r, or a single trailing \n.
\z              The end of input


Greedy Quantifiers

x?              x, either zero times or one time
x*              x, zero or more times
x+              x, one or more times
x{n}            x, exactly n times
x{n,}           x, at least n times
x{,m}           x, at most m times
x{n,m}          x, at least n times and at most m times


Possessive Quantifiers

x?+             x, either zero times or one time
x*+             x, zero or more times
x++             x, one or more times
x{n}+           x, exactly n times
x{n,}+          x, at least n times
x{,m}+          x, at most m times
x{n,m}+         x, at least n times and at most m times


Reluctant Quantifiers

x??             x, either zero times or one time
x*?             x, zero or more times
x+?             x, one or more times
x{n}?           x, exactly n times
x{n,}?          x, at least n times
x{,m}?          x, at most m times
x{n,m}?         x, at least n times and at most m times


Operators

xy              x then y
x|y             x or y
(x)             x as a capturing group


Quoting

\Q              Nothing, but treat every character (including \s) literally 
                until a matching \E
\E              Nothing, but ends its matching \Q

Special Constructs

(?:x)           x, but not as a capturing group
(?=x)           x, via positive lookahead. This means that the expression will
                match only if it is trailed by x. It will not "eat" any of the
                characters matched by x.
(?!x)           x, via negative lookahead. This means that the expression will
                match only if it is not trailed by x. It will not "eat" any of
                the characters matched by x.
(?<=x)          x, via positive lookbehind. x cannot contain any quantifiers.
(?x)            x, via negative lookbehind. x cannot contain any quantifiers.
(?>x)           x{1}+



Backslashes, escapes, and quoting:
----------------------------------

The backslash character ('\') serves to introduce escaped constructs, as defined
in the table above, as well as to quote characters that otherwise would be
interpreted as unescaped constructs. Thus the expression \\ matches a single
backslash and \{ matches a left brace.

It is an error to use a backslash prior to any alphabetic character that does
not denote an escaped construct; these are reserved for future extensions to the
regular-expression language. A backslash may be used prior to a non-alphabetic
character regardless of whether that character is part of an unescaped
construct.

It is necessary to double backslashes in string literals that represent regular
expressions to protect them from interpretation by a compiler. The string
literal "\b", for example, matches a single backspace character when interpreted
as a regular expression, while "\\b" matches a word boundary. The string litera
"\(hello\)" is illegal and leads to a compile-time error; in order to match the
string (hello) the string literal "\\(hello\\)" must be used.


Character Classes:
------------------

Character classes may appear within other character classes, and may be composed
by the union operator (implicit) and the intersection operator (&&). The union
operator denotes a class that contains every character that is in at least one
of its operand classes. The intersection operator denotes a class that contains
every character that is in both of its operand classes.

The precedence of character-class operators is as follows, from highest to
lowest:

 1   Literal escape    \x
 2   Range             a-z
 3   Grouping          [...]
 4   Intersection      [a-z&&[aeiou]]
 5   Union             [a-e][i-u]

Note that a different set of metacharacters are in effect inside a character
class than outside a character class. For instance, the regular expression .
loses its special meaning inside a character class, while the expression -
becomes a range forming metacharacter.


Groups and capturing:
---------------------

Capturing groups are numbered by counting their opening parentheses from left to
right. In the expression ((A)(B(C))), for example, there are four such groups:

 1 ((A)(B(C)))
 2 (A)
 3 (B(C))
 4 (C)

Group zero always stands for the entire expression. Note that highlight will 
only evaluate the highest group number to make regular expressions more suitable
for language definitions. Use (?:) syntax to avoid a capture of the new group.


Examples:
---------

$KEYWORDS(kwa)=regex([A-Z]\w+)
Highlight identifiers beginning with a capital letter.

$KEYWORDS(kwb)=regex([$@%]\w+)
Highlight variables beginning with $, @ or %.

$KEYWORDS(kwc)=regex(\$\{(\w+)\})
or
$KEYWORDS(kwc)=regex(\$\{(\w+)\}, 1)
Highlight variable names like ${name}. Only the name is highlighted as keyword.
The grouping feature is used to achieve this effect. If no capturing group
index is defined (like in the first example above), the right-most group's match
(highest capturing index) is returned.

$KEYWORDS(kwd)=regex((\w+)\s*\()
Highlight method names. Note that grouping is used again.


---
Andre Simon
andre.simon1@gmx.de
http://www.andre-simon.de/
http://wiki.andre-simon.de/