pcre.3

Apache V2.0.15 Alpha For Linuxhttpd-2_0_15-alpha.tar.Z

  \\b     word boundary
  \\B     not a word boundary
  \\A     start of subject (independent of multiline mode)
  \\Z     end of subject or newline at end (independent of multiline mode)
  \\z     end of subject (independent of multiline mode)

These assertions may not appear in character classes (but note that "\\b" has a
different meaning, namely the backspace character, inside a character class).

A word boundary is a position in the subject string where the current character
and the previous character do not both match \\w or \\W (i.e. one matches
\\w and the other matches \\W), or the start or end of the string if the
first or last character matches \\w, respectively.

The \\A, \\Z, and \\z assertions differ from the traditional circumflex and
dollar (described below) in that they only ever match at the very start and end
of the subject string, whatever options are set. They are not affected by the
PCRE_NOTBOL or PCRE_NOTEOL options. If the \fIstartoffset\fR argument of
\fBpcre_exec()\fR is non-zero, \\A can never match. The difference between \\Z
and \\z is that \\Z matches before a newline that is the last character of the
string as well as at the end of the string, whereas \\z matches only at the
end.


.SH CIRCUMFLEX AND DOLLAR
Outside a character class, in the default matching mode, the circumflex
character is an assertion which is true only if the current matching point is
at the start of the subject string. If the \fIstartoffset\fR argument of
\fBpcre_exec()\fR is non-zero, circumflex can never match. Inside a character
class, circumflex has an entirely different meaning (see below).

Circumflex need not be the first character of the pattern if a number of
alternatives are involved, but it should be the first thing in each alternative
in which it appears if the pattern is ever to match that branch. If all
possible alternatives start with a circumflex, that is, if the pattern is
constrained to match only at the start of the subject, it is said to be an
"anchored" pattern. (There are also other constructs that can cause a pattern
to be anchored.)

A dollar character is an assertion which is true only if the current matching
point is at the end of the subject string, or immediately before a newline
character that is the last character in the string (by default). Dollar need
not be the last character of the pattern if a number of alternatives are
involved, but it should be the last item in any branch in which it appears.
Dollar has no special meaning in a character class.

The meaning of dollar can be changed so that it matches only at the very end of
the string, by setting the PCRE_DOLLAR_ENDONLY option at compile or matching
time. This does not affect the \\Z assertion.

The meanings of the circumflex and dollar characters are changed if the
PCRE_MULTILINE option is set. When this is the case, they match immediately
after and immediately before an internal "\\n" character, respectively, in
addition to matching at the start and end of the subject string. For example,
the pattern /^abc$/ matches the subject string "def\\nabc" in multiline mode,
but not otherwise. Consequently, patterns that are anchored in single line mode
because all branches start with "^" are not anchored in multiline mode, and a
match for circumflex is possible when the \fIstartoffset\fR argument of
\fBpcre_exec()\fR is non-zero. The PCRE_DOLLAR_ENDONLY option is ignored if
PCRE_MULTILINE is set.

Note that the sequences \\A, \\Z, and \\z can be used to match the start and
end of the subject in both modes, and if all branches of a pattern start with
\\A is it always anchored, whether PCRE_MULTILINE is set or not.


.SH FULL STOP (PERIOD, DOT)
Outside a character class, a dot in the pattern matches any one character in
the subject, including a non-printing character, but not (by default) newline.
If the PCRE_DOTALL option is set, dots match newlines as well. The handling of
dot is entirely independent of the handling of circumflex and dollar, the only
relationship being that they both involve newline characters. Dot has no
special meaning in a character class.


.SH SQUARE BRACKETS
An opening square bracket introduces a character class, terminated by a closing
square bracket. A closing square bracket on its own is not special. If a
closing square bracket is required as a member of the class, it should be the
first data character in the class (after an initial circumflex, if present) or
escaped with a backslash.

A character class matches a single character in the subject; the character must
be in the set of characters defined by the class, unless the first character in
the class is a circumflex, in which case the subject character must not be in
the set defined by the class. If a circumflex is actually required as a member
of the class, ensure it is not the first character, or escape it with a
backslash.

For example, the character class [aeiou] matches any lower case vowel, while
[^aeiou] matches any character that is not a lower case vowel. Note that a
circumflex is just a convenient notation for specifying the characters which
are in the class by enumerating those that are not. It is not an assertion: it
still consumes a character from the subject string, and fails if the current
pointer is at the end of the string.

When caseless matching is set, any letters in a class represent both their
upper case and lower case versions, so for example, a caseless [aeiou] matches
"A" as well as "a", and a caseless [^aeiou] does not match "A", whereas a
caseful version would.

The newline character is never treated in any special way in character classes,
whatever the setting of the PCRE_DOTALL or PCRE_MULTILINE options is. A class
such as [^a] will always match a newline.

The minus (hyphen) character can be used to specify a range of characters in a
character class. For example, [d-m] matches any letter between d and m,
inclusive. If a minus character is required in a class, it must be escaped with
a backslash or appear in a position where it cannot be interpreted as
indicating a range, typically as the first or last character in the class.

It is not possible to have the literal character "]" as the end character of a
range. A pattern such as [W-]46] is interpreted as a class of two characters
("W" and "-") followed by a literal string "46]", so it would match "W46]" or
"-46]". However, if the "]" is escaped with a backslash it is interpreted as
the end of range, so [W-\\]46] is interpreted as a single class containing a
range followed by two separate characters. The octal or hexadecimal
representation of "]" can also be used to end a range.

Ranges operate in ASCII collating sequence. They can also be used for
characters specified numerically, for example [\\000-\\037]. If a range that
includes letters is used when caseless matching is set, it matches the letters
in either case. For example, [W-c] is equivalent to [][\\^_`wxyzabc], matched
caselessly, and if character tables for the "fr" locale are in use,
[\\xc8-\\xcb] matches accented E characters in both cases.

The character types \\d, \\D, \\s, \\S, \\w, and \\W may also appear in a
character class, and add the characters that they match to the class. For
example, [\\dABCDEF] matches any hexadecimal digit. A circumflex can
conveniently be used with the upper case character types to specify a more
restricted set of characters than the matching lower case type. For example,
the class [^\\W_] matches any letter or digit, but not underscore.

All non-alphameric characters other than \\, -, ^ (at the start) and the
terminating ] are non-special in character classes, but it does no harm if they
are escaped.


.SH POSIX CHARACTER CLASSES
Perl 5.6 (not yet released at the time of writing) is going to support the
POSIX notation for character classes, which uses names enclosed by [: and :]
within the enclosing square brackets. PCRE supports this notation. For example,

  [01[:alpha:]%]

matches "0", "1", any alphabetic character, or "%". The supported class names
are

  alnum    letters and digits
  alpha    letters
  ascii    character codes 0 - 127
  cntrl    control characters
  digit    decimal digits (same as \\d)
  graph    printing characters, excluding space
  lower    lower case letters
  print    printing characters, including space
  punct    printing characters, excluding letters and digits
  space    white space (same as \\s)
  upper    upper case letters
  word     "word" characters (same as \\w)
  xdigit   hexadecimal digits

The names "ascii" and "word" are Perl extensions. Another Perl extension is
negation, which is indicated by a ^ character after the colon. For example,

  [12[:^digit:]]

matches "1", "2", or any non-digit. PCRE (and Perl) also recogize the POSIX
syntax [.ch.] and [=ch=] where "ch" is a "collating element", but these are not
supported, and an error is given if they are encountered.


.SH VERTICAL BAR
Vertical bar characters are used to separate alternative patterns. For example,
the pattern

  gilbert|sullivan

matches either "gilbert" or "sullivan". Any number of alternatives may appear,
and an empty alternative is permitted (matching the empty string).
The matching process tries each alternative in turn, from left to right,
and the first one that succeeds is used. If the alternatives are within a
subpattern (defined below), "succeeds" means matching the rest of the main
pattern as well as the alternative in the subpattern.


.SH INTERNAL OPTION SETTING
The settings of PCRE_CASELESS, PCRE_MULTILINE, PCRE_DOTALL, and PCRE_EXTENDED
can be changed from within the pattern by a sequence of Perl option letters
enclosed between "(?" and ")". The option letters are

  i  for PCRE_CASELESS
  m  for PCRE_MULTILINE
  s  for PCRE_DOTALL
  x  for PCRE_EXTENDED

For example, (?im) sets caseless, multiline matching. It is also possible to
unset these options by preceding the letter with a hyphen, and a combined
setting and unsetting such as (?im-sx), which sets PCRE_CASELESS and
PCRE_MULTILINE while unsetting PCRE_DOTALL and PCRE_EXTENDED, is also
permitted. If a letter appears both before and after the hyphen, the option is
unset.

The scope of these option changes depends on where in the pattern the setting
occurs. For settings that are outside any subpattern (defined below), the
effect is the same as if the options were set or unset at the start of
matching. The following patterns all behave in exactly the same way:

  (?i)abc
  a(?i)bc
  ab(?i)c
  abc(?i)

which in turn is the same as compiling the pattern abc with PCRE_CASELESS set.
In other words, such "top level" settings apply to the whole pattern (unless
there are other changes inside subpatterns). If there is more than one setting
of the same option at top level, the rightmost setting is used.

If an option change occurs inside a subpattern, the effect is different. This
is a change of behaviour in Perl 5.005. An option change inside a subpattern
affects only that part of the subpattern that follows it, so

  (a(?i)b)c

matches abc and aBc and no other strings (assuming PCRE_CASELESS is not used).
By this means, options can be made to have different settings in different
parts of the pattern. Any changes made in one alternative do carry on
into subsequent branches within the same subpattern. For example,

  (a(?i)b|c)

matches "ab", "aB", "c", and "C", even though when matching "C" the first
branch is abandoned before the option setting. This is because the effects of
option settings happen at compile time. There would be some very weird
behaviour otherwise.

The PCRE-specific options PCRE_UNGREEDY and PCRE_EXTRA can be changed in the
same way as the Perl-compatible options by using the characters U and X
respectively. The (?X) flag setting is special in that it must always occur
earlier in the pattern than any of the additional features it turns on, even
when it is at top level. It is best put at the start.


.SH SUBPATTERNS
Subpatterns are delimited by parentheses (round brackets), which can be nested.
Marking part of a pattern as a subpattern does two things:

1. It localizes a set of alternatives. For example, the pattern

  cat(aract|erpillar|)

matches one of the words "cat", "cataract", or "caterpillar". Without the
parentheses, it would match "cataract", "erpillar" or the empty string.

2. It sets up the subpattern as a capturing subpattern (as defined above).
When the whole pattern matches, that portion of the subject string that matched
the subpattern is passed back to the caller via the \fIovector\fR argument of
\fBpcre_exec()\fR. Opening parentheses are counted from left to right (starting
from 1) to obtain the numbers of the capturing subpatterns.

For example, if the string "the red king" is matched against the pattern

  the ((red|white) (king|queen))

the captured substrings are "red king", "red", and "king", and are numbered 1,
2, and 3.

The fact that plain parentheses fulfil two functions is not always helpful.
There are often times when a grouping subpattern is required without a
capturing requirement. If an opening parenthesis is followed by "?:", the
subpattern does not do any capturing, and is not counted when computing the
number of any subsequent capturing subpatterns. For example, if the string "the
white queen" is matched against the pattern

  the ((?:red|white) (king|queen))

the captured substrings are "white queen" and "queen", and are numbered 1 and
2. The maximum number of captured substrings is 99, and the maximum number of
all subpatterns, both capturing and non-capturing, is 200.

As a convenient shorthand, if any option settings are required at the start of
a non-capturing subpattern, the option letters may appear between the "?" and
the ":". Thus the two patterns