/[pcre]/code/trunk/doc/pcrecpp.3
ViewVC logotype

Diff of /code/trunk/doc/pcrecpp.3

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 79 by nigel, Sat Feb 24 21:40:52 2007 UTC revision 99 by ph10, Tue Mar 6 12:27:42 2007 UTC
# Line 5  PCRE - Perl-compatible regular expressio Line 5  PCRE - Perl-compatible regular expressio
5  .rs  .rs
6  .sp  .sp
7  .B #include <pcrecpp.h>  .B #include <pcrecpp.h>
8  .PP  .
 .SM  
 .br  
9  .SH DESCRIPTION  .SH DESCRIPTION
10  .rs  .rs
11  .sp  .sp
12  The C++ wrapper for PCRE was provided by Google Inc. This brief man page was  The C++ wrapper for PCRE was provided by Google Inc. Some additional
13  constructed from the notes in the \fIpcrecpp.h\fP file, which should be  functionality was added by Giuseppe Maxia. This brief man page was constructed
14  consulted for further details.  from the notes in the \fIpcrecpp.h\fP file, which should be consulted for
15    further details.
16  .  .
17  .  .
18  .SH "MATCHING INTERFACE"  .SH "MATCHING INTERFACE"
# Line 84  The function returns true iff all of the Line 83  The function returns true iff all of the
83       number of sub-patterns, "i"th captured sub-pattern is       number of sub-patterns, "i"th captured sub-pattern is
84       ignored.       ignored.
85  .sp  .sp
86    CAVEAT: An optional sub-pattern that does not exist in the matched
87    string is assigned the empty string. Therefore, the following will
88    return false (because the empty string is not a valid number):
89    .sp
90       int number;
91       pcrecpp::RE::FullMatch("abc", "[a-z]+(\\d+)?", &number);
92    .sp
93  The matching interface supports at most 16 arguments per call.  The matching interface supports at most 16 arguments per call.
94  If you need more, consider using the more general interface  If you need more, consider using the more general interface
95  \fBpcrecpp::RE::DoMatch\fP. See \fBpcrecpp.h\fP for the signature for  \fBpcrecpp::RE::DoMatch\fP. See \fBpcrecpp.h\fP for the signature for
96  \fBDoMatch\fP.  \fBDoMatch\fP.
97  .  .
98    .SH "QUOTING METACHARACTERS"
99    .rs
100    .sp
101    You can use the "QuoteMeta" operation to insert backslashes before all
102    potentially meaningful characters in a string. The returned string, used as a
103    regular expression, will exactly match the original string.
104    .sp
105      Example:
106         string quoted = RE::QuoteMeta(unquoted);
107    .sp
108    Note that it's legal to escape a character even if it has no special meaning in
109    a regular expression -- so this function does that. (This also makes it
110    identical to the perl function of the same name; see "perldoc -f quotemeta".)
111    For example, "1.5-2.0?" becomes "1\e.5\e-2\e.0\e?".
112    .
113  .SH "PARTIAL MATCHES"  .SH "PARTIAL MATCHES"
114  .rs  .rs
115  .sp  .sp
# Line 130  NOTE: The UTF8 flag is ignored if pcre w Line 151  NOTE: The UTF8 flag is ignored if pcre w
151        --enable-utf8 flag.        --enable-utf8 flag.
152  .  .
153  .  .
154    .SH "PASSING MODIFIERS TO THE REGULAR EXPRESSION ENGINE"
155    .rs
156    .sp
157    PCRE defines some modifiers to change the behavior of the regular expression
158    engine. The C++ wrapper defines an auxiliary class, RE_Options, as a vehicle to
159    pass such modifiers to a RE class. Currently, the following modifiers are
160    supported:
161    .sp
162       modifier              description               Perl corresponding
163    .sp
164       PCRE_CASELESS         case insensitive match      /i
165       PCRE_MULTILINE        multiple lines match        /m
166       PCRE_DOTALL           dot matches newlines        /s
167       PCRE_DOLLAR_ENDONLY   $ matches only at end       N/A
168       PCRE_EXTRA            strict escape parsing       N/A
169       PCRE_EXTENDED         ignore whitespaces          /x
170       PCRE_UTF8             handles UTF8 chars          built-in
171       PCRE_UNGREEDY         reverses * and *?           N/A
172       PCRE_NO_AUTO_CAPTURE  disables capturing parens   N/A (*)
173    .sp
174    (*) Both Perl and PCRE allow non capturing parentheses by means of the
175    "?:" modifier within the pattern itself. e.g. (?:ab|cd) does not
176    capture, while (ab|cd) does.
177    .P
178    For a full account on how each modifier works, please check the
179    PCRE API reference page.
180    .P
181    For each modifier, there are two member functions whose name is made
182    out of the modifier in lowercase, without the "PCRE_" prefix. For
183    instance, PCRE_CASELESS is handled by
184    .sp
185      bool caseless()
186    .sp
187    which returns true if the modifier is set, and
188    .sp
189      RE_Options & set_caseless(bool)
190    .sp
191    which sets or unsets the modifier. Moreover, PCRE_EXTRA_MATCH_LIMIT can be
192    accessed through the \fBset_match_limit()\fR and \fBmatch_limit()\fR member
193    functions. Setting \fImatch_limit\fR to a non-zero value will limit the
194    execution of pcre to keep it from doing bad things like blowing the stack or
195    taking an eternity to return a result. A value of 5000 is good enough to stop
196    stack blowup in a 2MB thread stack. Setting \fImatch_limit\fR to zero disables
197    match limiting. Alternatively, you can call \fBmatch_limit_recursion()\fP
198    which uses PCRE_EXTRA_MATCH_LIMIT_RECURSION to limit how much PCRE
199    recurses. \fBmatch_limit()\fP limits the number of matches PCRE does;
200    \fBmatch_limit_recursion()\fP limits the depth of internal recursion, and
201    therefore the amount of stack that is used.
202    .P
203    Normally, to pass one or more modifiers to a RE class, you declare
204    a \fIRE_Options\fR object, set the appropriate options, and pass this
205    object to a RE constructor. Example:
206    .sp
207       RE_options opt;
208       opt.set_caseless(true);
209       if (RE("HELLO", opt).PartialMatch("hello world")) ...
210    .sp
211    RE_options has two constructors. The default constructor takes no arguments and
212    creates a set of flags that are off by default. The optional parameter
213    \fIoption_flags\fR is to facilitate transfer of legacy code from C programs.
214    This lets you do
215    .sp
216       RE(pattern,
217         RE_Options(PCRE_CASELESS|PCRE_MULTILINE)).PartialMatch(str);
218    .sp
219    However, new code is better off doing
220    .sp
221       RE(pattern,
222         RE_Options().set_caseless(true).set_multiline(true))
223           .PartialMatch(str);
224    .sp
225    If you are going to pass one of the most used modifiers, there are some
226    convenience functions that return a RE_Options class with the
227    appropriate modifier already set: \fBCASELESS()\fR, \fBUTF8()\fR,
228    \fBMULTILINE()\fR, \fBDOTALL\fR(), and \fBEXTENDED()\fR.
229    .P
230    If you need to set several options at once, and you don't want to go through
231    the pains of declaring a RE_Options object and setting several options, there
232    is a parallel method that give you such ability on the fly. You can concatenate
233    several \fBset_xxxxx()\fR member functions, since each of them returns a
234    reference to its class object. For example, to pass PCRE_CASELESS,
235    PCRE_EXTENDED, and PCRE_MULTILINE to a RE with one statement, you may write:
236    .sp
237       RE(" ^ xyz \e\es+ .* blah$",
238         RE_Options()
239           .set_caseless(true)
240           .set_extended(true)
241           .set_multiline(true)).PartialMatch(sometext);
242    .sp
243    .
244    .
245  .SH "SCANNING TEXT INCREMENTALLY"  .SH "SCANNING TEXT INCREMENTALLY"
246  .rs  .rs
247  .sp  .sp
# Line 215  string is left unaffected. Line 327  string is left unaffected.
327  .SH AUTHOR  .SH AUTHOR
328  .rs  .rs
329  .sp  .sp
330    .nf
331  The C++ wrapper was contributed by Google Inc.  The C++ wrapper was contributed by Google Inc.
332  .br  Copyright (c) 2006 Google Inc.
333  Copyright (c) 2005 Google Inc.  .fi
334    .
335    .
336    .SH REVISION
337    .rs
338    .sp
339    .nf
340    Last updated: 06 March 2007
341    .fi

Legend:
Removed from v.79  
changed lines
  Added in v.99

  ViewVC Help
Powered by ViewVC 1.1.5