/[pcre]/code/trunk/doc/html/pcrecpp.html

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

Parent Directory | Revision Log | View Patch Patch

-revision 80 by nigel,
Sat Feb 24 21:40:45 2007 UTC
+revision 81 by nigel,
Sat Feb 24 21:40:59 2007 UTC
 Line 18 
 man page, in case the conversion went wr
  <li><a name="TOC3" href="#SEC3">MATCHING INTERFACE</a>
  <li><a name="TOC4" href="#SEC4">PARTIAL MATCHES</a>
  <li><a name="TOC5" href="#SEC5">UTF-8 AND THE MATCHING INTERFACE</a>
- <li><a name="TOC6" href="#SEC6">SCANNING TEXT INCREMENTALLY</a>
+ <li><a name="TOC6" href="#SEC6">PASSING MODIFIERS TO THE REGULAR EXPRESSION ENGINE</a>
- <li><a name="TOC7" href="#SEC7">PARSING HEX/OCTAL/C-RADIX NUMBERS</a>
+ <li><a name="TOC7" href="#SEC7">SCANNING TEXT INCREMENTALLY</a>
- <li><a name="TOC8" href="#SEC8">REPLACING PARTS OF STRINGS</a>
+ <li><a name="TOC8" href="#SEC8">PARSING HEX/OCTAL/C-RADIX NUMBERS</a>
- <li><a name="TOC9" href="#SEC9">AUTHOR</a>
+ <li><a name="TOC9" href="#SEC9">REPLACING PARTS OF STRINGS</a>
+ <li><a name="TOC10" href="#SEC10">AUTHOR</a>
  </ul>
  <br><a name="SEC1" href="#TOC1">SYNOPSIS OF C++ WRAPPER</a><br>
  <P>
-Line 31 
 man page, in case the conversion went wr
+Line 32 
 man page, in case the conversion went wr
  </P>
  <br><a name="SEC2" href="#TOC1">DESCRIPTION</a><br>
  <P>
- 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
- constructed from the notes in the <i>pcrecpp.h</i> file, which should be
+ functionality was added by Giuseppe Maxia. This brief man page was constructed
- consulted for further details.
+ from the notes in the <i>pcrecpp.h</i> file, which should be consulted for
+ further details.
  </P>
  <br><a name="SEC3" href="#TOC1">MATCHING INTERFACE</a><br>
  <P>
-Line 148 
 NOTE: The UTF8 flag is ignored if pcre w
+Line 150 
 NOTE: The UTF8 flag is ignored if pcre w
        --enable-utf8 flag.
  </PRE>
  </P>
- <br><a name="SEC6" href="#TOC1">SCANNING TEXT INCREMENTALLY</a><br>
+ <br><a name="SEC6" href="#TOC1">PASSING MODIFIERS TO THE REGULAR EXPRESSION ENGINE</a><br>
+ <P>
+ PCRE defines some modifiers to change the behavior of the regular expression
+ engine. The C++ wrapper defines an auxiliary class, RE_Options, as a vehicle to
+ pass such modifiers to a RE class. Currently, the following modifiers are
+ supported:
+ <pre>
+    modifier              description               Perl corresponding
+    PCRE_CASELESS         case insensitive match      /i
+    PCRE_MULTILINE        multiple lines match        /m
+    PCRE_DOTALL           dot matches newlines        /s
+    PCRE_DOLLAR_ENDONLY   $ matches only at end       N/A
+    PCRE_EXTRA            strict escape parsing       N/A
+    PCRE_EXTENDED         ignore whitespaces          /x
+    PCRE_UTF8             handles UTF8 chars          built-in
+    PCRE_UNGREEDY         reverses * and *?           N/A
+    PCRE_NO_AUTO_CAPTURE  disables capturing parens   N/A (*)
+ </pre>
+ (*) Both Perl and PCRE allow non capturing parentheses by means of the
+ "?:" modifier within the pattern itself. e.g. (?:ab|cd) does not
+ capture, while (ab|cd) does.
+ </P>
+ <P>
+ For a full account on how each modifier works, please check the
+ PCRE API reference page.
+ </P>
+ <P>
+ For each modifier, there are two member functions whose name is made
+ out of the modifier in lowercase, without the "PCRE_" prefix. For
+ instance, PCRE_CASELESS is handled by
+ <pre>
+   bool caseless()
+ </pre>
+ which returns true if the modifier is set, and
+ <pre>
+   RE_Options & set_caseless(bool)
+ </pre>
+ which sets or unsets the modifier. Moreover, PCRE_CONFIG_MATCH_LIMIT can be
+ accessed through the <b>set_match_limit()</b> and <b>match_limit()</b> member
+ functions. Setting <i>match_limit</i> to a non-zero value will limit the
+ execution of pcre to keep it from doing bad things like blowing the stack or
+ taking an eternity to return a result. A value of 5000 is good enough to stop
+ stack blowup in a 2MB thread stack. Setting <i>match_limit</i> to zero disables
+ match limiting.
+ </P>
+ <P>
+ Normally, to pass one or more modifiers to a RE class, you declare
+ a <i>RE_Options</i> object, set the appropriate options, and pass this
+ object to a RE constructor. Example:
+ <pre>
+    RE_options opt;
+    opt.set_caseless(true);
+    if (RE("HELLO", opt).PartialMatch("hello world")) ...
+ </pre>
+ RE_options has two constructors. The default constructor takes no arguments and
+ creates a set of flags that are off by default. The optional parameter
+ <i>option_flags</i> is to facilitate transfer of legacy code from C programs.
+ This lets you do
+ <pre>
+    RE(pattern,
+      RE_Options(PCRE_CASELESS|PCRE_MULTILINE)).PartialMatch(str);
+ </pre>
+ However, new code is better off doing
+ <pre>
+    RE(pattern,
+      RE_Options().set_caseless(true).set_multiline(true))
+        .PartialMatch(str);
+ </pre>
+ If you are going to pass one of the most used modifiers, there are some
+ convenience functions that return a RE_Options class with the
+ appropriate modifier already set: <b>CASELESS()</b>, <b>UTF8()</b>,
+ <b>MULTILINE()</b>, <b>DOTALL</b>(), and <b>EXTENDED()</b>.
+ </P>
+ <P>
+ If you need to set several options at once, and you don't want to go through
+ the pains of declaring a RE_Options object and setting several options, there
+ is a parallel method that give you such ability on the fly. You can concatenate
+ several <b>set_xxxxx()</b> member functions, since each of them returns a
+ reference to its class object. For example, to pass PCRE_CASELESS,
+ PCRE_EXTENDED, and PCRE_MULTILINE to a RE with one statement, you may write:
+ <pre>
+    RE(" ^ xyz \\s+ .* blah$",
+      RE_Options()
+        .set_caseless(true)
+        .set_extended(true)
+        .set_multiline(true)).PartialMatch(sometext);
+ </PRE>
+ </P>
+ <br><a name="SEC7" href="#TOC1">SCANNING TEXT INCREMENTALLY</a><br>
  <P>
  The "Consume" operation may be useful if you want to repeatedly
  match regular expressions at the front of a string and skip over
-Line 181 
 could extract all words from a string by
+Line 273 
 could extract all words from a string by
    pcrecpp::RE("(\\w+)").FindAndConsume(&input, &word)
  </PRE>
  </P>
- <br><a name="SEC7" href="#TOC1">PARSING HEX/OCTAL/C-RADIX NUMBERS</a><br>
+ <br><a name="SEC8" href="#TOC1">PARSING HEX/OCTAL/C-RADIX NUMBERS</a><br>
  <P>
  By default, if you pass a pointer to a numeric value, the
  corresponding text is interpreted as a base-10 number. You can
-Line 199 
 prefixes, but defaults to base-10.
+Line 291 
 prefixes, but defaults to base-10.
  </pre>
  will leave 64 in a, b, c, and d.
  </P>
- <br><a name="SEC8" href="#TOC1">REPLACING PARTS OF STRINGS</a><br>
+ <br><a name="SEC9" href="#TOC1">REPLACING PARTS OF STRINGS</a><br>
  <P>
  You can replace the first match of "pattern" in "str" with "rewrite".
  Within "rewrite", backslash-escaped digits (\1 to \9) can be
-Line 231 
 The non-matching portions of "text" are
+Line 323 
 The non-matching portions of "text" are
  occurred and the extraction happened successfully;  if no match occurs, the
  string is left unaffected.
  </P>
- <br><a name="SEC9" href="#TOC1">AUTHOR</a><br>
+ <br><a name="SEC10" href="#TOC1">AUTHOR</a><br>
  <P>
  The C++ wrapper was contributed by Google Inc.
  <br>

 Legend:



Removed from v.80
 


changed lines


 
Added in v.81
 Legend:



Removed from v.80
 


changed lines


 
Added in v.81
-Removed from v.80
+Added in v.81

	ViewVC Help
Powered by ViewVC 1.1.5