Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/libs/regex/doc/syntax_extended.html @ 33

Last change on this file since 33 was 29, checked in by landauf, 17 years ago

updated boost from 1_33_1 to 1_34_1
File size: 24.1 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<html>
3   <head>
4      <title>Boost.Regex: POSIX-Extended Regular Expression Syntax</title>
5      <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
6      <LINK href="../../../boost.css" type="text/css" rel="stylesheet"></head>
7   <body>
8      <P>
9         <TABLE id="Table1" cellSpacing="1" cellPadding="1" width="100%" border="0">
10            <TR>
11               <td vAlign="top" width="300">
12                  <h3><A href="../../../index.htm"><IMG height="86" alt="C++ Boost" src="../../../boost.png" width="277" border="0"></A></h3>
13               </td>
14               <TD width="353">
15                  <H1 align="center">Boost.Regex</H1>
16                  <H2 align="center">POSIX-Extended Regular Expression Syntax</H2>
17               </TD>
18               <td width="50">
19                  <h3><A href="index.html"><IMG height="45" alt="Boost.Regex Index" src="uarrow.gif" width="43" border="0"></A></h3>
20               </td>
21            </TR>
22         </TABLE>
23      </P>
24      <HR>
25      <H3>Contents</H3>
26      <dl class="index">
27         <dt><A href="#synopsis">Synopsis</A> <dt><A href="#extended">POSIX&nbsp;Extended Syntax</A>
28               <dt><A href="#variations">Variations</A>
29                  <dd>
30                     <dl>
31                        <dt><A href="#egrep">egrep</A> <dt><A href="#awk">awk</A>&nbsp;</dt>
32                     </dl>
33                     <dt><A href="#options">Options</A> <dt><A href="#refs">References</A></dt>
34      </dl>
35      <H3><A name="synopsis"></A>Synopsis</H3>
36      <P>The POSIX-Extended regular expression syntax is supported by the POSIX C
37         regular expression API's, and variations are used by the utilities <EM>egrep</EM>
38         and <EM>awk</EM>. You can construct POSIX extended regular expressions in
39         Boost.Regex by passing the flag <EM>extended</EM> to the regex constructor, for
40         example:</P>
41      <PRE>// e1 is a case sensitive POSIX-Extended expression:
42boost::regex e1(my_expression, boost::regex::extended);
43// e2 a case insensitive POSIX-Extended expression:
44boost::regex e2(my_expression, boost::regex::extended|boost::regex::icase);</PRE>
45      <H3>POSIX Extended Syntax<A name="extended"></A></H3>
46      <P>In POSIX-Extended regular expressions, all characters match themselves except
47         for the following special characters:</P>
48      <PRE>.[{()\*+?|^$</PRE>
49      <H4>Wildcard:</H4>
50      <P>The single character '.' when used outside of a character set will match any
51         single character except:</P>
52      <P>The NULL character when the flag <EM>match_no_dot_null</EM> is passed to the
53         matching algorithms.</P>
54      <P>The newline character when the flag <EM>match_not_dot_newline</EM> is passed to
55         the matching algorithms.</P>
56      <H4>Anchors:</H4>
57      <P>A '^' character shall match the start of a line when used as the first
58         character of an expression, or the first character of a sub-expression.</P>
59      <P>A '$' character shall match the end of a line when used as the last character
60         of an expression, or the last character of a sub-expression.</P>
61      <H4>Marked sub-expressions:</H4>
62      <P>A section beginning ( and ending ) acts as a marked sub-expression.&nbsp; 
63         Whatever matched the sub-expression is split out in a separate field by the
64         matching algorithms.&nbsp; Marked sub-expressions can also repeated, or
65         referred to by a back-reference.</P>
66      <H4>Repeats:</H4>
67      <P>Any atom (a single character, a marked sub-expression, or a character class)
68         can be repeated with the *, +, ?, and {}&nbsp;operators.</P>
69      <P>The * operator will match the preceding atom zero or more times, for example
70         the expression a*b will match any of the following:</P>
71      <PRE>b
72ab
73aaaaaaaab</PRE>
74      <P>The + operator will match the preceding atom one or more times, for example the
75         expression a+b will match any of the following:</P>
76      <PRE>ab
77aaaaaaaab</PRE>
78      <P>But will not match:</P>
79      <PRE>b</PRE>
80      <P>The ? operator will match the preceding atom zero or&nbsp;one times, for
81         example the expression ca?b will match any of the following:</P>
82      <PRE>cb
83cab</PRE>
84      <P>But will not match:</P>
85      <PRE>caab</PRE>
86      <P>An atom can also be repeated with a bounded repeat:</P>
87      <P>a{n}&nbsp; Matches 'a' repeated exactly <EM>n</EM> times.</P>
88      <P>a{n,}&nbsp; Matches 'a' repeated <EM>n</EM> or more times.</P>
89      <P>a{n, m}&nbsp; Matches 'a' repeated between <EM>n</EM> and <EM>m</EM> times
90         inclusive.</P>
91      <P>For example:</P>
92      <PRE>^a{2,3}$</PRE>
93      <P>Will match either of:</P>
94      <PRE>aa
95aaa</PRE>
96      <P>But neither of:</P>
97      <PRE>a
98aaaa</PRE>
99      <P>It is an error to use a repeat operator, if the preceding construct can not be
100         repeated, for example:</P>
101      <PRE>a(*)</PRE>
102      <P>Will raise an error, as there is nothing for the * operator to be applied to.</P>
103      <H4>Back references:</H4>
104      <P>An escape character followed by a digit <EM>n</EM>, where <EM>n </EM>is in the
105         range 1-9, matches the same string that was matched by sub-expression <EM>n</EM>.&nbsp; 
106         For example the expression:</P>
107      <PRE>^(a*).*\1$</PRE>
108      <P>Will match the string:</P>
109      <PRE>aaabbaaa</PRE>
110      <P>But not the string:</P>
111      <PRE>aaabba</PRE>
112      <P><EM><STRONG>Caution</STRONG>: the POSIX standard does not support back-references
113            for "extended" regular expressions, this is a compatible extension to that
114            standard.</EM></P>
115      <H4>Alternation</H4>
116      <P>The | operator will match either of its arguments, so for example: abc|def will
117         match either "abc" or "def".&nbsp;
118      </P>
119      <P>Parenthesis can be used to group alternations, for example: ab(d|ef) will match
120         either of "abd" or "abef".</P>
121      <H4>Character sets:</H4>
122      <P>A character set is a bracket-expression starting with [ and ending with ], it
123         defines a set of characters, and matches any single character that is a member
124         of that set.</P>
125      <P>A bracket expression may contain any combination of the following:</P>
126      <BLOCKQUOTE dir="ltr" style="MARGIN-RIGHT: 0px">
127         <H5>Single characters:</H5>
128         <P>For example [abc], will match any of the characters 'a', 'b', or 'c'.</P>
129         <H5>Character ranges:</H5>
130         <P>For example [a-c] will match any single character in the range 'a' to
131            'c'.&nbsp; By default, for POSIX-Extended regular expressions, a character <EM>x</EM>
132            is within the range <EM>y</EM> to <EM>z</EM>, if it collates within that
133            range;&nbsp;<EM><STRONG>this results in locale specific behavior</STRONG></EM> .&nbsp; 
134            This behavior can be turned off by unsetting the <EM><A href="syntax_option_type.html#extended">
135                  collate</A></EM> option flag - in which case whether a character appears
136            within a range is determined by comparing the code points of the characters
137            only.</P>
138         <H5>Negation:</H5>
139         <P>If the bracket-expression begins with the ^ character, then it matches the
140            complement of the characters it contains, for example [^a-c] matches any
141            character that is not in the range a-c.</P>
142         <H5>Character classes:</H5>
143         <P>An expression of the form [[:name:]] matches the named character class "name",
144            for example [[:lower:]] matches any lower case character.&nbsp; See <A href="character_class_names.html">
145               character class names</A>.</P>
146         <H5>Collating Elements:</H5>
147         <P>An expression of the form [[.col.] matches the collating element <EM>col</EM>.&nbsp; 
148            A collating element is any single character, or any sequence of characters that
149            collates as a single unit.&nbsp; Collating elements may also be used as the end
150            point of a range, for example: [[.ae.]-c] matches the character sequence "ae",
151            plus any single character in the range "ae"-c, assuming that "ae" is treated as
152            a single collating element in the current locale.</P>
153         <P>Collating elements may be used in place of escapes (which are not normally
154            allowed inside character sets), for example [[.^.]abc] would match either one
155            of the characters 'abc^'.</P>
156         <P>As an extension, a collating element may also be specified via its <A href="collating_names.html">
157               symbolic name</A>, for example:</P>
158         <P>[[.NUL.]]</P>
159         <P>matches a NUL character.</P>
160         <H5>Equivalence classes:</H5>
161         <P>
162            An expression oftheform[[=col=]], matches any character or collating element
163            whose primary sort key is the same as that for collating element <EM>col</EM>,
164            as with colating elements the name <EM>col</EM> may be a <A href="collating_names.html">
165               symbolic name</A>.&nbsp; A primary sort key is one that ignores case,
166            accentation, or locale-specific tailorings; so for example [[=a=]] matches any
167            of the characters: a, à, á, â, ã, ä, å, A, À, Á, Â, Ã, Ä and Å.&nbsp; 
168            Unfortunately implementation of this is reliant on the platform's collation and
169            localisation support; this feature can not be relied upon to work portably
170            across all platforms, or even all locales on one platform.</P>
171      </BLOCKQUOTE>
172      <H5>Combinations:</H5>
173      <P>All of the above can be combined in one character set declaration, for example:
174         [[:digit:]a-c[.NUL.]].</P>
175      <H4>Escapes</H4>
176      <P>The POSIX standard defines no escape sequences for POSIX-Extended regular
177         expressions, except that:</P>
178      <UL>
179         <LI>
180         Any special character preceded by an escape shall match itself.
181         <LI>
182         The effect of any ordinary character being preceded by an escape is undefined.
183         <LI>
184            An escape inside a character class declaration shall match itself: in other
185            words the escape character is not "special" inside a character class
186            declaration; so [\^] will match either a literal '\' or a '^'.</LI></UL>
187      <P>However, that's rather restrictive, so the following standard-compatible
188         extensions are also supported by Boost.Regex:</P>
189      <BLOCKQUOTE dir="ltr" style="MARGIN-RIGHT: 0px">
190         <H5>Escapes matching a specific character</H5>
191         <P>The following escape sequences are all synonyms for single characters:</P>
192         <P>
193            <TABLE id="Table7" cellSpacing="1" cellPadding="1" width="100%" border="1">
194               <TR>
195                  <TD><STRONG>Escape</STRONG></TD>
196                  <TD><STRONG>Character</STRONG></TD>
197               </TR>
198               <TR>
199                  <TD>\a</TD>
200                  <TD>'\a'</TD>
201               </TR>
202               <TR>
203                  <TD>\e</TD>
204                  <TD>0x1B</TD>
205               </TR>
206               <TR>
207                  <TD>\f</TD>
208                  <TD>\f</TD>
209               </TR>
210               <TR>
211                  <TD>\n</TD>
212                  <TD>\n</TD>
213               </TR>
214               <TR>
215                  <TD>\r</TD>
216                  <TD>\r</TD>
217               </TR>
218               <TR>
219                  <TD>\t</TD>
220                  <TD>\t</TD>
221               </TR>
222               <TR>
223                  <TD>\v</TD>
224                  <TD>\v</TD>
225               </TR>
226               <TR>
227                  <TD>\b</TD>
228                  <TD>\b (but only inside a character class declaration).</TD>
229               </TR>
230               <TR>
231                  <TD>\cX</TD>
232                  <TD>An ASCII escape sequence - the character whose code point is X % 32</TD>
233               </TR>
234               <TR>
235                  <TD>\xdd</TD>
236                  <TD>A hexadecimal escape sequence - matches the single character whose code point
237                     is 0xdd.</TD>
238               </TR>
239               <TR>
240                  <TD>\x{dddd}</TD>
241                  <TD>A hexadecimal escape sequence - matches the single character whose code point
242                     is 0xdddd.</TD>
243               </TR>
244               <TR>
245                  <TD>\0ddd</TD>
246                  <TD>An octal escape sequence - matches the single character whose code point is
247                     0ddd.</TD>
248               </TR>
249               <TR>
250                  <TD>\N{Name}</TD>
251                  <TD>Matches the single character which has the <A href="collating_names.html">symbolic
252                        name</A> <EM>name.&nbsp; </EM>For example \N{newline} matches the single
253                     character \n.</TD>
254               </TR>
255            </TABLE>
256         </P>
257         <H5>"Single character" character&nbsp;classes:</H5>
258         <P>Any escaped character <EM>x</EM>, if <EM>x</EM> is the name of a character
259            class shall match any character that is a member of that class, and any escaped
260            character <EM>X</EM>, if <EM>x</EM> is the name of a character class, shall
261            match any character not in that class.</P>
262         <P>The following are supported by default:</P>
263         <P>
264            <TABLE id="Table3" cellSpacing="1" cellPadding="1" width="300" border="1">
265               <TR>
266                  <TD><STRONG>Escape sequence</STRONG></TD>
267                  <TD><STRONG>Equivalent to</STRONG></TD>
268               </TR>
269               <TR>
270                  <TD>\d</TD>
271                  <TD>[[:digit:]]</TD>
272               </TR>
273               <TR>
274                  <TD>\l</TD>
275                  <TD>[[:lower:]]</TD>
276               </TR>
277               <TR>
278                  <TD>\s</TD>
279                  <TD>[[:space:]]</TD>
280               </TR>
281               <TR>
282                  <TD>\u</TD>
283                  <TD>[[:upper:]]</TD>
284               </TR>
285               <TR>
286                  <TD>\w</TD>
287                  <TD>[[:word:]]</TD>
288               </TR>
289               <TR>
290                  <TD>\D</TD>
291                  <TD>[^[:digit:]]</TD>
292               </TR>
293               <TR>
294                  <TD>\L</TD>
295                  <TD>[^[:lower:]]</TD>
296               </TR>
297               <TR>
298                  <TD>\S</TD>
299                  <TD>[^[:space:]]</TD>
300               </TR>
301               <TR>
302                  <TD>\U</TD>
303                  <TD>[^[:upper:]]</TD>
304               </TR>
305               <TR>
306                  <TD>\W</TD>
307                  <TD>[^[:word:]]</TD>
308               </TR>
309            </TABLE>
310         </P>
311         <H5>
312            <H5>Character Properties</H5>
313         </H5>
314         <P dir="ltr">The character property names in the following table are all
315            equivalent to the <A href="character_class_names.html">names used in character
316               classes</A>.</P>
317         <H5>
318            <TABLE id="Table9" cellSpacing="1" cellPadding="1" width="100%" border="0">
319               <TR>
320                  <TD><STRONG>Form</STRONG></TD>
321                  <TD><STRONG>Description</STRONG></TD>
322                  <TD><STRONG>Equivalent character set form</STRONG></TD>
323               </TR>
324               <TR>
325                  <TD>\pX</TD>
326                  <TD>Matches any character that has the property X.</TD>
327                  <TD>[[:X:]]</TD>
328               </TR>
329               <TR>
330                  <TD>\p{Name}</TD>
331                  <TD>Matches any character that has the property <EM>Name</EM>.</TD>
332                  <TD>[[:Name:]]</TD>
333               </TR>
334               <TR>
335                  <TD>\PX</TD>
336                  <TD>Matches any character that does not have the property X.</TD>
337                  <TD>[^[:X:]]</TD>
338               </TR>
339               <TR>
340                  <TD>\P{Name}</TD>
341                  <TD>Matches any character that does not have the property <EM>Name</EM>.</TD>
342                  <TD>[^[:Name:]]</TD>
343               </TR>
344            </TABLE>
345         </H5>
346         <H5>Word Boundaries</H5>
347         <P>The following escape sequences match the boundaries of words:</P>
348         <P>
349            <TABLE id="Table4" cellSpacing="1" cellPadding="1" width="100%" border="1">
350               <TR>
351                  <TD>\&lt;</TD>
352                  <TD>Matches the start of a word.</TD>
353               </TR>
354               <TR>
355                  <TD>\&gt;</TD>
356                  <TD>Matches the end of a word.</TD>
357               </TR>
358               <TR>
359                  <TD>\b</TD>
360                  <TD>Matches a word boundary (the start or end of a word).</TD>
361               </TR>
362               <TR>
363                  <TD>\B</TD>
364                  <TD>Matches only when not at a word boundary.</TD>
365               </TR>
366            </TABLE>
367         </P>
368         <H5>Buffer boundaries</H5>
369         <P>The following match only at buffer boundaries: a "buffer" in this context is
370            the whole of the input text&nbsp;that is being matched against (note that ^ and
371            $ may match embedded newlines within the text).</P>
372         <P>
373            <TABLE id="Table5" cellSpacing="1" cellPadding="1" width="100%" border="1">
374               <TR>
375                  <TD>\`</TD>
376                  <TD>Matches at the start of a buffer only.</TD>
377               </TR>
378               <TR>
379                  <TD>\'</TD>
380                  <TD>Matches at the end of a buffer only.</TD>
381               </TR>
382               <TR>
383                  <TD>\A</TD>
384                  <TD>Matches at the start of a buffer only (the same as \`).</TD>
385               </TR>
386               <TR>
387                  <TD>\z</TD>
388                  <TD>Matches at the end of a buffer only (the same as \').</TD>
389               </TR>
390               <TR>
391                  <TD>\Z</TD>
392                  <TD>Matches an optional sequence of newlines at the end of a buffer: equivalent to
393                     the regular expression \n*\z</TD>
394               </TR>
395            </TABLE>
396         </P>
397         <H5>Continuation Escape</H5>
398         <P>The sequence \G matches only at the end of the last match found, or at the
399            start of the text being matched if no previous match was found.&nbsp; This
400            escape useful if you're iterating over the matches contained within a text, and
401            you want each subsequence match to start where the last one ended.</P>
402         <H5>Quoting escape</H5>
403         <P>The escape sequence \Q begins a "quoted sequence": all the subsequent
404            characters are treated as literals, until either the end of the regular
405            expression or \E is found.&nbsp; For example the expression: \Q\*+\Ea+ would
406            match either of:</P>
407         <PRE>\*+a<BR>\*+aaa</PRE>
408         <H5>Unicode escapes</H5>
409         <P>
410            <TABLE id="Table6" cellSpacing="1" cellPadding="1" width="100%" border="1">
411               <TR>
412                  <TD>\C</TD>
413                  <TD>Matches a single code point: in Boost regex this has exactly the same effect
414                     as a "." operator.</TD>
415               </TR>
416               <TR>
417                  <TD>\X</TD>
418                  <TD>Matches a combining character sequence: that is any non-combining character
419                     followed by a sequence of zero or more combining characters.</TD>
420               </TR>
421            </TABLE>
422         </P>
423         <H5>Any other escape</H5>
424         <P>Any other escape sequence matches the character that is escaped, for example \@
425            matches a literal <A href="mailto:'@'">'@'</A>.</P>
426      </BLOCKQUOTE><A name="variations">
427         <H4>Operator precedence</H4>
428         <P>&nbsp;The order of precedence for of operators is as shown in the following
429            table:</P>
430         <P>
431            <TABLE id="Table2" cellSpacing="1" cellPadding="1" width="100%" border="1">
432               <TR>
433                  <TD>Collation-related bracket symbols</TD>
434                  <TD>[==] [::] [..]</TD>
435               </TR>
436               <TR>
437                  <TD>Escaped characters
438                  </TD>
439                  <TD>\</TD>
440               </TR>
441               <TR>
442                  <TD>Character set&nbsp;(bracket expression)
443                  </TD>
444                  <TD>[]</TD>
445               </TR>
446               <TR>
447                  <TD>Grouping</TD>
448                  <TD>()</TD>
449               </TR>
450               <TR>
451                  <TD>Single-character-ERE duplication
452                  </TD>
453                  <TD>* + ? {m,n}</TD>
454               </TR>
455               <TR>
456                  <TD>Concatenation</TD>
457                  <TD></TD>
458               </TR>
459               <TR>
460                  <TD>Anchoring</TD>
461                  <TD>^$</TD>
462               </TR>
463               <TR>
464                  <TD>Alternation</TD>
465                  <TD>|</TD>
466               </TR>
467            </TABLE>
468         </P>
469      </A>
470      <H4>What Gets Matched</H4>
471      <P>When there is more that one way to match a regular expression, the "best"
472         possible match is obtained using the <A href="syntax_leftmost_longest.html">leftmost-longest
473            rule</A>.</P>
474      <H3>Variations</H3>
475      <H4>Egrep<A name="egrep"></H4>
476      <P>When an expression is compiled with the flag <EM>egrep</EM> set, then the
477         expression is treated as a newline separated list of POSIX-Extended
478         expressions, a match is found if any of the expressions in the list match, for
479         example:</P>
480      <PRE>boost::regex e("abc\ndef", boost::regex::egrep);</PRE>
481      <P>will match either of the POSIX-Basic expressions "abc" or "def".</P>
482      <P>As its name suggests, this behavior is consistent with the Unix utility <EM>egrep</EM>,
483         and with <EM>grep</EM> when used with the -E option.</P>
484      <H4>awk<A name="awk"></A></H4>
485      <P>In addition to the <A href="#extended">POSIX-Extended features</A>&nbsp;the
486         escape character is special inside a character class declaration.&nbsp;</P>
487      <P>In addition, some escape sequences that are not defined as part of
488         POSIX-Extended specification are required to be supported - however Boost.Regex
489         supports these by default anyway.</P>
490      <H3><A name="options"></A>Options</H3>
491      <P>There are a <A href="syntax_option_type.html#extended">variety of flags</A> that
492         may be combined with the <EM>extended</EM> and <EM>egrep</EM> options when
493         constructing the regular expression, in particular note that the <A href="syntax_option_type.html#extended">
494            newline_alt</A> option alters the syntax, while the <A href="syntax_option_type.html#extended">
495            collate, nosubs&nbsp;and icase</A> options modify how the case and locale
496         sensitivity are to be applied.</P>
497      <H3><A name="refs">References</H3>
498      <P><A href="http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap09.html"> IEEE
499            Std 1003.1-2001, Portable Operating System Interface (POSIX ), Base Definitions
500            and Headers, Section 9, Regular Expressions.</A></P>
501      <P><A href="http://www.opengroup.org/onlinepubs/000095399/utilities/grep.html"> IEEE
502            Std 1003.1-2001, Portable Operating System Interface (POSIX ), Shells and
503            Utilities, Section 4, Utilities, egrep.</A></P>
504      <P><A href="http://www.opengroup.org/onlinepubs/000095399/utilities/awk.html">IEEE
505            Std 1003.1-2001, Portable Operating System Interface (POSIX ), Shells and
506            Utilities, Section 4, Utilities, awk.</A></P>
507      <HR>
508      <P></P>
509      <p>Revised&nbsp; 
510         <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> 
511         21 Aug 2004&nbsp; 
512         <!--webbot bot="Timestamp" endspan i-checksum="39359" --></p>
513      <P><I>© Copyright <a href="mailto:jm@regex.fsnet.co.uk">John Maddock</a>&nbsp;2004</I></P>
514      <I>
515         <P><I>Use, modification and distribution are subject to the Boost Software License,
516               Version 1.0. (See accompanying file <A href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</A>
517               or copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>).</I></P>
518      </I>
519   </body>
520</html>
Note: See TracBrowser for help on using the repository browser.