2 Copyright 2006-2007 John Maddock.
3 Distributed under the Boost Software License, Version 1.0.
4 (See accompanying file LICENSE_1_0.txt or copy at
5 http://www.boost.org/LICENSE_1_0.txt).
9 [section:basic_extended POSIX Extended Regular Expression Syntax]
13 The POSIX-Extended regular expression syntax is supported by the POSIX
14 C regular expression API's, and variations are used by the utilities
15 `egrep` and `awk`. You can construct POSIX extended regular expressions in
16 Boost.Regex by passing the flag `extended` to the regex constructor, for example:
18 // e1 is a case sensitive POSIX-Extended expression:
19 boost::regex e1(my_expression, boost::regex::extended);
20 // e2 a case insensitive POSIX-Extended expression:
21 boost::regex e2(my_expression, boost::regex::extended|boost::regex::icase);
23 [#boost_regex.posix_extended_syntax][h3 POSIX Extended Syntax]
25 In POSIX-Extended regular expressions, all characters match themselves except for
26 the following special characters:
28 [pre .\[{}()\\\*+?|^$]
32 The single character '.' when used outside of a character set will match
33 any single character except:
35 * The NULL character when the flag `match_no_dot_null` is passed to the
37 * The newline character when the flag `match_not_dot_newline` is passed
38 to the matching algorithms.
42 A '^' character shall match the start of a line when used as the first
43 character of an expression, or the first character of a sub-expression.
45 A '$' character shall match the end of a line when used as the
46 last character of an expression, or the last character of a sub-expression.
48 [h4 Marked sub-expressions:]
50 A section beginning `(` and ending `)` acts as a marked sub-expression.
51 Whatever matched the sub-expression is split out in a separate field
52 by the matching algorithms. Marked sub-expressions can also repeated,
53 or referred to by a back-reference.
57 Any atom (a single character, a marked sub-expression, or a character class)
58 can be repeated with the `*`, `+`, `?`, and `{}` operators.
60 The `*` operator will match the preceding atom /zero or more times/, for
61 example the expression `a*b` will match any of the following:
69 The `+` operator will match the preceding atom /one or more times/,
70 for example the expression a+b will match any of the following:
83 The `?` operator will match the preceding atom /zero or one times/, for
84 example the expression `ca?b` will match any of the following:
96 An atom can also be repeated with a bounded repeat:
98 `a{n}` Matches 'a' repeated /exactly n times/.
100 `a{n,}` Matches 'a' repeated /n or more times/.
102 `a{n, m}` Matches 'a' repeated /between n and m times inclusive/.
108 Will match either of:
118 It is an error to use a repeat operator, if the preceding construct can not
119 be repeated, for example:
123 Will raise an error, as there is nothing for the `*` operator to be applied to.
125 [h4 Back references:]
127 An escape character followed by a digit /n/, where /n/ is in the range 1-9,
128 matches the same string that was matched by sub-expression /n/. For example
133 Will match the string:
141 [caution The POSIX standard does not support back-references for "extended"
142 regular expressions, this is a compatible extension to that standard.]
146 The `|` operator will match either of its arguments, so for example:
147 `abc|def` will match either "abc" or "def".
149 Parenthesis can be used to group alternations, for example: `ab(d|ef)`
150 will match either of "abd" or "abef".
154 A character set is a bracket-expression starting with \[ and ending with \],
155 it defines a set of characters, and matches any single character that is
156 a member of that set.
158 A bracket expression may contain any combination of the following:
160 [h5 Single characters:]
162 For example `[abc]`, will match any of the characters 'a', 'b', or 'c'.
164 [h5 Character ranges:]
166 For example `[a-c]` will match any single character in the range 'a' to 'c'.
167 By default, for POSIX-Extended regular expressions, a character /x/ is
168 within the range /y/ to /z/, if it collates within that range; this
169 results in locale specific behavior . This behavior can be turned
170 off by unsetting the `collate`
171 [link boost_regex.ref.syntax_option_type option flag] - in which case whether
172 a character appears within a range is determined by comparing the code
173 points of the characters only.
177 If the bracket-expression begins with the ^ character, then it matches the
178 complement of the characters it contains, for example `[^a-c]` matches
179 any character that is not in the range `a-c`.
181 [h5 Character classes:]
183 An expression of the form `[[:name:]]` matches the named character class "name",
184 for example `[[:lower:]]` matches any lower case character.
185 See [link boost_regex.syntax.character_classes character class names].
187 [h5 Collating Elements:]
189 An expression of the form `[[.col.]` matches the collating element /col/.
190 A collating element is any single character, or any sequence of
191 characters that collates as a single unit. Collating elements may
192 also be used as the end point of a range, for example: `[[.ae.]-c]`
193 matches the character sequence "ae", plus any single character
194 in the range "ae"-c, assuming that "ae" is treated as a single
195 collating element in the current locale.
197 Collating elements may be used in place of escapes (which are not
198 normally allowed inside character sets), for example `[[.^.]abc]`
199 would match either one of the characters 'abc^'.
201 As an extension, a collating element may also be specified via its
202 [link boost_regex.syntax.collating_names symbolic name], for example:
206 matches a NUL character.
208 [h5 Equivalence classes:]
210 An expression of the form `[[=col=]]`, matches any character or collating element
211 whose primary sort key is the same as that for collating element /col/,
212 as with collating elements the name /col/ may be a
213 [link boost_regex.syntax.collating_names symbolic name]. A primary
214 sort key is one that ignores case, accentation, or locale-specific tailorings;
215 so for example `[[=a=]]` matches any of the characters:
216 a, '''À''', '''Á''', '''Â''',
217 '''Ã''', '''Ä''', '''Å''', A, '''à''', '''á''',
218 '''â''', '''ã''', '''ä''' and '''å'''.
219 Unfortunately implementation of this is reliant on the platform's
220 collation and localisation support; this feature can not be relied
221 upon to work portably across all platforms, or even all locales on one platform.
225 All of the above can be combined in one character set declaration,
226 for example: `[[:digit:]a-c[.NUL.]]`.
230 The POSIX standard defines no escape sequences for POSIX-Extended
231 regular expressions, except that:
233 * Any special character preceded by an escape shall match itself.
234 * The effect of any ordinary character being preceded by an escape is undefined.
235 * An escape inside a character class declaration shall match itself: in
236 other words the escape character is not "special" inside a character
237 class declaration; so `[\^]` will match either a literal '\\' or a '^'.
239 However, that's rather restrictive, so the following standard-compatible
240 extensions are also supported by Boost.Regex:
242 [h5 Escapes matching a specific character]
244 The following escape sequences are all synonyms for single characters:
247 [[Escape][Character]]
255 [[\\b][\\b (but only inside a character class declaration).]]
256 [[\\cX][An ASCII escape sequence - the character whose code point is X % 32]]
257 [[\\xdd][A hexadecimal escape sequence - matches the single character whose code point is 0xdd.]]
258 [[\\x{dddd}][A hexadecimal escape sequence - matches the single character whose code point is 0xdddd.]]
259 [[\\0ddd][An octal escape sequence - matches the single character whose code point is 0ddd.]]
260 [[\\N{Name}][Matches the single character which has the symbolic name ['Name]. For example `\\N{newline}` matches the single character \\n.]]
263 [h5 "Single character" character classes:]
265 Any escaped character /x/, if /x/ is the name of a character class shall
266 match any character that is a member of that class, and any
267 escaped character /X/, if /x/ is the name of a character class,
268 shall match any character not in that class.
270 The following are supported by default:
273 [[Escape sequence][Equivalent to]]
274 [[`\d`][`[[:digit:]]`]]
275 [[`\l`][`[[:lower:]]`]]
276 [[`\s`][`[[:space:]]`]]
277 [[`\u`][`[[:upper:]]`]]
278 [[`\w`][`[[:word:]]`]]
279 [[`\D`][`[^[:digit:]]`]]
280 [[`\L`][`[^[:lower:]]`]]
281 [[`\S`][`[^[:space:]]`]]
282 [[`\U`][`[^[:upper:]]`]]
283 [[`\W`][`[^[:word:]]`]]
286 [h5 Character Properties]
288 The character property names in the following table are all equivalent to the
289 names used in character classes.
292 [[Form][Description][Equivalent character set form]]
293 [[`\pX`][Matches any character that has the property X.][`[[:X:]]`]]
294 [[`\p{Name}`][Matches any character that has the property Name.][`[[:Name:]]`]]
295 [[`\PX`][Matches any character that does not have the property X.][`[^[:X:]]`]]
296 [[`\P{Name}`][Matches any character that does not have the property Name.][`[^[:Name:]]`]]
299 For example `\pd` matches any "digit" character, as does `\p{digit}`.
303 The following escape sequences match the boundaries of words:
307 [[`\<`][Matches the start of a word.]]
308 [[`\>`][Matches the end of a word.]]
309 [[`\b`][Matches a word boundary (the start or end of a word).]]
310 [[`\B`][Matches only when not at a word boundary.]]
313 [h5 Buffer boundaries]
315 The following match only at buffer boundaries: a "buffer" in this
316 context is the whole of the input text that is being matched against
317 (note that ^ and $ may match embedded newlines within the text).
321 [[\\\`][Matches at the start of a buffer only.]]
322 [[\\'][Matches at the end of a buffer only.]]
323 [[`\A`][Matches at the start of a buffer only (the same as \\\`).]]
324 [[`\z`][Matches at the end of a buffer only (the same as \\').]]
325 [[`\Z`][Matches an optional sequence of newlines at the end of a buffer:
326 equivalent to the regular expression `\n*\z`]]
329 [h5 Continuation Escape]
331 The sequence `\G` matches only at the end of the last match found, or at
332 the start of the text being matched if no previous match was found.
333 This escape useful if you're iterating over the matches contained within
334 a text, and you want each subsequence match to start where the last one ended.
338 The escape sequence `\Q` begins a "quoted sequence": all the subsequent
339 characters are treated as literals, until either the end of the
340 regular expression or `\E` is found. For example the expression: `\Q\*+\Ea+`
341 would match either of:
350 [[`\C`][Matches a single code point: in Boost regex this has exactly the same effect as a "." operator.]]
351 [[`\X`][Matches a combining character sequence: that is any non-combining character followed by a sequence of zero or more combining characters.]]
354 [h5 Any other escape]
356 Any other escape sequence matches the character that is escaped,
357 for example \\@ matches a literal '@'.
359 [h4 Operator precedence]
361 The order of precedence for of operators is as follows:
363 # Collation-related bracket symbols `[==] [::] [..]`
364 # Escaped characters `\`
365 # Character set (bracket expression) `[]`
367 # Single-character-ERE duplication `* + ? {m,n}`
372 [h4 What Gets Matched]
374 When there is more that one way to match a regular expression, the
375 "best" possible match is obtained using the
376 [link boost_regex.syntax.leftmost_longest_rule leftmost-longest rule].
382 When an expression is compiled with the
383 [link boost_regex.ref.syntax_option_type flag `egrep`] set, then the
384 expression is treated as a newline separated list of
385 [link boost_regex.posix_extended_syntax POSIX-Extended expressions],
386 a match is found if any of the
387 expressions in the list match, for example:
389 boost::regex e("abc\ndef", boost::regex::egrep);
391 will match either of the POSIX-Basic expressions "abc" or "def".
393 As its name suggests, this behavior is consistent with the Unix utility `egrep`,
394 and with grep when used with the -E option.
399 [link boost_regex.posix_extended_syntax POSIX-Extended features] the
401 special inside a character class declaration.
403 In addition, some escape sequences that are not defined as part of
404 POSIX-Extended specification are required to be supported - however Boost.Regex
405 supports these by default anyway.
409 There are a [link boost_regex.ref.syntax_option_type.syntax_option_type_extended variety of flags]
410 that may be combined with the `extended` and `egrep` options when
411 constructing the regular expression, in particular note that the
412 [link boost_regex.ref.syntax_option_type.syntax_option_type_extended `newline_alt`]
413 option alters the syntax, while the
414 [link boost_regex.ref.syntax_option_type.syntax_option_type_extended `collate`, `nosubs`
415 and `icase` options] modify how the case and locale sensitivity are to be applied.
419 [@http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap09.html
420 IEEE Std 1003.1-2001, Portable Operating System Interface (POSIX ), Base Definitions and Headers, Section 9, Regular Expressions.]
422 [@http://www.opengroup.org/onlinepubs/000095399/utilities/grep.html
423 IEEE Std 1003.1-2001, Portable Operating System Interface (POSIX ), Shells and Utilities, Section 4, Utilities, egrep.]
425 [@http://www.opengroup.org/onlinepubs/000095399/utilities/awk.html
426 IEEE Std 1003.1-2001, Portable Operating System Interface (POSIX ), Shells and Utilities, Section 4, Utilities, awk.]