Introduction to Library Functions PCRECP(3)
NAME
PCRE - Perl-compatible regular expressions.
SYNOPSIS OF C] WRAPER
#include
DESCRIPTION
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
pcrecpp.h file, which should be consulted for further
details.
MATCHING INTERFACE
The "FullMatch" operation checks that supplied text matches
a supplied pattern exactly. If pointer arguments are sup-
plied, it copies matched sub-strings that match sub-patterns
into them.
Example: successful match
pcrecpp::RE re("h.*o");
re.FullMatch("hello");
Example: unsuccessful match (requires full match):
pcrecpp::RE re("e");
!re.FullMatch("hello");
Example: creating a temporary RE object:
pcrecpp::RE("h.*o").FullMatch("hello");
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.
You must supply extra pointer arguments to extract matched
subpieces.
Example: extracts "ruby" into "s" and 1234 into "i"
int i;
string s;
pcrecpp::RE re("(\\w]):(\\d])");
re.FullMatch("ruby:1234", &s, &i);
Example: does not try to extract any extra sub-patterns
re.FullMatch("ruby:1234", &s);
SunOS 5.10 Last change: 1
Introduction to Library Functions PCRECP(3)
Example: does not try to extract into NUL
re.FullMatch("ruby:1234", NUL, &i);
Example: integer overflow causes failure
!re.FullMatch("ruby:1234567891234", NUL, &i);
Example: fails because there aren't enough sub-patterns:
!pcrecpp::RE("\\w]:\\d]").FullMatch("ruby:1234", &s);
Example: fails because string cannot be stored in integer
!pcrecpp::RE("(.*)").FullMatch("ruby", &i);
The provided pointer arguments can be pointers to any scalar
numeric type, or one of:
string (matched piece is copied to string)
StringPiece (StringPiece is mutated to point to matched
piece)
T (where "bool T::ParseFrom(const char*,
int)" exists)
NUL (the corresponding matched sub-pattern is
not copied)
The function returns true iff all of the following condi-
tions are satisfied:
a. "text" matches "pattern" exactly;
b. The number of matched sub-patterns is >= number of sup-
plied
pointers;
c. The "i"th argument has a suitable type for holding the
string captured as the "i"th sub-pattern. If you pass
in
void * NUL for the "i"th argument, or a non-void *
NUL
of the correct type, or pass fewer arguments than the
number of sub-patterns, "i"th captured sub-pattern is
ignored.
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):
int number;
pcrecpp::RE::FullMatch("abc", "[a-z](\\d])?", &number);
The matching interface supports at most 16 arguments per
call. If you need more, consider using the more general
interface pcrecpp::RE::DoMatch. See pcrecpp.h for the
SunOS 5.10 Last change: 2
Introduction to Library Functions PCRECP(3)
signature for DoMatch.
QUOTING METACHARACTERS
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.
Example:
string quoted = RE::QuoteMeta(unquoted);
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 func-
tion of the same name; see "perldoc -f quotemeta".) For
example, "1.5-2.0?" becomes "1\.5\-2\.0\?".
PARTIAL MATCHES
You can use the "PartialMatch" operation when you want the
pattern to match any substring of the text.
Example: simple search for a string:
pcrecpp::RE("ell").PartialMatch("hello");
Example: find first number in a string:
int number;
pcrecpp::RE re("(\\d])");
re.PartialMatch("x*100 ] 20", &number);
assert(number == 100);
UTF-8 AND THE MATCHING INTERFACE
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.
Example:
pcrecpp::REOptions options;
options.setutf8();
pcrecpp::RE re(utf8pattern, options);
re.FullMatch(utf8string);
Example: using the convenience function UTF8():
pcrecpp::RE re(utf8pattern, pcrecpp::UTF8());
SunOS 5.10 Last change: 3
Introduction to Library Functions PCRECP(3)
re.FullMatch(utf8string);
NOTE: The UTF8 flag is ignored if pcre was not configured
with the
--enable-utf8 flag.
PASING MODIFIERS TO THE REGULAR EXPRESION ENGINE
PCRE defines some modifiers to change the behavior of the
regular expression engine. The C] wrapper defines an auxi-
liary class, REOptions, as a vehicle to pass such modifiers
to a RE class. Currently, the following modifiers are sup-
ported:
modifier description Perl
corresponding
PCRECASELES case insensitive match /i
PCREMULTILINE multiple lines match /m
PCREDOTAL dot matches newlines /s
PCREDOLARENDONLY $ matches only at end N/A
PCREXTRA strict escape parsing N/A
PCREXTENDED ignore whitespaces /x
PCREUTF8 handles UTF8 chars built-
in
PCREUNGREDY reverses * and *? N/A
PCRENOAUTOCAPTURE disables capturing parens N/A (*)
(*) Both Perl and PCRE allow non capturing parentheses by
means of the "?:" modifier within the pattern itself. e.g.
(?:abcd) does not capture, while (abcd) does.
For a full account on how each modifier works, please check
the PCRE API reference page.
For each modifier, there are two member functions whose name
is made out of the modifier in lowercase, without the
"PCRE" prefix. For instance, PCRECASELES is handled by
bool caseless()
which returns true if the modifier is set, and
REOptions & setcaseless(bool)
which sets or unsets the modifier. Moreover,
PCREXTRAMATCHLIMIT can be accessed through the
setmatchlimit() and matchlimit() member functions. Set-
ting matchlimit to a non-zero value will limit the execu-
tion 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
SunOS 5.10 Last change: 4
Introduction to Library Functions PCRECP(3)
stack. Setting matchlimit to zero disables match limiting.
Alternatively, you can call matchlimitrecursion() which
uses PCREXTRAMATCHLIMITRECURSION to limit how much PCRE
recurses. matchlimit() limits the number of matches PCRE
does; matchlimitrecursion() limits the depth of internal
recursion, and therefore the amount of stack that is used.
Normally, to pass one or more modifiers to a RE class, you
declare a REOptions object, set the appropriate options,
and pass this object to a RE constructor. Example:
REoptions opt;
opt.setcaseless(true);
if (RE("HELO", opt).PartialMatch("hello world")) ...
REoptions has two constructors. The default constructor
takes no arguments and creates a set of flags that are off
by default. The optional parameter optionflags is to facil-
itate transfer of legacy code from C programs. This lets
you do
RE(pattern,
REOptions(PCRECASELESPCREMULTILINE)).PartialMatch(str);
However, new code is better off doing
RE(pattern,
REOptions().setcaseless(true).setmultiline(true))
.PartialMatch(str);
If you are going to pass one of the most used modifiers,
there are some convenience functions that return a
REOptions class with the appropriate modifier already set:
CASELES(), UTF8(), MULTILINE(), DOTAL(), and EXTENDED().
If you need to set several options at once, and you don't
want to go through the pains of declaring a REOptions
object and setting several options, there is a parallel
method that give you such ability on the fly. You can con-
catenate several setxxxxx() member functions, since each of
them returns a reference to its class object. For example,
to pass PCRECASELES, PCREXTENDED, and PCREMULTILINE to
a RE with one statement, you may write:
RE(" ^ xyz \\s] .* blah$",
REOptions()
.setcaseless(true)
.setextended(true)
.setmultiline(true)).PartialMatch(sometext);
SunOS 5.10 Last change: 5
Introduction to Library Functions PCRECP(3)
SCANING TEXT INCREMENTALY
The "Consume" operation may be useful if you want to repeat-
edly 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.
Example: read lines of the form "var = value" from a
string.
string contents = ...; / Fill string
somehow
pcrecpp::StringPiece input(contents); / Wrap in a
StringPiece
string var;
int value;
pcrecpp::RE re("(\\w]) = (\\d])\n");
while (re.Consume(&input, &var, &value)) {
...;
}
Each successful call to "Consume" will set "var/value", and
also advance "input" so it points past the matched text.
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
pcrecpp::RE("(\\w])").FindAndConsume(&input, &word)
PARSING HEX/OCTAL/C-RADIX NUMBERS
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.
Example:
int a, b, c, d;
pcrecpp::RE re("(.*) (.*) (.*) (.*)");
re.FullMatch("100 40 0100 0x40",
pcrecpp::Octal(&a), pcrecpp::Hex(&b),
pcrecpp::CRadix(&c), pcrecpp::CRadix(&d));
will leave 64 in a, b, c, and d.
SunOS 5.10 Last change: 6
Introduction to Library Functions PCRECP(3)
REPLACING PARTS OF STRINGS
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:
string s = "yabba dabba doo";
pcrecpp::RE("b]").Replace("d", &s);
will leave "s" containing "yada dabba doo". The result is
true if the pattern matches and a replacement occurs, false
otherwise.
GlobalReplace is like Replace except that it replaces all
occurrences of the pattern in the string with the rewrite.
Replacements are not subject to re-matching. For example:
string s = "yabba dabba doo";
pcrecpp::RE("b]").GlobalReplace("d", &s);
will leave "s" containing "yada dada doo". It returns the
number of replacements made.
Extract is like Replace, 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 extrac-
tion happened successfully; if no match occurs, the string
is left unaffected.
AUTHOR
The C] wrapper was contributed by Google Inc.
Copyright (c) 2007 Google Inc.
REVISION
Last updated: 12 November 2007
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.10 Last change: 7
Introduction to Library Functions PCRECP(3)
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWpcre
Interface Stability Uncommitted
NOTES
Source for PCRE is available on http:/opensolaris.org.
SunOS 5.10 Last change: 8
|
