Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/libs/regex/doc/syntax_basic.html @ 29

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

updated boost from 1_33_1 to 1_34_1
File size: 14.0 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<html>
3   <head>
4      <title>Boost.Regex: POSIX-Basic 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 Basic 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="#Basic">POSIX Basic Syntax</A> <dt><A href="#variations">
28                     Variations</A>
29                  <dd>
30                     <dl>
31                        <dt><A href="#grep">Grep</A> <dt><A href="#emacs">Emacs</A></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-Basic regular expression syntax is used by the Unix utility <EM>sed</EM>,
37         and variations are used by <EM>grep</EM> and <EM>emacs</EM>.&nbsp; You can
38         construct POSIX basic regular expressions in Boost.Regex by passing the flag <EM>basic</EM>
39         to the regex constructor, for example:</P>
40      <PRE>// e1 is a case sensitive POSIX-Basic expression:
41boost::regex e1(my_expression, boost::regex::basic);
42// e2 a case insensitive POSIX-Basic expression:
43boost::regex e2(my_expression, boost::regex::basic|boost::regex::icase);</PRE>
44      <H3>POSIX Basic Syntax<A name="Basic"></A></H3>
45      <P>In POSIX-Basic regular expressions, all characters are match themselves except
46         for the following special characters:</P>
47      <PRE>.[\*^$</PRE>
48      <H4>Wildcard:</H4>
49      <P>The single character '.' when used outside of a character set will match any
50         single character except:</P>
51      <P>The NULL character when the flag <EM>match_no_dot_null</EM> is passed to the
52         matching algorithms.</P>
53      <P>The newline character when the flag <EM>match_not_dot_newline</EM> is passed to
54         the matching algorithms.</P>
55      <H4>Anchors:</H4>
56      <P>A '^' character shall match the start of a line when used as the first
57         character of an expression, or the first character of a sub-expression.</P>
58      <P>A '$' character shall match the end of a line when used as the last character
59         of an expression, or the last character of a sub-expression.</P>
60      <H4>Marked sub-expressions:</H4>
61      <P>A section beginning \( and ending \) acts as a marked sub-expression.&nbsp; 
62         Whatever matched the sub-expression is split out in a separate field by the
63         matching algorithms.&nbsp; Marked sub-expressions can also repeated, or
64         referred-to by a back-reference.</P>
65      <H4>Repeats:</H4>
66      <P>Any atom (a single character, a marked sub-expression, or a character class)
67         can be repeated with the * operator.</P>
68      <P>For example a* will match any number of letter a's repeated zero or more times
69         (an atom repeated zero times matches an empty string), so the expression a*b
70         will match any of the following:</P>
71      <PRE>b
72ab
73aaaaaaaab</PRE>
74      <P>An atom can also be repeated with a bounded repeat:</P>
75      <P>a\{n\}&nbsp; Matches 'a' repeated exactly <EM>n</EM> times.</P>
76      <P>a\{n,\}&nbsp; Matches 'a' repeated <EM>n</EM> or more times.</P>
77      <P>a\{n, m\}&nbsp; Matches 'a' repeated between <EM>n</EM> and <EM>m</EM> times
78         inclusive.</P>
79      <P>For example:</P>
80      <PRE>^a\{2,3\}$</PRE>
81      <P>Will match either of:</P>
82      <PRE>aa
83aaa</PRE>
84      <P>But neither of:</P>
85      <PRE>a
86aaaa</PRE>
87      <P>It is an error to use a repeat operator, if the preceding construct can not be
88         repeated, for example:</P>
89      <PRE>a\(*\)</PRE>
90      <P>Will raise an error, as there is nothing for the * operator to be applied to.</P>
91      <H4>Back references:</H4>
92      <P>An escape character followed by a digit <EM>n</EM>, where <EM>n </EM>is in the
93         range 1-9, matches the same string that was matched by sub-expression <EM>n</EM>.&nbsp; 
94         For example the expression:</P>
95      <PRE>^\(a*\).*\1$</PRE>
96      <P>Will match the string:</P>
97      <PRE>aaabbaaa</PRE>
98      <P>But not the string:</P>
99      <PRE>aaabba</PRE>
100      <H4>Character sets:</H4>
101      <P>A character set is a bracket-expression starting with [ and ending with ], it
102         defines a set of characters, and matches any single character that is a member
103         of that set.</P>
104      <P>A bracket expression may contain any combination of the following:</P>
105      <BLOCKQUOTE dir="ltr" style="MARGIN-RIGHT: 0px">
106         <H5>Single characters:</H5>
107         <P>For example [abc], will match any of the characters 'a', 'b', or 'c'.</P>
108         <H5>Character ranges:</H5>
109         <P>For example [a-c] will match any single character in the range 'a' to
110            'c'.&nbsp; By default, for POSIX-Basic regular expressions, a character <EM>x</EM>
111            is within the range <EM>y</EM> to <EM>z</EM>, if it collates within that
112            range;&nbsp;this results in locale specific behavior.&nbsp; This behavior can
113            be turned off by unsetting the <EM><A href="syntax_option_type.html#basic">collate</A></EM>
114            option flag - in which case whether a character appears within a range is
115            determined by comparing the code points of the characters only</P>
116         <H5>Negation:</H5>
117         <P>If the bracket-expression begins with the ^ character, then it matches the
118            complement of the characters it contains, for example [^a-c] matches any
119            character that is not in the range a-c.</P>
120         <H5>Character classes:</H5>
121         <P>An expression of the form [[:name:]] matches the named character class "name",
122            for example [[:lower:]] matches any lower case character.&nbsp; See <A href="character_class_names.html">
123               character class names</A>.</P>
124         <H5>Collating Elements:</H5>
125         <P>An expression of the form [[.col.] matches the collating element <EM>col</EM>.&nbsp; 
126            A collating element is any single character, or any sequence of characters that
127            collates as a single unit.&nbsp; Collating elements may also be used as the end
128            point of a range, for example: [[.ae.]-c] matches the character sequence "ae",
129            plus any single character in the rangle "ae"-c, assuming that "ae" is treated
130            as a single collating element in the current locale.</P>
131         <P>Collating elements may be used in place of escapes (which are not normally
132            allowed inside character sets), for example [[.^.]abc] would match either one
133            of the characters 'abc^'.</P>
134         <P>As an extension, a collating element may also be specified via its <A href="collating_names.html">
135               symbolic name</A>, for example:</P>
136         <P>[[.NUL.]]</P>
137         <P>matches a NUL character.</P>
138         <H5>Equivalence classes:</H5>
139         <P>
140            An expression of theform[[=col=]], matches any character or collating element
141            whose primary sort key is the same as that for collating element <EM>col</EM>,
142            as with collating elements the name <EM>col</EM> may be a <A href="collating_names.html">
143               symbolic name</A>.&nbsp; A primary sort key is one that ignores case,
144            accentation, or locale-specific tailorings; so for example [[=a=]] matches any
145            of the characters: a, à, á, â, ã, ä, å, A, À, Á, Â, Ã, Ä and Å.&nbsp; 
146            Unfortunately implementation of this is reliant on the platform's collation and
147            localisation support; this feature can not be relied upon to work portably
148            across all platforms, or even all locales on one platform.</P>
149      </BLOCKQUOTE>
150      <H5>Combinations:</H5>
151      <P>All of the above can be combined in one character set declaration, for example:
152         [[:digit:]a-c[.NUL.]].</P>
153      <H4>Escapes</H4>
154      <P>With the exception of the escape sequences \{, \}, \(, and \), which are
155         documented above, an escape followed by any character matches that
156         character.&nbsp; This can be used to make the special characters .[\*^$,
157         "ordinary".&nbsp; Note that the escape character loses its special meaning
158         inside a character set, so [\^] will match either a literal '\' or a '^'.</P>
159      <H4>What Gets Matched</H4>
160      <P>When there is more that one way to match a regular expression, the "best"
161         possible match is obtained using the <A href="syntax_leftmost_longest.html">leftmost-longest
162            rule</A>.</P>
163      <H3><A name="variations"></A>Variations</H3>
164      <H4><A name="grep"></A>Grep</H4>
165      <P>When an expression is compiled with the flag <EM>grep</EM> set, then the
166         expression is treated as a newline separated list of <A href="#Basic">POSIX-Basic</A>
167         expressions, a match is found if any of the expressions in the list match, for
168         example:</P>
169      <PRE>boost::regex e("abc\ndef", boost::regex::grep);</PRE>
170      <P>will match either of the POSIX-Basic expressions "abc" or "def".</P>
171      <P>As its name suggests, this behavior is consistent with the Unix utility <EM>grep</EM>.</P>
172      <H4><A name="emacs"></A>emacs</H4>
173      <P>In addition to the <A href="#Basic">POSIX-Basic features</A> the following
174         characters are also special:</P>
175      <BLOCKQUOTE dir="ltr" style="MARGIN-RIGHT: 0px">
176         <P>+ repeats the preceding atom one or more times.</P>
177         <P>? repeats the preceding atom zero or one times.</P>
178         <P>*? A non-greedy version of *.</P>
179         <P>+? A non-greedy version of +.</P>
180         <P>?? A non-greedy version of ?.</P>
181      </BLOCKQUOTE>
182      <P>And the following escape sequences are also recognised:</P>
183      <BLOCKQUOTE dir="ltr" style="MARGIN-RIGHT: 0px">
184         <P>\| specifies an alternative.</P>
185         <P>\(?:&nbsp; ...&nbsp; \) is a non-marking grouping construct - allows you to
186            lexically group something without spitting out an extra sub-expression.</P>
187         <P>\w&nbsp; matches any word character.</P>
188         <P>\W matches any non-word character.</P>
189         <P>\sx matches any character in the syntax group <EM>x</EM>, the following emacs
190            groupings are supported: 's', ' ', '_', 'w', '.', ')', '(', '"', '\'', '&gt;'
191            and '&lt;'.&nbsp; Refer to the emacs docs for details.</P>
192         <P>\Sx matches any character not in the syntax grouping <EM>x</EM>.</P>
193         <P>\c and \C are not supported.</P>
194         <P>\` matches zero characters only at the start of a buffer (or string being
195            matched).</P>
196         <P>\' matches zero characters only at the end of a buffer (or string being
197            matched).</P>
198         <P>\b matches zero characters at a word boundary.</P>
199         <P>\B matches zero characters, not at a word boundary.</P>
200         <P>\&lt; matches zero characters only at the start of a word.</P>
201         <P>\&gt; matches zero characters only at the end of a word.</P>
202      </BLOCKQUOTE>
203      <P dir="ltr">Finally, you should note that emacs style regular expressions are
204         matched according to the <A href="syntax_perl.html#what">Perl "depth first search"
205            rules</A>.&nbsp; Emacs expressions are matched this way because they contain
206         Perl-like extensions, that do not interact well with the <A href="syntax_leftmost_longest.html">
207            POSIX-style leftmost-longest rule</A>.</P>
208      <H3><A name="options"></A>Options</H3>
209      <P>There are a <A href="syntax_option_type.html#basic">variety of flags</A> that
210         may be combined with the <EM>basic</EM> and <EM>grep</EM> options when
211         constructing the regular expression, in particular note that the <A href="syntax_option_type.html#basic">
212            newline_alt, no_char_classes, no-intervals, bk_plus_qm and bk_plus_vbar</A> options
213         all alter the syntax, while the <A href="syntax_option_type.html#basic">collate
214            and icase</A> options modify how the case and locale sensitivity are to be
215         applied.</P>
216      <H3><A name="refs"></A>References</H3>
217      <P><A href="http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap09.html">IEEE
218            Std 1003.1-2001, Portable Operating System Interface (POSIX ), Base Definitions
219            and Headers, Section 9, Regular Expressions (FWD.1).</A></P>
220      <P><A href="http://www.opengroup.org/onlinepubs/000095399/utilities/grep.html">IEEE
221            Std 1003.1-2001, Portable Operating System Interface (POSIX ), Shells and
222            Utilities, Section 4, Utilities, grep (FWD.1).</A></P>
223      <P><A href="http://www.gnu.org/software/emacs/">Emacs Version 21.3</A>.</P>
224      <P>
225         <HR>
226      <P></P>
227      <p>Revised&nbsp; 
228         <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> 
229         21 Aug 2004&nbsp; 
230         <!--webbot bot="Timestamp" endspan i-checksum="39359" --></p>
231      <P><I>© Copyright <a href="mailto:jm@regex.fsnet.co.uk">John Maddock</a>&nbsp;2004</I></P>
232      <I>
233         <P><I>Use, modification and distribution are subject to the Boost Software License,
234               Version 1.0. (See accompanying file <A href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</A>
235               or copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>).</I></P>
236      </I>
237   </body>
238</html>
Note: See TracBrowser for help on using the repository browser.