400 lines
20 KiB
HTML
400 lines
20 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of PCRECPP</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>PCRECPP</H1>
|
|
Section: C Library Functions (3)<BR>Updated: 08 January 2012<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
PCRE - Perl-compatible regular expressions.
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS OF C++ WRAPPER</H2>
|
|
|
|
|
|
<P>
|
|
<B>#include <<A HREF="file:///usr/include/pcrecpp.h">pcrecpp.h</A>></B>
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
|
|
<P>
|
|
The C++ wrapper for PCRE was provided by Google Inc. Some additional
|
|
functionality was added by Giuseppe Maxia. This brief man page was constructed
|
|
from the notes in the <I>pcrecpp.h</I> file, which should be consulted for
|
|
further details. Note that the C++ wrapper supports only the original 8-bit
|
|
PCRE library. There is no 16-bit or 32-bit support at present.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>MATCHING INTERFACE</H2>
|
|
|
|
|
|
<P>
|
|
The "FullMatch" operation checks that supplied text matches a supplied pattern
|
|
exactly. If pointer arguments are supplied, it copies matched sub-strings that
|
|
match sub-patterns into them.
|
|
<P>
|
|
<BR> Example: successful match
|
|
<BR> pcrecpp::RE re("h.*o");
|
|
<BR> re.FullMatch("hello");
|
|
<P>
|
|
<BR> Example: unsuccessful match (requires full match):
|
|
<BR> pcrecpp::RE re("e");
|
|
<BR> !re.FullMatch("hello");
|
|
<P>
|
|
<BR> Example: creating a temporary RE object:
|
|
<BR> pcrecpp::RE("h.*o").FullMatch("hello");
|
|
<P>
|
|
You can pass in a "const char*" or a "string" for "text". The examples below
|
|
tend to use a const char*. You can, as in the different examples above, store
|
|
the RE object explicitly in a variable or use a temporary RE object. The
|
|
examples below use one mode or the other arbitrarily. Either could correctly be
|
|
used for any of these examples.
|
|
<P>
|
|
|
|
You must supply extra pointer arguments to extract matched subpieces.
|
|
<P>
|
|
<BR> Example: extracts "ruby" into "s" and 1234 into "i"
|
|
<BR> int i;
|
|
<BR> string s;
|
|
<BR> pcrecpp::RE re("(\\w+):(\\d+)");
|
|
<BR> re.FullMatch("ruby:1234", &s, &i);
|
|
<P>
|
|
<BR> Example: does not try to extract any extra sub-patterns
|
|
<BR> re.FullMatch("ruby:1234", &s);
|
|
<P>
|
|
<BR> Example: does not try to extract into NULL
|
|
<BR> re.FullMatch("ruby:1234", NULL, &i);
|
|
<P>
|
|
<BR> Example: integer overflow causes failure
|
|
<BR> !re.FullMatch("ruby:1234567891234", NULL, &i);
|
|
<P>
|
|
<BR> Example: fails because there aren't enough sub-patterns:
|
|
<BR> !pcrecpp::RE("\\w+:\\d+").FullMatch("ruby:1234", &s);
|
|
<P>
|
|
<BR> Example: fails because string cannot be stored in integer
|
|
<BR> !pcrecpp::RE("(.*)").FullMatch("ruby", &i);
|
|
<P>
|
|
The provided pointer arguments can be pointers to any scalar numeric
|
|
type, or one of:
|
|
<P>
|
|
<BR> string (matched piece is copied to string)
|
|
<BR> StringPiece (StringPiece is mutated to point to matched piece)
|
|
<BR> T (where "bool T::ParseFrom(const char*, int)" exists)
|
|
<BR> NULL (the corresponding matched sub-pattern is not copied)
|
|
<P>
|
|
The function returns true iff all of the following conditions are satisfied:
|
|
<P>
|
|
<BR> a. "text" matches "pattern" exactly;
|
|
<P>
|
|
<BR> b. The number of matched sub-patterns is >= number of supplied
|
|
<BR> pointers;
|
|
<P>
|
|
<BR> c. The "i"th argument has a suitable type for holding the
|
|
<BR> string captured as the "i"th sub-pattern. If you pass in
|
|
<BR> void * NULL for the "i"th argument, or a non-void * NULL
|
|
<BR> of the correct type, or pass fewer arguments than the
|
|
<BR> number of sub-patterns, "i"th captured sub-pattern is
|
|
<BR> ignored.
|
|
<P>
|
|
CAVEAT: An optional sub-pattern that does not exist in the matched
|
|
string is assigned the empty string. Therefore, the following will
|
|
return false (because the empty string is not a valid number):
|
|
<P>
|
|
<BR> int number;
|
|
<BR> pcrecpp::RE::FullMatch("abc", "[a-z]+(\\d+)?", &number);
|
|
<P>
|
|
The matching interface supports at most 16 arguments per call.
|
|
If you need more, consider using the more general interface
|
|
<B>pcrecpp::RE::DoMatch</B>. See <B>pcrecpp.h</B> for the signature for
|
|
<B>DoMatch</B>.
|
|
<P>
|
|
|
|
NOTE: Do not use <B>no_arg</B>, which is used internally to mark the end of a
|
|
list of optional arguments, as a placeholder for missing arguments, as this can
|
|
lead to segfaults.
|
|
<A NAME="lbAF"> </A>
|
|
<H2>QUOTING METACHARACTERS</H2>
|
|
|
|
|
|
<P>
|
|
You can use the "QuoteMeta" operation to insert backslashes before all
|
|
potentially meaningful characters in a string. The returned string, used as a
|
|
regular expression, will exactly match the original string.
|
|
<P>
|
|
<BR> Example:
|
|
<BR> string quoted = RE::QuoteMeta(unquoted);
|
|
<P>
|
|
Note that it's legal to escape a character even if it has no special meaning in
|
|
a regular expression -- so this function does that. (This also makes it
|
|
identical to the perl function of the same name; see "perldoc -f quotemeta".)
|
|
For example, "1.5-2.0?" becomes "1\.5\-2\.0\?".
|
|
<A NAME="lbAG"> </A>
|
|
<H2>PARTIAL MATCHES</H2>
|
|
|
|
|
|
<P>
|
|
You can use the "PartialMatch" operation when you want the pattern
|
|
to match any substring of the text.
|
|
<P>
|
|
<BR> Example: simple search for a string:
|
|
<BR> pcrecpp::RE("ell").PartialMatch("hello");
|
|
<P>
|
|
<BR> Example: find first number in a string:
|
|
<BR> int number;
|
|
<BR> pcrecpp::RE re("(\\d+)");
|
|
<BR> re.PartialMatch("x*100 + 20", &number);
|
|
<BR> assert(number == 100);
|
|
<A NAME="lbAH"> </A>
|
|
<H2>UTF-8 AND THE MATCHING INTERFACE</H2>
|
|
|
|
|
|
<P>
|
|
By default, pattern and text are plain text, one byte per character. The UTF8
|
|
flag, passed to the constructor, causes both pattern and string to be treated
|
|
as UTF-8 text, still a byte stream but potentially multiple bytes per
|
|
character. In practice, the text is likelier to be UTF-8 than the pattern, but
|
|
the match returned may depend on the UTF8 flag, so always use it when matching
|
|
UTF8 text. For example, "." will match one byte normally but with UTF8 set may
|
|
match up to three bytes of a multi-byte character.
|
|
<P>
|
|
<BR> Example:
|
|
<BR> pcrecpp::RE_Options options;
|
|
<BR> options.set_utf8();
|
|
<BR> pcrecpp::RE re(utf8_pattern, options);
|
|
<BR> re.FullMatch(utf8_string);
|
|
<P>
|
|
<BR> Example: using the convenience function UTF8():
|
|
<BR> pcrecpp::RE re(utf8_pattern, pcrecpp::UTF8());
|
|
<BR> re.FullMatch(utf8_string);
|
|
<P>
|
|
NOTE: The UTF8 flag is ignored if pcre was not configured with the
|
|
<BR> --enable-utf8 flag.
|
|
<A NAME="lbAI"> </A>
|
|
<H2>PASSING MODIFIERS TO THE REGULAR EXPRESSION ENGINE</H2>
|
|
|
|
|
|
<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:
|
|
<P>
|
|
<BR> modifier description Perl corresponding
|
|
<P>
|
|
<BR> PCRE_CASELESS case insensitive match /i
|
|
<BR> PCRE_MULTILINE multiple lines match /m
|
|
<BR> PCRE_DOTALL dot matches newlines /s
|
|
<BR> PCRE_DOLLAR_ENDONLY $ matches only at end N/A
|
|
<BR> PCRE_EXTRA strict escape parsing N/A
|
|
<BR> PCRE_EXTENDED ignore white spaces /x
|
|
<BR> PCRE_UTF8 handles UTF8 chars built-in
|
|
<BR> PCRE_UNGREEDY reverses * and *? N/A
|
|
<BR> PCRE_NO_AUTO_CAPTURE disables capturing parens N/A (*)
|
|
<P>
|
|
(*) 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>
|
|
|
|
For a full account on how each modifier works, please check the
|
|
PCRE API reference page.
|
|
<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
|
|
<P>
|
|
<BR> bool caseless()
|
|
<P>
|
|
which returns true if the modifier is set, and
|
|
<P>
|
|
<BR> RE_Options & set_caseless(bool)
|
|
<P>
|
|
which sets or unsets the modifier. Moreover, PCRE_EXTRA_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. Alternatively, you can call <B>match_limit_recursion()</B>
|
|
which uses PCRE_EXTRA_MATCH_LIMIT_RECURSION to limit how much PCRE
|
|
recurses. <B>match_limit()</B> limits the number of matches PCRE does;
|
|
<B>match_limit_recursion()</B> limits the depth of internal recursion, and
|
|
therefore the amount of stack that is used.
|
|
<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:
|
|
<P>
|
|
<BR> RE_Options opt;
|
|
<BR> opt.set_caseless(true);
|
|
<BR> if (RE("HELLO", opt).PartialMatch("hello world")) ...
|
|
<P>
|
|
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
|
|
<P>
|
|
<BR> RE(pattern,
|
|
<BR> RE_Options(PCRE_CASELESS|PCRE_MULTILINE)).PartialMatch(str);
|
|
<P>
|
|
However, new code is better off doing
|
|
<P>
|
|
<BR> RE(pattern,
|
|
<BR> RE_Options().set_caseless(true).set_multiline(true))
|
|
<BR> .PartialMatch(str);
|
|
<P>
|
|
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>
|
|
|
|
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:
|
|
<P>
|
|
<BR> RE(" ^ xyz \\s+ .* blah$",
|
|
<BR> RE_Options()
|
|
<BR> .set_caseless(true)
|
|
<BR> .set_extended(true)
|
|
<BR> .set_multiline(true)).PartialMatch(sometext);
|
|
<P>
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>SCANNING TEXT INCREMENTALLY</H2>
|
|
|
|
|
|
<P>
|
|
The "Consume" operation may be useful if you want to repeatedly
|
|
match regular expressions at the front of a string and skip over
|
|
them as they match. This requires use of the "StringPiece" type,
|
|
which represents a sub-range of a real string. Like RE, StringPiece
|
|
is defined in the pcrecpp namespace.
|
|
<P>
|
|
<BR> Example: read lines of the form "var = value" from a string.
|
|
<BR> string contents = ...; // Fill string somehow
|
|
<BR> pcrecpp::StringPiece input(contents); // Wrap in a StringPiece
|
|
<P>
|
|
<BR> string var;
|
|
<BR> int value;
|
|
<BR> pcrecpp::RE re("(\\w+) = (\\d+)\n");
|
|
<BR> while (re.Consume(&input, &var, &value)) {
|
|
<BR> ...;
|
|
<BR> }
|
|
<P>
|
|
Each successful call to "Consume" will set "var/value", and also
|
|
advance "input" so it points past the matched text.
|
|
<P>
|
|
|
|
The "FindAndConsume" operation is similar to "Consume" but does not
|
|
anchor your match at the beginning of the string. For example, you
|
|
could extract all words from a string by repeatedly calling
|
|
<P>
|
|
<BR> pcrecpp::RE("(\\w+)").FindAndConsume(&input, &word)
|
|
<A NAME="lbAK"> </A>
|
|
<H2>PARSING HEX/OCTAL/C-RADIX NUMBERS</H2>
|
|
|
|
|
|
<P>
|
|
By default, if you pass a pointer to a numeric value, the
|
|
corresponding text is interpreted as a base-10 number. You can
|
|
instead wrap the pointer with a call to one of the operators Hex(),
|
|
Octal(), or CRadix() to interpret the text in another base. The
|
|
CRadix operator interprets C-style "0" (base-8) and "0x" (base-16)
|
|
prefixes, but defaults to base-10.
|
|
<P>
|
|
<BR> Example:
|
|
<BR> int a, b, c, d;
|
|
<BR> pcrecpp::RE re("(.*) (.*) (.*) (.*)");
|
|
<BR> re.FullMatch("100 40 0100 0x40",
|
|
<BR> pcrecpp::Octal(&a), pcrecpp::Hex(&b),
|
|
<BR> pcrecpp::CRadix(&c), pcrecpp::CRadix(&d));
|
|
<P>
|
|
will leave 64 in a, b, c, and d.
|
|
<A NAME="lbAL"> </A>
|
|
<H2>REPLACING PARTS OF STRINGS</H2>
|
|
|
|
|
|
<P>
|
|
You can replace the first match of "pattern" in "str" with "rewrite".
|
|
Within "rewrite", backslash-escaped digits (\1 to \9) can be
|
|
used to insert text matching corresponding parenthesized group
|
|
from the pattern. \0 in "rewrite" refers to the entire matching
|
|
text. For example:
|
|
<P>
|
|
<BR> string s = "yabba dabba doo";
|
|
<BR> pcrecpp::RE("b+").Replace("d", &s);
|
|
<P>
|
|
will leave "s" containing "yada dabba doo". The result is true if the pattern
|
|
matches and a replacement occurs, false otherwise.
|
|
<P>
|
|
|
|
<B>GlobalReplace</B> is like <B>Replace</B> except that it replaces all
|
|
occurrences of the pattern in the string with the rewrite. Replacements are
|
|
not subject to re-matching. For example:
|
|
<P>
|
|
<BR> string s = "yabba dabba doo";
|
|
<BR> pcrecpp::RE("b+").GlobalReplace("d", &s);
|
|
<P>
|
|
will leave "s" containing "yada dada doo". It returns the number of
|
|
replacements made.
|
|
<P>
|
|
|
|
<B>Extract</B> is like <B>Replace</B>, except that if the pattern matches,
|
|
"rewrite" is copied into "out" (an additional argument) with substitutions.
|
|
The non-matching portions of "text" are ignored. Returns true iff a match
|
|
occurred and the extraction happened successfully; if no match occurs, the
|
|
string is left unaffected.
|
|
<A NAME="lbAM"> </A>
|
|
<H2>AUTHOR</H2>
|
|
|
|
|
|
<P>
|
|
<PRE>
|
|
The C++ wrapper was contributed by Google Inc.
|
|
Copyright (c) 2007 Google Inc.
|
|
</PRE>
|
|
|
|
<A NAME="lbAN"> </A>
|
|
<H2>REVISION</H2>
|
|
|
|
|
|
<P>
|
|
<PRE>
|
|
Last updated: 08 January 2012
|
|
</PRE>
|
|
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="1"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="2"><A HREF="#lbAC">SYNOPSIS OF C++ WRAPPER</A><DD>
|
|
<DT id="3"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="4"><A HREF="#lbAE">MATCHING INTERFACE</A><DD>
|
|
<DT id="5"><A HREF="#lbAF">QUOTING METACHARACTERS</A><DD>
|
|
<DT id="6"><A HREF="#lbAG">PARTIAL MATCHES</A><DD>
|
|
<DT id="7"><A HREF="#lbAH">UTF-8 AND THE MATCHING INTERFACE</A><DD>
|
|
<DT id="8"><A HREF="#lbAI">PASSING MODIFIERS TO THE REGULAR EXPRESSION ENGINE</A><DD>
|
|
<DT id="9"><A HREF="#lbAJ">SCANNING TEXT INCREMENTALLY</A><DD>
|
|
<DT id="10"><A HREF="#lbAK">PARSING HEX/OCTAL/C-RADIX NUMBERS</A><DD>
|
|
<DT id="11"><A HREF="#lbAL">REPLACING PARTS OF STRINGS</A><DD>
|
|
<DT id="12"><A HREF="#lbAM">AUTHOR</A><DD>
|
|
<DT id="13"><A HREF="#lbAN">REVISION</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:51 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|