doc/concepts/pcre

SYNOPSIS
        PCRE - Perl-compatible regular expressions


DESCRIPTION
        This document describes the regular expressions supported by the
        PCRE package. When the package is compiled into the driver, the
        macro __PCRE__ is defined.

        Most of this manpage is lifted directly from the original PCRE
        manpage (dated January 2003).

        The PCRE library is a set of functions that implement  regular
        expression  pattern  matching using the same syntax and semantics
        as Perl  5,  with  just  a  few  differences  (see below).  The
        current  implementation  corresponds  to  Perl 5.005, with some
        additional features  from  later  versions.  This  includes  some
        experimental,  incomplete  support for UTF-8 encoded strings.
        Details of exactly what is  and  what is not supported are given
        below.


PCRE REGULAR EXPRESSION DETAILS

       The  syntax  and semantics of the regular expressions supported by PCRE
       are described below. Regular expressions are also described in the Perl
       documentation  and in a number of other books, some of which have copi-
       ous examples. Jeffrey Friedl's "Mastering  Regular  Expressions",  pub-
       lished  by  O'Reilly, covers them in great detail. The description here
       is intended as reference documentation.

       The basic operation of PCRE is on strings of bytes. However,  there  is
       also  support for UTF-8 character strings. To use this support you must
       build PCRE to include UTF-8 support, and then call pcre_compile()  with
       the  PCRE_UTF8  option.  How  this affects the pattern matching is men-
       tioned in several places below. There is also a summary of  UTF-8  fea-
       tures in the section on UTF-8 support in the main pcre page.

       A  regular  expression  is  a pattern that is matched against a subject
       string from left to right. Most characters stand for  themselves  in  a
       pattern,  and  match  the corresponding characters in the subject. As a
       trivial example, the pattern

         The quick brown fox

       matches a portion of a subject string that is identical to itself.  The
       power of regular expressions comes from the ability to include alterna-
       tives and repetitions in the pattern. These are encoded in the  pattern
       by  the  use  of meta-characters, which do not stand for themselves but
       instead are interpreted in some special way.

       There are two different sets of meta-characters: those that are  recog-
       nized  anywhere in the pattern except within square brackets, and those
       that are recognized in square brackets. Outside  square  brackets,  the
       meta-characters are as follows:

         \      general escape character with several uses
         ^      assert start of string (or line, in multiline mode)
         $      assert end of string (or line, in multiline mode)
         .      match any character except newline (by default)
         [      start character class definition
         |      start of alternative branch
         (      start subpattern
         )      end subpattern
         ?      extends the meaning of (
                also 0 or 1 quantifier
                also quantifier minimizer
         *      0 or more quantifier
         +      1 or more quantifier
                also "possessive quantifier"
         {      start min/max quantifier

       Part  of  a  pattern  that is in square brackets is called a "character
       class". In a character class the only meta-characters are:

         \      general escape character
         ^      negate the class, but only if the first character
         -      indicates character range
         [      POSIX character class (only if followed by POSIX
                  syntax)
         ]      terminates the character class

       The following sections describe the use of each of the meta-characters.


BACKSLASH

       The backslash character has several uses. Firstly, if it is followed by
       a non-alphameric character, it takes  away  any  special  meaning  that
       character  may  have.  This  use  of  backslash  as an escape character
       applies both inside and outside character classes.

       For example, if you want to match a * character, you write  \*  in  the
       pattern.   This  escaping  action  applies whether or not the following
       character would otherwise be interpreted as a meta-character, so it  is
       always  safe to precede a non-alphameric with backslash to specify that
       it stands for itself. In particular, if you want to match a  backslash,
       you write \\.

       If  a  pattern is compiled with the PCRE_EXTENDED option, whitespace in
       the pattern (other than in a character class) and characters between  a
       # outside a character class and the next newline character are ignored.
       An escaping backslash can be used to include a whitespace or #  charac-
       ter as part of the pattern.

       If  you  want  to remove the special meaning from a sequence of charac-
       ters, you can do so by putting them between \Q and \E. This is  differ-
       ent  from  Perl  in  that  $  and  @ are handled as literals in \Q...\E
       sequences in PCRE, whereas in Perl, $ and @ cause  variable  interpola-
       tion. Note the following examples:

         Pattern            PCRE matches   Perl matches

         \Qabc$xyz\E        abc$xyz        abc followed by the
                                             contents of $xyz
         \Qabc\$xyz\E       abc\$xyz       abc\$xyz
         \Qabc\E\$\Qxyz\E   abc$xyz        abc$xyz

       The  \Q...\E  sequence  is recognized both inside and outside character
       classes.

       A second use of backslash provides a way of encoding non-printing char-
       acters  in patterns in a visible manner. There is no restriction on the
       appearance of non-printing characters, apart from the binary zero  that
       terminates  a  pattern,  but  when  a pattern is being prepared by text
       editing, it is usually easier  to  use  one  of  the  following  escape
       sequences than the binary character it represents:

         \a        alarm, that is, the BEL character (hex 07)
         \cx       "control-x", where x is any character
         \e        escape (hex 1B)
         \f        formfeed (hex 0C)
         \n        newline (hex 0A)
         \r        carriage return (hex 0D)
         \t        tab (hex 09)
         \ddd      character with octal code ddd, or backreference
         \xhh      character with hex code hh
         \x{hhh..} character with hex code hhh... (UTF-8 mode only)

       The  precise  effect of \cx is as follows: if x is a lower case letter,
       it is converted to upper case. Then bit 6 of the character (hex 40)  is
       inverted.   Thus  \cz becomes hex 1A, but \c{ becomes hex 3B, while \c;
       becomes hex 7B.

       After \x, from zero to two hexadecimal digits are read (letters can  be
       in  upper or lower case). In UTF-8 mode, any number of hexadecimal dig-
       its may appear between \x{ and }, but the value of the  character  code
       must  be  less  than  2**31  (that is, the maximum hexadecimal value is
       7FFFFFFF). If characters other than hexadecimal digits  appear  between
       \x{  and }, or if there is no terminating }, this form of escape is not
       recognized. Instead, the initial \x will be interpreted as a basic hex-
       adecimal escape, with no following digits, giving a byte whose value is
       zero.

       Characters whose value is less than 256 can be defined by either of the
       two  syntaxes for \x when PCRE is in UTF-8 mode. There is no difference
       in the way they are handled. For example, \xdc is exactly the  same  as
       \x{dc}.

       After  \0  up  to  two further octal digits are read. In both cases, if
       there are fewer than two digits, just those that are present are  used.
       Thus  the sequence \0\x\07 specifies two binary zeros followed by a BEL
       character (code value 7). Make sure you supply  two  digits  after  the
       initial zero if the character that follows is itself an octal digit.

       The handling of a backslash followed by a digit other than 0 is compli-
       cated.  Outside a character class, PCRE reads it and any following dig-
       its  as  a  decimal  number. If the number is less than 10, or if there
       have been at least that many previous capturing left parentheses in the
       expression,  the  entire  sequence  is  taken  as  a  back reference. A
       description of how this works is given later, following the  discussion
       of parenthesized subpatterns.

       Inside  a  character  class, or if the decimal number is greater than 9
       and there have not been that many capturing subpatterns, PCRE  re-reads
       up  to three octal digits following the backslash, and generates a sin-
       gle byte from the least significant 8 bits of the value. Any subsequent
       digits stand for themselves.  For example:

         \040   is another way of writing a space
         \40    is the same, provided there are fewer than 40
                   previous capturing subpatterns
         \7     is always a back reference
         \11    might be a back reference, or another way of
                   writing a tab
         \011   is always a tab
         \0113  is a tab followed by the character "3"
         \113   might be a back reference, otherwise the
                   character with octal code 113
         \377   might be a back reference, otherwise
                   the byte consisting entirely of 1 bits
         \81    is either a back reference, or a binary zero
                   followed by the two characters "8" and "1"

       Note  that  octal  values of 100 or greater must not be introduced by a
       leading zero, because no more than three octal digits are ever read.

       All the sequences that define a single byte value  or  a  single  UTF-8
       character (in UTF-8 mode) can be used both inside and outside character
       classes. In addition, inside a character  class,  the  sequence  \b  is
       interpreted  as  the  backspace character (hex 08). Outside a character
       class it has a different meaning (see below).

       The third use of backslash is for specifying generic character types:

         \d     any decimal digit
         \D     any character that is not a decimal digit
         \s     any whitespace character
         \S     any character that is not a whitespace character
         \w     any "word" character
         \W     any "non-word" character

       Each pair of escape sequences partitions the complete set of characters
       into  two disjoint sets. Any given character matches one, and only one,
       of each pair.

       In UTF-8 mode, characters with values greater than 255 never match  \d,
       \s, or \w, and always match \D, \S, and \W.

       For  compatibility  with Perl, \s does not match the VT character (code
       11).  This makes it different from the the POSIX "space" class. The  \s
       characters are HT (9), LF (10), FF (12), CR (13), and space (32).

       A  "word" character is any letter or digit or the underscore character,
       that is, any character which can be part of a Perl "word". The  defini-
       tion  of  letters  and digits is controlled by PCRE's character tables,
       and may vary if locale- specific matching is taking place (see  "Locale
       support"  in  the  pcreapi  page).  For  example,  in the "fr" (French)
       locale, some character codes greater than 128  are  used  for  accented
       letters, and these are matched by \w.

       These character type sequences can appear both inside and outside char-
       acter classes. They each match one character of the  appropriate  type.
       If  the current matching point is at the end of the subject string, all
       of them fail, since there is no character to match.

       The fourth use of backslash is for certain simple assertions. An asser-
       tion  specifies a condition that has to be met at a particular point in
       a match, without consuming any characters from the subject string.  The
       use  of subpatterns for more complicated assertions is described below.
       The backslashed assertions are

         \b     matches at a word boundary
         \B     matches when not at a word boundary
         \A     matches at start of subject
         \Z     matches at end of subject or before newline at end
         \z     matches at end of subject
         \G     matches at first matching position in subject

       These assertions may not appear in character classes (but note that  \b
       has a different meaning, namely the backspace character, inside a char-
       acter 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. Thus,
       they are independent of multiline mode.

       They are not affected by the PCRE_NOTBOL or PCRE_NOTEOL options. If the
       startoffset argument of pcre_exec() is non-zero, indicating that match-
       ing is to start at a point other than the beginning of the subject,  \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.

       The  \G assertion is true only when the current matching position is at
       the start point of the match, as specified by the startoffset  argument
       of  pcre_exec().  It  differs  from \A when the value of startoffset is
       non-zero. By calling pcre_exec() multiple times with appropriate  argu-
       ments, you can mimic Perl's /g option, and it is in this kind of imple-
       mentation where \G can be useful.

       Note, however, that PCRE's interpretation of \G, as the  start  of  the
       current match, is subtly different from Perl's, which defines it as the
       end of the previous match. In Perl, these can  be  different  when  the
       previously  matched  string was empty. Because PCRE does just one match
       at a time, it cannot reproduce this behaviour.

       If all the alternatives of a pattern begin with \G, the  expression  is
       anchored to the starting match position, and the "anchored" flag is set
       in the compiled regular expression.


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  startoffset  argu-
       ment  of  pcre_exec()  is  non-zero,  circumflex can never match if the
       PCRE_MULTILINE option is unset. 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 sub-
       ject, 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 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 immedi-
       ately  after  and  immediately  before  an  internal newline character,
       respectively, in addition to matching at the start and end of the  sub-
       ject  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  cir-
       cumflex  is  possible  when  the startoffset argument of pcre_exec() 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 it is always anchored, whether PCRE_MULTILINE is set or
       not.


FULL STOP (PERIOD, DOT)

       Outside a character class, a dot in the pattern matches any one charac-
       ter  in  the  subject,  including a non-printing character, but not (by
       default) newline.  In UTF-8 mode, a dot matches  any  UTF-8  character,
       which  might  be  more than one byte long, except (by default) for new-
       line. If the PCRE_DOTALL option is set, dots match  newlines  as  well.
       The  handling of dot is entirely independent of the handling of circum-
       flex and dollar, the only relationship being  that  they  both  involve
       newline characters. Dot has no special meaning in a character class.


MATCHING A SINGLE BYTE

       Outside a character class, the escape sequence \C matches any one byte,
       both in and out of UTF-8 mode. Unlike a dot, it always matches  a  new-
       line.  The  feature  is  provided  in Perl in order to match individual
       bytes in UTF-8 mode.  Because it breaks up UTF-8 characters into  indi-
       vidual  bytes,  what  remains  in  the  string may be a malformed UTF-8
       string. For this reason it is best avoided.

       PCRE does not allow \C to appear in lookbehind assertions (see  below),
       because in UTF-8 mode it makes it impossible to calculate the length of
       the lookbehind.


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 spe-
       cial. 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.  In  UTF-8
       mode,  the character may occupy more than one byte. A matched character
       must be in the set of characters defined by the class, unless the first
       character  in  the  class definition 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.

       In  UTF-8 mode, characters with values greater than 255 can be included
       in a class as a literal string of bytes, or by using the  \x{  escaping
       mechanism.

       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. PCRE does not  support  the
       concept of case for characters with values greater than 255.

       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 charac-
       ters 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 charac-
       ter  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  inter-
       preted  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 the collating sequence of character values. They can
       also  be  used  for  characters  specified  numerically,  for   example
       [\000-\037].  In UTF-8 mode, ranges can include characters whose values
       are greater than 255, for example [\x{100}-\x{2ff}].

       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.


POSIX CHARACTER CLASSES

       Perl supports the POSIX notation  for  character  classes,  which  uses
       names  enclosed by [: and :] within the enclosing square brackets. PCRE
       also 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
         blank    space or tab only
         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 (not quite the same as \s)
         upper    upper case letters
         word     "word" characters (same as \w)
         xdigit   hexadecimal digits

       The  "space" characters are HT (9), LF (10), VT (11), FF (12), CR (13),
       and space (32). Notice that this list includes the VT  character  (code
       11). This makes "space" different to \s, which does not include VT (for
       Perl compatibility).

       The name "word" is a Perl extension, and "blank"  is  a  GNU  extension
       from  Perl  5.8. 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 recognize  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.

       In UTF-8 mode, characters with values greater than 255 do not match any
       of the POSIX character classes.


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 alterna-
       tives  are within a subpattern (defined below), "succeeds" means match-
       ing the rest of the main pattern as well as the alternative in the sub-
       pattern.


INTERNAL OPTION SETTING

       The  settings  of  the  PCRE_CASELESS, PCRE_MULTILINE, PCRE_DOTALL, and
       PCRE_EXTENDED options 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 possi-
       ble to unset these options by preceding the letter with a hyphen, and a
       combined setting and unsetting such as (?im-sx), which sets  PCRE_CASE-
       LESS  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.

       When  an option change occurs at top level (that is, not inside subpat-
       tern parentheses), the change applies to the remainder of  the  pattern
       that follows.  If the change is placed right at the start of a pattern,
       PCRE extracts it into the global options (and it will therefore show up
       in data extracted by the pcre_fullinfo() function).

       An option change within a subpattern affects only that part of the cur-
       rent pattern 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.


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
       ovector argument of pcre_exec(). 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  pat-
       tern

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

       the captured substrings are "red king", "red", and "king", and are num-
       bered 1, 2, and 3, respectively.

       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  a question mark and a colon, the subpattern does not do any captur-
       ing, 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 capturing subpatterns is 65535, and the
       maximum depth of nesting 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

         (?i:saturday|sunday)
         (?:(?i)saturday|sunday)

       match exactly the same set of strings. Because alternative branches are
       tried from left to right, and options are not reset until  the  end  of
       the  subpattern is reached, an option setting in one branch does affect
       subsequent branches, so the above patterns match "SUNDAY"  as  well  as
       "Saturday".


NAMED SUBPATTERNS

       Identifying  capturing  parentheses  by number is simple, but it can be
       very hard to keep track of the numbers in complicated  regular  expres-
       sions.  Furthermore,  if  an  expression  is  modified, the numbers may
       change. To help with the difficulty, PCRE supports the naming  of  sub-
       patterns,  something  that  Perl  does  not  provide. The Python syntax
       (?P<name>...) is used. Names consist  of  alphanumeric  characters  and
       underscores, and must be unique within a pattern.

       Named  capturing  parentheses  are  still  allocated numbers as well as
       names. The PCRE API provides function calls for extracting the name-to-
       number  translation  table from a compiled pattern. For further details
       see the pcreapi documentation.


REPETITION

       Repetition is specified by quantifiers, which can  follow  any  of  the
       following items:

         a literal data character
         the . metacharacter
         the \C escape sequence
         escapes such as \d that match single characters
         a character class
         a back reference (see next section)
         a parenthesized subpattern (unless it is an assertion)

       The  general repetition quantifier specifies a minimum and maximum num-
       ber of permitted matches, by giving the two numbers in  curly  brackets
       (braces),  separated  by  a comma. The numbers must be less than 65536,
       and the first must be less than or equal to the second. For example:

         z{2,4}

       matches "zz", "zzz", or "zzzz". A closing brace on its  own  is  not  a
       special  character.  If  the second number is omitted, but the comma is
       present, there is no upper limit; if the second number  and  the  comma
       are  both omitted, the quantifier specifies an exact number of required
       matches. Thus

         [aeiou]{3,}

       matches at least 3 successive vowels, but may match many more, while

         \d{8}

       matches exactly 8 digits. An opening curly bracket that  appears  in  a
       position  where a quantifier is not allowed, or one that does not match
       the syntax of a quantifier, is taken as a literal character. For  exam-
       ple, {,6} is not a quantifier, but a literal string of four characters.

       In UTF-8 mode, quantifiers apply to UTF-8  characters  rather  than  to
       individual bytes. Thus, for example, \x{100}{2} matches two UTF-8 char-
       acters, each of which is represented by a two-byte sequence.

       The quantifier {0} is permitted, causing the expression to behave as if
       the previous item and the quantifier were not present.

       For  convenience  (and  historical compatibility) the three most common
       quantifiers have single-character abbreviations:

         *    is equivalent to {0,}
         +    is equivalent to {1,}
         ?    is equivalent to {0,1}

       It is possible to construct infinite loops by  following  a  subpattern
       that can match no characters with a quantifier that has no upper limit,
       for example:

         (a?)*

       Earlier versions of Perl and PCRE used to give an error at compile time
       for  such  patterns. However, because there are cases where this can be
       useful, such patterns are now accepted, but if any  repetition  of  the
       subpattern  does in fact match no characters, the loop is forcibly bro-
       ken.

       By default, the quantifiers are "greedy", that is, they match  as  much
       as  possible  (up  to  the  maximum number of permitted times), without
       causing the rest of the pattern to fail. The classic example  of  where
       this gives problems is in trying to match comments in C programs. These
       appear between the sequences /* and */ and within the  sequence,  indi-
       vidual * and / characters may appear. An attempt to match C comments by
       applying the pattern

         /\*.*\*/

       to the string

         /* first command */  not comment  /* second comment */

       fails, because it matches the entire string owing to the greediness  of
       the .*  item.

       However,  if  a quantifier is followed by a question mark, it ceases to
       be greedy, and instead matches the minimum number of times possible, so
       the pattern

         /\*.*?\*/

       does  the  right  thing with the C comments. The meaning of the various
       quantifiers is not otherwise changed,  just  the  preferred  number  of
       matches.   Do  not  confuse this use of question mark with its use as a
       quantifier in its own right. Because it has two uses, it can  sometimes
       appear doubled, as in

         \d??\d

       which matches one digit by preference, but can match two if that is the
       only way the rest of the pattern matches.

       If the PCRE_UNGREEDY option is set (an option which is not available in
       Perl),  the  quantifiers are not greedy by default, but individual ones
       can be made greedy by following them with a  question  mark.  In  other
       words, it inverts the default behaviour.

       When  a  parenthesized  subpattern  is quantified with a minimum repeat
       count that is greater than 1 or with a limited maximum, more  store  is
       required  for  the  compiled  pattern, in proportion to the size of the
       minimum or maximum.

       If a pattern starts with .* or .{0,} and the PCRE_DOTALL option (equiv-
       alent  to Perl's /s) is set, thus allowing the . to match newlines, the
       pattern is implicitly anchored, because whatever follows will be  tried
       against  every character position in the subject string, so there is no
       point in retrying the overall match at any position  after  the  first.
       PCRE normally treats such a pattern as though it were preceded by \A.

       In  cases  where  it  is known that the subject string contains no new-
       lines, it is worth setting PCRE_DOTALL in order to  obtain  this  opti-
       mization, or alternatively using ^ to indicate anchoring explicitly.

       However,  there is one situation where the optimization cannot be used.
       When .*  is inside capturing parentheses that  are  the  subject  of  a
       backreference  elsewhere in the pattern, a match at the start may fail,
       and a later one succeed. Consider, for example:

         (.*)abc\1

       If the subject is "xyz123abc123" the match point is the fourth  charac-
       ter. For this reason, such a pattern is not implicitly anchored.

       When a capturing subpattern is repeated, the value captured is the sub-
       string that matched the final iteration. For example, after

         (tweedle[dume]{3}\s*)+

       has matched "tweedledum tweedledee" the value of the captured substring
       is  "tweedledee".  However,  if there are nested capturing subpatterns,
       the corresponding captured values may have been set in previous  itera-
       tions. For example, after

         /(a|(b))+/

       matches "aba" the value of the second captured substring is "b".


ATOMIC GROUPING AND POSSESSIVE QUANTIFIERS

       With both maximizing and minimizing repetition, failure of what follows
       normally causes the repeated item to be re-evaluated to see if  a  dif-
       ferent number of repeats allows the rest of the pattern to match. Some-
       times it is useful to prevent this, either to change the nature of  the
       match,  or  to  cause it fail earlier than it otherwise might, when the
       author of the pattern knows there is no point in carrying on.

       Consider, for example, the pattern \d+foo when applied to  the  subject
       line

         123456bar

       After matching all 6 digits and then failing to match "foo", the normal
       action of the matcher is to try again with only 5 digits  matching  the
       \d+  item,  and  then  with  4,  and  so on, before ultimately failing.
       "Atomic grouping" (a term taken from Jeffrey  Friedl's  book)  provides
       the  means for specifying that once a subpattern has matched, it is not
       to be re-evaluated in this way.

       If we use atomic grouping for the previous example, the  matcher  would
       give up immediately on failing to match "foo" the first time. The nota-
       tion is a kind of special parenthesis, starting with  (?>  as  in  this
       example:

         (?>\d+)foo

       This  kind  of  parenthesis "locks up" the  part of the pattern it con-
       tains once it has matched, and a failure further into  the  pattern  is
       prevented  from  backtracking into it. Backtracking past it to previous
       items, however, works as normal.

       An alternative description is that a subpattern of  this  type  matches
       the  string  of  characters  that an identical standalone pattern would
       match, if anchored at the current point in the subject string.

       Atomic grouping subpatterns are not capturing subpatterns. Simple cases
       such as the above example can be thought of as a maximizing repeat that
       must swallow everything it can. So, while both \d+ and  \d+?  are  pre-
       pared  to  adjust  the number of digits they match in order to make the
       rest of the pattern match, (?>\d+) can only match an entire sequence of
       digits.

       Atomic  groups in general can of course contain arbitrarily complicated
       subpatterns, and can be nested. However, when  the  subpattern  for  an
       atomic group is just a single repeated item, as in the example above, a
       simpler notation, called a "possessive quantifier" can  be  used.  This
       consists  of  an  additional  + character following a quantifier. Using
       this notation, the previous example can be rewritten as

         \d++bar

       Possessive  quantifiers  are  always  greedy;  the   setting   of   the
       PCRE_UNGREEDY option is ignored. They are a convenient notation for the
       simpler forms of atomic group. However, there is no difference  in  the
       meaning  or  processing  of  a possessive quantifier and the equivalent
       atomic group.

       The possessive quantifier syntax is an extension to the Perl syntax. It
       originates in Sun's Java package.

       When  a  pattern  contains an unlimited repeat inside a subpattern that
       can itself be repeated an unlimited number of  times,  the  use  of  an
       atomic  group  is  the  only way to avoid some failing matches taking a
       very long time indeed. The pattern

         (\D+|<\d+>)*[!?]

       matches an unlimited number of substrings that either consist  of  non-
       digits,  or  digits  enclosed in <>, followed by either ! or ?. When it
       matches, it runs quickly. However, if it is applied to

         aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

       it takes a long time before reporting  failure.  This  is  because  the
       string  can  be  divided  between  the two repeats in a large number of
       ways, and all have to be tried. (The example used [!?]  rather  than  a
       single  character  at the end, because both PCRE and Perl have an opti-
       mization that allows for fast failure when a single character is  used.
       They  remember  the last single character that is required for a match,
       and fail early if it is not present in the string.)  If the pattern  is
       changed to

         ((?>\D+)|<\d+>)*[!?]

       sequences  of non-digits cannot be broken, and failure happens quickly.


BACK REFERENCES

       Outside a character class, a backslash followed by a digit greater than
       0 (and possibly further digits) is a back reference to a capturing sub-
       pattern earlier (that is, to its left) in the pattern,  provided  there
       have been that many previous capturing left parentheses.

       However, if the decimal number following the backslash is less than 10,
       it is always taken as a back reference, and causes  an  error  only  if
       there  are  not that many capturing left parentheses in the entire pat-
       tern. In other words, the parentheses that are referenced need  not  be
       to  the left of the reference for numbers less than 10. See the section
       entitled "Backslash" above for further details of the handling of  dig-
       its following a backslash.

       A  back  reference matches whatever actually matched the capturing sub-
       pattern in the current subject string, rather  than  anything  matching
       the subpattern itself (see "Subpatterns as subroutines" below for a way
       of doing that). So the pattern

         (sens|respons)e and \1ibility

       matches "sense and sensibility" and "response and responsibility",  but
       not  "sense and responsibility". If caseful matching is in force at the
       time of the back reference, the case of letters is relevant. For  exam-
       ple,

         ((?i)rah)\s+\1

       matches  "rah  rah"  and  "RAH RAH", but not "RAH rah", even though the
       original capturing subpattern is matched caselessly.

       Back references to named subpatterns use the Python  syntax  (?P=name).
       We could rewrite the above example as follows:

         (?<p1>(?i)rah)\s+(?P=p1)

       There  may be more than one back reference to the same subpattern. If a
       subpattern has not actually been used in a particular match,  any  back
       references to it always fail. For example, the pattern

         (a|(bc))\2

       always  fails if it starts to match "a" rather than "bc". Because there
       may be many capturing parentheses in a pattern,  all  digits  following
       the  backslash  are taken as part of a potential back reference number.
       If the pattern continues with a digit character, some delimiter must be
       used  to  terminate  the back reference. If the PCRE_EXTENDED option is
       set, this can be whitespace.  Otherwise an empty comment can be used.

       A back reference that occurs inside the parentheses to which it  refers
       fails  when  the subpattern is first used, so, for example, (a\1) never
       matches.  However, such references can be useful inside  repeated  sub-
       patterns. For example, the pattern

         (a|b\1)+

       matches any number of "a"s and also "aba", "ababbaa" etc. At each iter-
       ation of the subpattern,  the  back  reference  matches  the  character
       string  corresponding  to  the previous iteration. In order for this to
       work, the pattern must be such that the first iteration does  not  need
       to  match the back reference. This can be done using alternation, as in
       the example above, or by a quantifier with a minimum of zero.


ASSERTIONS

       An assertion is a test on the characters  following  or  preceding  the
       current  matching  point that does not actually consume any characters.
       The simple assertions coded as \b, \B, \A, \G, \Z,  \z,  ^  and  $  are
       described above.  More complicated assertions are coded as subpatterns.
       There are two kinds: those that look ahead of the current  position  in
       the subject string, and those that look behind it.

       An  assertion  subpattern  is matched in the normal way, except that it
       does not cause the current matching position to be  changed.  Lookahead
       assertions  start with (?= for positive assertions and (?! for negative
       assertions. For example,

         \w+(?=;)

       matches a word followed by a semicolon, but does not include the  semi-
       colon in the match, and

         foo(?!bar)

       matches  any  occurrence  of  "foo" that is not followed by "bar". Note
       that the apparently similar pattern

         (?!foo)bar

       does not find an occurrence of "bar"  that  is  preceded  by  something
       other  than "foo"; it finds any occurrence of "bar" whatsoever, because
       the assertion (?!foo) is always true when the next three characters are
       "bar". A lookbehind assertion is needed to achieve this effect.

       If you want to force a matching failure at some point in a pattern, the
       most convenient way to do it is  with  (?!)  because  an  empty  string
       always  matches, so an assertion that requires there not to be an empty
       string must always fail.

       Lookbehind assertions start with (?<= for positive assertions and  (?<!
       for negative assertions. For example,

         (?<!foo)bar

       does  find  an  occurrence  of "bar" that is not preceded by "foo". The
       contents of a lookbehind assertion are restricted  such  that  all  the
       strings it matches must have a fixed length. However, if there are sev-
       eral alternatives, they do not all have to have the same fixed  length.
       Thus

         (?<=bullock|donkey)

       is permitted, but

         (?<!dogs?|cats?)

       causes  an  error at compile time. Branches that match different length
       strings are permitted only at the top level of a lookbehind  assertion.
       This  is  an  extension  compared  with  Perl (at least for 5.8), which
       requires all branches to match the same length of string. An  assertion
       such as

         (?<=ab(c|de))

       is  not  permitted,  because  its single top-level branch can match two
       different lengths, but it is acceptable if rewritten to  use  two  top-
       level branches:

         (?<=abc|abde)

       The  implementation  of lookbehind assertions is, for each alternative,
       to temporarily move the current position back by the  fixed  width  and
       then try to match. If there are insufficient characters before the cur-
       rent position, the match is deemed to fail.

       PCRE does not allow the \C escape (which matches a single byte in UTF-8
       mode)  to appear in lookbehind assertions, because it makes it impossi-
       ble to calculate the length of the lookbehind.

       Atomic groups can be used in conjunction with lookbehind assertions  to
       specify efficient matching at the end of the subject string. Consider a
       simple pattern such as

         abcd$

       when applied to a long string that does  not  match.  Because  matching
       proceeds from left to right, PCRE will look for each "a" in the subject
       and then see if what follows matches the rest of the  pattern.  If  the
       pattern is specified as

         ^.*abcd$

       the  initial .* matches the entire string at first, but when this fails
       (because there is no following "a"), it backtracks to match all but the
       last  character,  then all but the last two characters, and so on. Once
       again the search for "a" covers the entire string, from right to  left,
       so we are no better off. However, if the pattern is written as

         ^(?>.*)(?<=abcd)

       or, equivalently,

         ^.*+(?<=abcd)

       there  can  be  no  backtracking for the .* item; it can match only the
       entire string. The subsequent lookbehind assertion does a  single  test
       on  the last four characters. If it fails, the match fails immediately.
       For long strings, this approach makes a significant difference  to  the
       processing time.

       Several assertions (of any sort) may occur in succession. For example,

         (?<=\d{3})(?<!999)foo

       matches  "foo" preceded by three digits that are not "999". Notice that
       each of the assertions is applied independently at the  same  point  in
       the  subject  string.  First  there  is a check that the previous three
       characters are all digits, and then there is  a  check  that  the  same
       three characters are not "999".  This pattern does not match "foo" pre-
       ceded by six characters, the first of which are  digits  and  the  last
       three  of  which  are not "999". For example, it doesn't match "123abc-
       foo". A pattern to do that is

         (?<=\d{3}...)(?<!999)foo

       This time the first assertion looks at the  preceding  six  characters,
       checking that the first three are digits, and then the second assertion
       checks that the preceding three characters are not "999".

       Assertions can be nested in any combination. For example,

         (?<=(?<!foo)bar)baz

       matches an occurrence of "baz" that is preceded by "bar" which in  turn
       is not preceded by "foo", while

         (?<=\d{3}(?!999)...)foo

       is another pattern which matches "foo" preceded by three digits and any
       three characters that are not "999".

       Assertion subpatterns are not capturing subpatterns,  and  may  not  be
       repeated,  because  it  makes no sense to assert the same thing several
       times. If any kind of assertion contains capturing  subpatterns  within
       it,  these are counted for the purposes of numbering the capturing sub-
       patterns in the whole pattern.  However, substring capturing is carried
       out  only  for  positive assertions, because it does not make sense for
       negative assertions.


CONDITIONAL SUBPATTERNS

       It is possible to cause the matching process to obey a subpattern  con-
       ditionally  or to choose between two alternative subpatterns, depending
       on the  result  of  an  assertion,  or  whether  a  previous  capturing
       subpattern  matched  or not. The two possible forms of conditional sub-
       pattern are

         (?(condition)yes-pattern)
         (?(condition)yes-pattern|no-pattern)

       If the condition is satisfied, the yes-pattern is used;  otherwise  the
       no-pattern  (if  present)  is used. If there are more than two alterna-
       tives in the subpattern, a compile-time error occurs.

       There are three kinds of condition. If the text between the parentheses
       consists  of  a  sequence  of digits, the condition is satisfied if the
       capturing subpattern of that number has previously matched. The  number
       must  be  greater than zero. Consider the following pattern, which con-
       tains non-significant white space to make it more readable (assume  the
       PCRE_EXTENDED  option)  and  to  divide it into three parts for ease of
       discussion:

         ( \( )?    [^()]+    (?(1) \) )

       The first part matches an optional opening  parenthesis,  and  if  that
       character is present, sets it as the first captured substring. The sec-
       ond part matches one or more characters that are not  parentheses.  The
       third part is a conditional subpattern that tests whether the first set
       of parentheses matched or not. If they did, that is, if subject started
       with an opening parenthesis, the condition is true, and so the yes-pat-
       tern is executed and a  closing  parenthesis  is  required.  Otherwise,
       since  no-pattern  is  not  present, the subpattern matches nothing. In
       other words,  this  pattern  matches  a  sequence  of  non-parentheses,
       optionally enclosed in parentheses.

       If the condition is the string (R), it is satisfied if a recursive call
       to the pattern or subpattern has been made. At "top level", the  condi-
       tion  is  false.   This  is  a  PCRE  extension. Recursive patterns are
       described in the next section.

       If the condition is not a sequence of digits or  (R),  it  must  be  an
       assertion.   This may be a positive or negative lookahead or lookbehind
       assertion. Consider  this  pattern,  again  containing  non-significant
       white space, and with the two alternatives on the second line:

         (?(?=[^a-z]*[a-z])
         \d{2}-[a-z]{3}-\d{2}  |  \d{2}-\d{2}-\d{2} )

       The  condition  is  a  positive  lookahead  assertion  that  matches an
       optional sequence of non-letters followed by a letter. In other  words,
       it  tests  for the presence of at least one letter in the subject. If a
       letter is found, the subject is matched against the first  alternative;
       otherwise  it  is  matched  against  the  second.  This pattern matches
       strings in one of the two forms dd-aaa-dd or dd-dd-dd,  where  aaa  are
       letters and dd are digits.


COMMENTS

       The sequence (?# marks the start of a comment which continues up to the
       next closing parenthesis. Nested parentheses  are  not  permitted.  The
       characters  that make up a comment play no part in the pattern matching
       at all.

       If the PCRE_EXTENDED option is set, an unescaped # character outside  a
       character class introduces a comment that continues up to the next new-
       line character in the pattern.


RECURSIVE PATTERNS

       Consider the problem of matching a string in parentheses, allowing  for
       unlimited  nested  parentheses.  Without the use of recursion, the best
       that can be done is to use a pattern that  matches  up  to  some  fixed
       depth  of  nesting.  It  is not possible to handle an arbitrary nesting
       depth. Perl has provided an experimental facility that  allows  regular
       expressions to recurse (amongst other things). It does this by interpo-
       lating Perl code in the expression at run time, and the code can  refer
       to the expression itself. A Perl pattern to solve the parentheses prob-
       lem can be created like this:

         $re = qr{\( (?: (?>[^()]+) | (?p{$re}) )* \)}x;

       The (?p{...}) item interpolates Perl code at run time, and in this case
       refers  recursively to the pattern in which it appears. Obviously, PCRE
       cannot support the interpolation of Perl  code.  Instead,  it  supports
       some  special  syntax for recursion of the entire pattern, and also for
       individual subpattern recursion.

       The special item that consists of (? followed by a number greater  than
       zero and a closing parenthesis is a recursive call of the subpattern of
       the given number, provided that it occurs inside that  subpattern.  (If
       not,  it  is  a  "subroutine" call, which is described in the next sec-
       tion.) The special item (?R) is a recursive call of the entire  regular
       expression.

       For  example,  this  PCRE pattern solves the nested parentheses problem
       (assume the  PCRE_EXTENDED  option  is  set  so  that  white  space  is
       ignored):

         \( ( (?>[^()]+) | (?R) )* \)

       First  it matches an opening parenthesis. Then it matches any number of
       substrings which can either be a  sequence  of  non-parentheses,  or  a
       recursive  match  of  the pattern itself (that is a correctly parenthe-
       sized substring).  Finally there is a closing parenthesis.

       If this were part of a larger pattern, you would not  want  to  recurse
       the entire pattern, so instead you could use this:

         ( \( ( (?>[^()]+) | (?1) )* \) )

       We  have  put the pattern into parentheses, and caused the recursion to
       refer to them instead of the whole pattern. In a larger pattern,  keep-
       ing  track  of parenthesis numbers can be tricky. It may be more conve-
       nient to use named parentheses instead. For this, PCRE uses  (?P>name),
       which  is  an  extension  to the Python syntax that PCRE uses for named
       parentheses (Perl does not provide named parentheses). We could rewrite
       the above example as follows:

         (?P<pn> \( ( (?>[^()]+) | (?P>pn) )* \) )

       This  particular example pattern contains nested unlimited repeats, and
       so the use of atomic grouping for matching strings  of  non-parentheses
       is  important  when  applying the pattern to strings that do not match.
       For example, when this pattern is applied to

         (aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa()

       it yields "no match" quickly. However, if atomic grouping is not  used,
       the  match  runs  for a very long time indeed because there are so many
       different ways the + and * repeats can carve up the  subject,  and  all
       have to be tested before failure can be reported.

       At the end of a match, the values set for any capturing subpatterns are
       those from the outermost level of the recursion at which the subpattern
       value  is  set.   If  you want to obtain intermediate values, a callout
       function can be used (see below and the pcrecallout documentation).  If
       the pattern above is matched against

         (ab(cd)ef)

       the  value  for  the  capturing  parentheses is "ef", which is the last
       value taken on at the top level. If additional parentheses  are  added,
       giving

         \( ( ( (?>[^()]+) | (?R) )* ) \)
            ^                        ^
            ^                        ^

       the  string  they  capture is "ab(cd)ef", the contents of the top level
       parentheses. If there are more than 15 capturing parentheses in a  pat-
       tern, PCRE has to obtain extra memory to store data during a recursion,
       which it does by using pcre_malloc, freeing  it  via  pcre_free  after-
       wards.  If  no  memory  can  be  obtained,  the  match  fails  with the
       PCRE_ERROR_NOMEMORY error.

       Do not confuse the (?R) item with the condition (R),  which  tests  for
       recursion.   Consider  this pattern, which matches text in angle brack-
       ets, allowing for arbitrary nesting. Only digits are allowed in  nested
       brackets  (that is, when recursing), whereas any characters are permit-
       ted at the outer level.

         < (?: (?(R) \d++  | [^<>]*+) | (?R)) * >

       In this pattern, (?(R) is the start of a conditional  subpattern,  with
       two  different  alternatives for the recursive and non-recursive cases.
       The (?R) item is the actual recursive call.


SUBPATTERNS AS SUBROUTINES

       If the syntax for a recursive subpattern reference (either by number or
       by  name)  is used outside the parentheses to which it refers, it oper-
       ates like a subroutine in a programming language.  An  earlier  example
       pointed out that the pattern

         (sens|respons)e and \1ibility

       matches  "sense and sensibility" and "response and responsibility", but
       not "sense and responsibility". If instead the pattern

         (sens|respons)e and (?1)ibility

       is used, it does match "sense and responsibility" as well as the  other
       two  strings.  Such  references must, however, follow the subpattern to
       which they refer.


CALLOUTS

       Perl has a feature whereby using the sequence (?{...}) causes arbitrary
       Perl  code to be obeyed in the middle of matching a regular expression.
       This makes it possible, amongst other things, to extract different sub-
       strings that match the same pair of parentheses when there is a repeti-
       tion.

       PCRE provides a similar feature, but of course it cannot obey arbitrary
       Perl code. The feature is called "callout". The caller of PCRE provides
       an external function by putting its entry point in the global  variable
       pcre_callout.   By default, this variable contains NULL, which disables
       all calling out.

       Within a regular expression, (?C) indicates the  points  at  which  the
       external  function  is  to be called. If you want to identify different
       callout points, you can put a number less than 256 after the letter  C.
       The  default  value is zero.  For example, this pattern has two callout
       points:

         (?C1)abc(?C2)def

       During matching, when PCRE reaches a callout point (and pcre_callout is
       set),  the  external function is called. It is provided with the number
       of the callout, and, optionally, one item of data  originally  supplied
       by  the  caller of pcre_exec(). The callout function may cause matching
       to backtrack, or to fail altogether.  A  complete  description  of  the
       interface  to the callout function is given in the pcrecallout documen-
       tation.


DIFFERENCES FROM PERL
       This section escribes the differences in the ways that PCRE and Perl
       handle regular expressions. The differences  described  here  are  with
       respect to Perl 5.8.

       1.  PCRE does not have full UTF-8 support. Details of what it does have
       are given in the section on UTF-8 support in the main pcre page.

       2. PCRE does not allow repeat quantifiers on lookahead assertions. Perl
       permits  them,  but they do not mean what you might think. For example,
       (?!a){3} does not assert that the next three characters are not "a". It
       just asserts that the next character is not "a" three times.

       3.  Capturing  subpatterns  that occur inside negative lookahead asser-
       tions are counted, but their entries in the offsets  vector  are  never
       set.  Perl sets its numerical variables from any such patterns that are
       matched before the assertion fails to match something (thereby succeed-
       ing),  but  only  if the negative lookahead assertion contains just one
       branch.

       4. Though binary zero characters are supported in the  subject  string,
       they are not allowed in a pattern string because it is passed as a nor-
       mal C string, terminated by zero. The escape sequence "\0" can be  used
       in the pattern to represent a binary zero.

       5.  The  following Perl escape sequences are not supported: \l, \u, \L,
       \U, \P, \p, \N, and \X. In fact these are implemented by Perl's general
       string-handling and are not part of its pattern matching engine. If any
       of these are encountered by PCRE, an error is generated.

       6. PCRE does support the \Q...\E escape for quoting substrings. Charac-
       ters  in  between  are  treated as literals. This is slightly different
       from Perl in that $ and @ are  also  handled  as  literals  inside  the
       quotes.  In Perl, they cause variable interpolation (but of course PCRE
       does not have variables). Note the following examples:

           Pattern            PCRE matches      Perl matches

           \Qabc$xyz\E        abc$xyz           abc followed by the
                                                  contents of $xyz
           \Qabc\$xyz\E       abc\$xyz          abc\$xyz
           \Qabc\E\$\Qxyz\E   abc$xyz           abc$xyz

       The \Q...\E sequence is recognized both inside  and  outside  character
       classes.

       7. Fairly obviously, PCRE does not support the (?{code}) and (?p{code})
       constructions. However, there is some experimental support  for  recur-
       sive  patterns  using the non-Perl items (?R), (?number) and (?P>name).
       Also, the PCRE "callout" feature allows  an  external  function  to  be
       called during pattern matching.

       8.  There  are some differences that are concerned with the settings of
       captured strings when part of  a  pattern  is  repeated.  For  example,
       matching  "aba"  against  the  pattern  /^(a(b)?)+$/  in Perl leaves $2
       unset, but in PCRE it is set to "b".

       9. PCRE  provides  some  extensions  to  the  Perl  regular  expression
       facilities:

       (a)  Although  lookbehind  assertions  must match fixed length strings,
       each alternative branch of a lookbehind assertion can match a different
       length of string. Perl requires them all to have the same length.

       (b)  If PCRE_DOLLAR_ENDONLY is set and PCRE_MULTILINE is not set, the $
       meta-character matches only at the very end of the string.

       (c) If PCRE_EXTRA is set, a backslash followed by a letter with no spe-
       cial meaning is faulted.

       (d)  If  PCRE_UNGREEDY is set, the greediness of the repetition quanti-
       fiers is inverted, that is, by default they are not greedy, but if fol-
       lowed by a question mark they are.

       (e)  PCRE_ANCHORED  can  be used to force a pattern to be tried only at
       the first matching position in the subject string.

       (f) The PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, and  PCRE_NO_AUTO_CAP-
       TURE options for pcre_exec() have no Perl equivalents.

       (g)  The (?R), (?number), and (?P>name) constructs allows for recursive
       pattern matching (Perl can do  this  using  the  (?p{code})  construct,
       which PCRE cannot support.)

       (h)  PCRE supports named capturing substrings, using the Python syntax.

       (i) PCRE supports the possessive quantifier  "++"  syntax,  taken  from
       Sun's Java package.

       (j) The (R) condition, for testing recursion, is a PCRE extension.

       (k) The callout facility is PCRE-specific.



NOTES
        The \< and \> metacharacters from Henry Spencers package
        are not available in PCRE, but can be emulate with \b,
        as required, also in conjunction with \W or \w.

        In LDMud, backtracks are limited by the EVAL_COST runtime
        limit, to avoid freezing the driver with a match
        like regexp(({"=XX==================="}), "X(.+)+X").

        LDMud doesn't support PCRE callouts.


LIMITATIONS
        There are some size limitations in PCRE but it is hoped that
        they will never in practice be relevant.  The maximum length
        of a compiled pattern is 65539 (sic) bytes.  All  values  in
        repeating  quantifiers  must be less than 65536.  There max-
        imum number of capturing subpatterns is 65535.  There is  no
        limit  to  the  number of non-capturing subpatterns, but the
        maximum depth of nesting of all kinds of parenthesized  sub-
        pattern,  including  capturing  subpatterns, assertions, and
        other types of subpattern, is 200.

        The maximum length of a subject string is the largest  posi-
        tive number that an integer variable can hold. However, PCRE
        uses recursion to handle subpatterns and indefinite  repeti-
        tion.  This  means  that the available stack space may limit
        the size of a subject string that can be processed  by  cer-
        tain patterns.


AUTHOR
        Philip Hazel <ph10@cam.ac.uk>
        University Computing Service,
        New Museums Site,
        Cambridge CB2 3QG, England.
        Phone: +44 1223 334714

SEE ALSO
        regexp(C), hsregexp(C)