/[pcre]/code/trunk/doc/pcre.txt

Diff of /code/trunk/doc/pcre.txt

Parent Directory | Revision Log | View Patch Patch

-revision 123 by ph10,
Mon Mar 12 15:19:06 2007 UTC
+revision 654 by ph10,
Tue Aug  2 11:00:40 2011 UTC
 Line 2
  This file contains a concatenation of the PCRE man pages, converted to plain
  text format for ease of searching with a text editor, or for use on systems
  that do not have a man page processor. The small individual files that give
- synopses of each function in the library have not been included. There are
+ synopses of each function in the library have not been included. Neither has
- separate text files for the pcregrep and pcretest commands.
+ the pcredemo program. There are separate text files for the pcregrep and
+ pcretest commands.
  -----------------------------------------------------------------------------
-Line 18 
 INTRODUCTION
+Line 19 
 INTRODUCTION
         The  PCRE  library is a set of functions that implement regular expres-
         sion pattern matching using the same syntax and semantics as Perl, with
-        just  a  few differences. (Certain features that appeared in Python and
+        just  a few differences. Some features that appeared in Python and PCRE
-        PCRE before they appeared in Perl are also available using  the  Python
+        before they appeared in Perl are also available using the  Python  syn-
-        syntax.)
+        tax,  there  is  some  support for one or two .NET and Oniguruma syntax
+        items, and there is an option for requesting some  minor  changes  that
-        The  current  implementation of PCRE (release 7.x) corresponds approxi-
+        give better JavaScript compatibility.
-        mately with Perl 5.10, including support for UTF-8 encoded strings  and
-        Unicode general category properties. However, UTF-8 and Unicode support
+        The  current implementation of PCRE corresponds approximately with Perl
-        has to be explicitly enabled; it is not the default. The Unicode tables
+.12, including support for UTF-8 encoded strings and  Unicode  general
-        correspond to Unicode release 5.0.0.
+        category  properties.  However,  UTF-8  and  Unicode  support has to be
+        explicitly enabled; it is not the default. The  Unicode  tables  corre-
+        spond to Unicode release 6.0.0.
         In  addition to the Perl-compatible matching function, PCRE contains an
-        alternative matching function that matches the same  compiled  patterns
+        alternative function that matches the same compiled patterns in a  dif-
-        in  a different way. In certain circumstances, the alternative function
+        ferent way. In certain circumstances, the alternative function has some
-        has some advantages. For a discussion of the two  matching  algorithms,
+        advantages.  For a discussion of the two matching algorithms,  see  the
-        see the pcrematching page.
+        pcrematching page.
         PCRE  is  written  in C and released as a C library. A number of people
         have written wrappers and interfaces of various kinds.  In  particular,
-Line 45 
 INTRODUCTION
+Line 48 
 INTRODUCTION
         Details of exactly which Perl regular expression features are  and  are
         not supported by PCRE are given in separate documents. See the pcrepat-
-        tern and pcrecompat pages.
+        tern and pcrecompat pages. There is a syntax summary in the  pcresyntax
+        page.
-        Some features of PCRE can be included, excluded, or  changed  when  the
+        Some  features  of  PCRE can be included, excluded, or changed when the
-        library  is  built.  The pcre_config() function makes it possible for a
+        library is built. The pcre_config() function makes it  possible  for  a
-        client to discover which features are  available.  The  features  them-
+        client  to  discover  which  features are available. The features them-
-        selves  are described in the pcrebuild page. Documentation about build-
+        selves are described in the pcrebuild page. Documentation about  build-
-        ing PCRE for various operating systems can be found in the README  file
+        ing  PCRE  for various operating systems can be found in the README and
-        in the source distribution.
+        NON-UNIX-USE files in the source distribution.
-        The  library  contains  a number of undocumented internal functions and
+        The library contains a number of undocumented  internal  functions  and
-        data tables that are used by more than one  of  the  exported  external
+        data  tables  that  are  used by more than one of the exported external
-        functions,  but  which  are  not  intended for use by external callers.
+        functions, but which are not intended  for  use  by  external  callers.
-        Their names all begin with "_pcre_", which hopefully will  not  provoke
+        Their  names  all begin with "_pcre_", which hopefully will not provoke
         any name clashes. In some environments, it is possible to control which
-        external symbols are exported when a shared library is  built,  and  in
+        external  symbols  are  exported when a shared library is built, and in
         these cases the undocumented symbols are not exported.
  USER DOCUMENTATION
-        The  user  documentation  for PCRE comprises a number of different sec-
+        The user documentation for PCRE comprises a number  of  different  sec-
-        tions. In the "man" format, each of these is a separate "man page".  In
+        tions.  In the "man" format, each of these is a separate "man page". In
-        the  HTML  format, each is a separate page, linked from the index page.
+        the HTML format, each is a separate page, linked from the  index  page.
-        In the plain text format, all the sections are concatenated,  for  ease
+        In  the  plain  text format, all the sections, except the pcredemo sec-
-        of searching. The sections are as follows:
+        tion, are concatenated, for ease of searching. The sections are as fol-
+        lows:
           pcre              this document
+          pcre-config       show PCRE installation configuration information
           pcreapi           details of PCRE's native C API
           pcrebuild         options for building PCRE
           pcrecallout       details of the callout feature
           pcrecompat        discussion of Perl compatibility
           pcrecpp           details of the C++ wrapper
+          pcredemo          a demonstration C program that uses PCRE
           pcregrep          description of the pcregrep command
           pcrematching      discussion of the two matching algorithms
           pcrepartial       details of the partial matching facility
-Line 85 
 USER DOCUMENTATION
+Line 92 
 USER DOCUMENTATION
           pcreperform       discussion of performance issues
           pcreposix         the POSIX-compatible C API
           pcreprecompile    details of saving and re-using precompiled patterns
-          pcresample        discussion of the sample program
+          pcresample        discussion of the pcredemo program
           pcrestack         discussion of stack usage
+          pcresyntax        quick syntax reference
           pcretest          description of the pcretest testing command
-        In addition, in the "man" and HTML formats, there is a short  page  for
+        In  addition,  in the "man" and HTML formats, there is a short page for
         each C library function, listing its arguments and results.
  LIMITATIONS
-        There  are some size limitations in PCRE but it is hoped that they will
+        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  if  PCRE
+        The  maximum  length of a compiled pattern is 65539 (sic) bytes if PCRE
         is compiled with the default internal linkage size of 2. If you want to
-        process regular expressions that are truly enormous,  you  can  compile
+        process  regular  expressions  that are truly enormous, you can compile
-        PCRE  with  an  internal linkage size of 3 or 4 (see the README file in
+        PCRE with an internal linkage size of 3 or 4 (see the  README  file  in
-        the source distribution and the pcrebuild documentation  for  details).
+        the  source  distribution and the pcrebuild documentation for details).
-        In  these  cases the limit is substantially larger.  However, the speed
+        In these cases the limit is substantially larger.  However,  the  speed
         of execution is slower.
-        All values in repeating quantifiers must be less than 65536. The  maxi-
+        All values in repeating quantifiers must be less than 65536.
-        mum  compiled  length  of  subpattern  with an explicit repeat count is
-bytes. The maximum number of capturing subpatterns is 65535.
         There is no limit to the number of parenthesized subpatterns, but there
         can be no more than 65535 capturing subpatterns.
-Line 116 
 LIMITATIONS
+Line 122 
 LIMITATIONS
         The maximum length of name for a named subpattern is 32 characters, and
         the maximum number of named subpatterns is 10000.
-        The maximum length of a subject string is the largest  positive  number
+        The  maximum  length of a subject string is the largest positive number
-        that  an integer variable can hold. However, when using the traditional
+        that an integer variable can hold. However, when using the  traditional
         matching function, PCRE uses recursion to handle subpatterns and indef-
-        inite  repetition.  This means that the available stack space may limit
+        inite repetition.  This means that the available stack space may  limit
         the size of a subject string that can be processed by certain patterns.
         For a discussion of stack issues, see the pcrestack documentation.
  UTF-8 AND UNICODE PROPERTY SUPPORT
-        From  release  3.3,  PCRE  has  had  some support for character strings
+        From release 3.3, PCRE has  had  some  support  for  character  strings
-        encoded in the UTF-8 format. For release 4.0 this was greatly  extended
+        encoded  in the UTF-8 format. For release 4.0 this was greatly extended
-        to  cover  most common requirements, and in release 5.0 additional sup-
+        to cover most common requirements, and in release 5.0  additional  sup-
         port for Unicode general category properties was added.
-        In order process UTF-8 strings, you must build PCRE  to  include  UTF-8
+        In  order  process  UTF-8 strings, you must build PCRE to include UTF-8
-        support  in  the  code,  and, in addition, you must call pcre_compile()
+        support in the code, and, in addition,  you  must  call  pcre_compile()
-        with the PCRE_UTF8 option flag. When you do this, both the pattern  and
+        with  the  PCRE_UTF8  option  flag,  or the pattern must start with the
-        any  subject  strings  that are matched against it are treated as UTF-8
+        sequence (*UTF8). When either of these is the case,  both  the  pattern
-        strings instead of just strings of bytes.
+        and  any  subject  strings  that  are matched against it are treated as
+        UTF-8 strings instead of strings of 1-byte characters.
         If you compile PCRE with UTF-8 support, but do not use it at run  time,
         the  library will be a bit bigger, but the additional run time overhead
-Line 154 
 UTF-8 AND UNICODE PROPERTY SUPPORT
+Line 161 
 UTF-8 AND UNICODE PROPERTY SUPPORT
         optionally be prefixed by "Is", for compatibility with Perl  5.6.  PCRE
         does not support this.
-        The following comments apply when PCRE is running in UTF-8 mode:
+    Validity of UTF-8 strings
+        When  you  set  the  PCRE_UTF8 flag, the strings passed as patterns and
+        subjects are (by default) checked for validity on entry to the relevant
+        functions.  From  release 7.3 of PCRE, the check is according the rules
+        of RFC 3629, which are themselves derived from the  Unicode  specifica-
+        tion.  Earlier  releases  of PCRE followed the rules of RFC 2279, which
+        allows the full range of 31-bit values (0 to 0x7FFFFFFF).  The  current
+        check allows only values in the range U+0 to U+10FFFF, excluding U+D800
+        to U+DFFF.
+        The excluded code points are the "Low Surrogate Area"  of  Unicode,  of
+        which  the Unicode Standard says this: "The Low Surrogate Area does not
+        contain any  character  assignments,  consequently  no  character  code
+        charts or namelists are provided for this area. Surrogates are reserved
+        for use with UTF-16 and then must be used in pairs."  The  code  points
+        that  are  encoded  by  UTF-16  pairs are available as independent code
+        points in the UTF-8 encoding. (In  other  words,  the  whole  surrogate
+        thing is a fudge for UTF-16 which unfortunately messes up UTF-8.)
+        If an invalid UTF-8 string is passed to PCRE, an error return is given.
+        At compile time, the only additional information is the offset  to  the
+        first byte of the failing character. The runtime functions (pcre_exec()
+        and pcre_dfa_exec()), pass back this information  as  well  as  a  more
+        detailed  reason  code if the caller has provided memory in which to do
+        this.
+        In some situations, you may already know that your strings  are  valid,
+        and  therefore  want  to  skip these checks in order to improve perfor-
+        mance. If you set the PCRE_NO_UTF8_CHECK flag at compile time or at run
+        time,  PCRE  assumes  that  the pattern or subject it is given (respec-
+        tively) contains only valid UTF-8 codes. In  this  case,  it  does  not
+        diagnose an invalid UTF-8 string.
+        If  you  pass  an  invalid UTF-8 string when PCRE_NO_UTF8_CHECK is set,
+        what happens depends on why the string is invalid. If the  string  con-
+        forms to the "old" definition of UTF-8 (RFC 2279), it is processed as a
+        string of characters in the range 0  to  0x7FFFFFFF.  In  other  words,
+        apart from the initial validity test, PCRE (when in UTF-8 mode) handles
+        strings according to the more liberal rules of RFC  2279.  However,  if
+        the  string does not even conform to RFC 2279, the result is undefined.
+        Your program may crash.
+        If you want to process strings  of  values  in  the  full  range  0  to
+x7FFFFFFF,  encoded in a UTF-8-like manner as per the old RFC, you can
+        set PCRE_NO_UTF8_CHECK to bypass the more restrictive test. However, in
+        this situation, you will have to apply your own validity check.
-.  When you set the PCRE_UTF8 flag, the strings passed as patterns and
+    General comments about UTF-8 mode
-        subjects are checked for validity on entry to the  relevant  functions.
-        If an invalid UTF-8 string is passed, an error return is given. In some
-        situations, you may already know  that  your  strings  are  valid,  and
-        therefore want to skip these checks in order to improve performance. If
-        you set the PCRE_NO_UTF8_CHECK flag at compile time  or  at  run  time,
-        PCRE  assumes  that  the  pattern or subject it is given (respectively)
-        contains only valid UTF-8 codes. In this case, it does not diagnose  an
-        invalid  UTF-8 string. If you pass an invalid UTF-8 string to PCRE when
-        PCRE_NO_UTF8_CHECK is set, the results are undefined. Your program  may
-        crash.
 .  An  unbraced  hexadecimal  escape sequence (such as \xb3) matches a
         two-byte UTF-8 character if the value is greater than 127.
 . Octal numbers up to \777 are recognized, and  match  two-byte  UTF-8
         characters for values greater than \177.
 .  Repeat quantifiers apply to complete UTF-8 characters, not to indi-
         vidual bytes, for example: \x{100}{3}.
 . The dot metacharacter matches one UTF-8 character instead of a  sin-
         gle byte.
 .  The  escape sequence \C can be used to match a single byte in UTF-8
         mode, but its use can lead to some strange effects.  This  facility  is
         not available in the alternative matching function, pcre_dfa_exec().
 .  The  character escapes \b, \B, \d, \D, \s, \S, \w, and \W correctly
-        test characters of any code value, but the characters that PCRE  recog-
+        test characters of any code value, but, by default, the characters that
-        nizes  as  digits,  spaces,  or  word characters remain the same set as
+        PCRE  recognizes  as digits, spaces, or word characters remain the same
-        before, all with values less than 256. This remains true even when PCRE
+        set as before, all with values less than 256. This  remains  true  even
-        includes  Unicode  property support, because to do otherwise would slow
+        when  PCRE  is built to include Unicode property support, because to do
-        down PCRE in many common cases. If you really want to test for a  wider
+        otherwise would slow down PCRE in many common cases. Note in particular
-        sense  of,  say,  "digit",  you must use Unicode property tests such as
+        that this applies to \b and \B, because they are defined in terms of \w
-        \p{Nd}.
+        and \W. If you really want to test for a wider sense of, say,  "digit",
+        you  can  use  explicit Unicode property tests such as \p{Nd}. Alterna-
-. Similarly, characters that match the POSIX named  character  classes
+        tively, if you set the PCRE_UCP option,  the  way  that  the  character
-        are all low-valued characters.
+        escapes  work  is changed so that Unicode properties are used to deter-
+        mine which characters match. There are more details in the  section  on
-.  Case-insensitive  matching  applies only to characters whose values
+        generic character types in the pcrepattern documentation.
-        are less than 128, unless PCRE is built with Unicode property  support.
-        Even  when  Unicode  property support is available, PCRE still uses its
+.  Similarly,  characters that match the POSIX named character classes
-        own character tables when checking the case of  low-valued  characters,
+        are all low-valued characters, unless the PCRE_UCP option is set.
-        so  as not to degrade performance.  The Unicode property information is
-        used only for characters with higher values. Even when Unicode property
+. However, the horizontal and  vertical  whitespace  matching  escapes
-        support is available, PCRE supports case-insensitive matching only when
+        (\h,  \H,  \v, and \V) do match all the appropriate Unicode characters,
-        there is a one-to-one mapping between a letter's  cases.  There  are  a
+        whether or not PCRE_UCP is set.
-        small  number  of  many-to-one  mappings in Unicode; these are not sup-
-        ported by PCRE.
+. Case-insensitive matching applies only to  characters  whose  values
+        are  less than 128, unless PCRE is built with Unicode property support.
+        Even when Unicode property support is available, PCRE  still  uses  its
+        own  character  tables when checking the case of low-valued characters,
+        so as not to degrade performance.  The Unicode property information  is
+        used only for characters with higher values. Furthermore, PCRE supports
+        case-insensitive matching only  when  there  is  a  one-to-one  mapping
+        between  a letter's cases. There are a small number of many-to-one map-
+        pings in Unicode; these are not supported by PCRE.
  AUTHOR
-Line 215 
 AUTHOR
+Line 266 
 AUTHOR
         Cambridge CB2 3QH, England.
         Putting an actual email address here seems to have been a spam  magnet,
-        so I've taken it away. If you want to email me, use my initial and sur-
+        so  I've  taken  it away. If you want to email me, use my two initials,
-        name, separated by a dot, at the domain ucs.cam.ac.uk.
+        followed by the two digits 10, at the domain cam.ac.uk.
  REVISION
-        Last updated: 06 March 2007
+        Last updated: 07 May 2011
-        Copyright (c) 1997-2007 University of Cambridge.
+        Copyright (c) 1997-2011 University of Cambridge.
  ------------------------------------------------------------------------------
-Line 236 
 NAME
+Line 287 
 NAME
  PCRE BUILD-TIME OPTIONS
         This  document  describes  the  optional  features  of PCRE that can be
-        selected when the library is compiled. They are all selected, or  dese-
+        selected when the library is compiled. It assumes use of the  configure
-        lected, by providing options to the configure script that is run before
+        script,  where the optional features are selected or deselected by pro-
-        the make command. The complete list of  options  for  configure  (which
+        viding options to configure before running the make  command.  However,
-        includes  the  standard  ones such as the selection of the installation
+        the  same  options  can be selected in both Unix-like and non-Unix-like
-        directory) can be obtained by running
+        environments using the GUI facility of cmake-gui if you are using CMake
+        instead of configure to build PCRE.
+        There  is  a  lot more information about building PCRE in non-Unix-like
+        environments in the file called NON_UNIX_USE, which is part of the PCRE
+        distribution.  You  should consult this file as well as the README file
+        if you are building in a non-Unix-like environment.
+        The complete list of options for configure (which includes the standard
+        ones  such  as  the  selection  of  the  installation directory) can be
+        obtained by running
           ./configure --help
-        The following sections describe certain options whose names begin  with
+        The following sections include  descriptions  of  options  whose  names
-        --enable  or  --disable. These settings specify changes to the defaults
+        begin with --enable or --disable. These settings specify changes to the
-        for the configure command. Because of the  way  that  configure  works,
+        defaults for the configure command. Because of the way  that  configure
-        --enable  and  --disable  always  come  in  pairs, so the complementary
+        works,  --enable  and --disable always come in pairs, so the complemen-
-        option always exists as well, but as it specifies the  default,  it  is
+        tary option always exists as well, but as it specifies the default,  it
-        not described.
+        is not described.
+ BUILDING SHARED AND STATIC LIBRARIES
+        The  PCRE building process uses libtool to build both shared and static
+        Unix libraries by default. You can suppress one of these by adding  one
+        of
+          --disable-shared
+          --disable-static
+        to the configure command, as required.
  C++ SUPPORT
-Line 265 
 C++ SUPPORT
+Line 338 
 C++ SUPPORT
  UTF-8 SUPPORT
-        To build PCRE with support for UTF-8 character strings, add
+        To build PCRE with support for UTF-8 Unicode character strings, add
           --enable-utf8
         to  the  configure  command.  Of  itself, this does not make PCRE treat
         strings as UTF-8. As well as compiling PCRE with this option, you  also
         have  have to set the PCRE_UTF8 option when you call the pcre_compile()
-        function.
+        or pcre_compile2() functions.
+        If you set --enable-utf8 when compiling in an EBCDIC environment,  PCRE
+        expects its input to be either ASCII or UTF-8 (depending on the runtime
+        option). It is not possible to support both EBCDIC and UTF-8  codes  in
+        the  same  version  of  the  library.  Consequently,  --enable-utf8 and
+        --enable-ebcdic are mutually exclusive.
  UNICODE CHARACTER PROPERTY SUPPORT
-Line 288 
 UNICODE CHARACTER PROPERTY SUPPORT
+Line 367 
 UNICODE CHARACTER PROPERTY SUPPORT
         to the configure command. This implies UTF-8 support, even if you  have
         not explicitly requested it.
-        Including  Unicode  property  support  adds around 90K of tables to the
+        Including  Unicode  property  support  adds around 30K of tables to the
-        PCRE library, approximately doubling its size. Only the  general  cate-
+        PCRE library. Only the general category properties such as  Lu  and  Nd
-        gory  properties  such as Lu and Nd are supported. Details are given in
+        are supported. Details are given in the pcrepattern documentation.
-        the pcrepattern documentation.
  CODE VALUE OF NEWLINE
-        By default, PCRE interprets character 10 (linefeed, LF)  as  indicating
+        By  default,  PCRE interprets the linefeed (LF) character as indicating
-        the  end  of  a line. This is the normal newline character on Unix-like
+        the end of a line. This is the normal newline  character  on  Unix-like
-        systems. You can compile PCRE to use character 13 (carriage return, CR)
+        systems.  You  can compile PCRE to use carriage return (CR) instead, by
-        instead, by adding
+        adding
           --enable-newline-is-cr
-        to  the  configure  command.  There  is  also  a --enable-newline-is-lf
+        to the  configure  command.  There  is  also  a  --enable-newline-is-lf
         option, which explicitly specifies linefeed as the newline character.
         Alternatively, you can specify that line endings are to be indicated by
-Line 313 
 CODE VALUE OF NEWLINE
+Line 391 
 CODE VALUE OF NEWLINE
         to the configure command. There is a fourth option, specified by
+          --enable-newline-is-anycrlf
+        which causes PCRE to recognize any of the three sequences  CR,  LF,  or
+        CRLF as indicating a line ending. Finally, a fifth option, specified by
           --enable-newline-is-any
-        which causes PCRE to recognize any Unicode newline sequence.
+        causes PCRE to recognize any Unicode newline sequence.
         Whatever  line  ending convention is selected when PCRE is built can be
         overridden when the library functions are called. At build time  it  is
         conventional to use the standard for your operating system.
- BUILDING SHARED AND STATIC LIBRARIES
+ WHAT \R MATCHES
-        The  PCRE building process uses libtool to build both shared and static
+        By  default,  the  sequence \R in a pattern matches any Unicode newline
-        Unix libraries by default. You can suppress one of these by adding  one
+        sequence, whatever has been selected as the line  ending  sequence.  If
-        of
+        you specify
-          --disable-shared
+          --enable-bsr-anycrlf
-          --disable-static
-        to the configure command, as required.
+        the  default  is changed so that \R matches only CR, LF, or CRLF. What-
+        ever is selected when PCRE is built can be overridden when the  library
+        functions are called.
  POSIX MALLOC USAGE
-Line 357 
 HANDLING VERY LARGE PATTERNS
+Line 441 
 HANDLING VERY LARGE PATTERNS
         nation metacharacter). By default, two-byte values are used  for  these
         offsets,  leading  to  a  maximum size for a compiled pattern of around
 K. This is sufficient to handle all but the most  gigantic  patterns.
-        Nevertheless,  some  people do want to process enormous patterns, so it
+        Nevertheless,  some  people do want to process truyl enormous patterns,
-        is possible to compile PCRE to use three-byte or four-byte  offsets  by
+        so it is possible to compile PCRE to use three-byte or  four-byte  off-
-        adding a setting such as
+        sets by adding a setting such as
           --with-link-size=3
-Line 367 
 HANDLING VERY LARGE PATTERNS
+Line 451 
 HANDLING VERY LARGE PATTERNS
         longer offsets slows down the operation of PCRE because it has to  load
         additional bytes when handling them.
-        If  you  build  PCRE with an increased link size, test 2 (and test 5 if
-        you are using UTF-8) will fail. Part of the output of these tests is  a
-        representation  of the compiled pattern, and this changes with the link
-        size.
  AVOIDING EXCESSIVE STACK USAGE
         When matching with the pcre_exec() function, PCRE implements backtrack-
-        ing  by  making recursive calls to an internal function called match().
+        ing by making recursive calls to an internal function  called  match().
-        In environments where the size of the stack is limited,  this  can  se-
+        In  environments  where  the size of the stack is limited, this can se-
-        verely  limit  PCRE's operation. (The Unix environment does not usually
+        verely limit PCRE's operation. (The Unix environment does  not  usually
         suffer from this problem, but it may sometimes be necessary to increase
-        the  maximum  stack size.  There is a discussion in the pcrestack docu-
+        the maximum stack size.  There is a discussion in the  pcrestack  docu-
-        mentation.) An alternative approach to recursion that uses memory  from
+        mentation.)  An alternative approach to recursion that uses memory from
-        the  heap  to remember data, instead of using recursive function calls,
+        the heap to remember data, instead of using recursive  function  calls,
-        has been implemented to work round the problem of limited  stack  size.
+        has  been  implemented to work round the problem of limited stack size.
         If you want to build a version of PCRE that works this way, add
           --disable-stack-for-recursion
-        to  the  configure  command. With this configuration, PCRE will use the
+        to the configure command. With this configuration, PCRE  will  use  the
-        pcre_stack_malloc and pcre_stack_free variables to call memory  manage-
+        pcre_stack_malloc  and pcre_stack_free variables to call memory manage-
-        ment  functions.  Separate  functions are provided because the usage is
+        ment functions. By default these point to malloc() and free(), but  you
-        very predictable: the block sizes requested are always  the  same,  and
+        can replace the pointers so that your own functions are used instead.
-        the  blocks  are always freed in reverse order. A calling program might
-        be able to implement optimized functions that perform better  than  the
+        Separate  functions  are  provided  rather  than  using pcre_malloc and
-        standard  malloc()  and  free()  functions.  PCRE  runs noticeably more
+        pcre_free because the  usage  is  very  predictable:  the  block  sizes
-        slowly when built in this way. This option affects only the pcre_exec()
+        requested  are  always  the  same,  and  the blocks are always freed in
-        function; it is not relevant for the the pcre_dfa_exec() function.
+        reverse order. A calling program might be able to  implement  optimized
+        functions  that  perform  better  than  malloc()  and free(). PCRE runs
+        noticeably more slowly when built in this way. This option affects only
+        the pcre_exec() function; it is not relevant for pcre_dfa_exec().
  LIMITING PCRE RESOURCE USAGE
-Line 429 
 LIMITING PCRE RESOURCE USAGE
+Line 511 
 LIMITING PCRE RESOURCE USAGE
         time.
+ CREATING CHARACTER TABLES AT BUILD TIME
+        PCRE uses fixed tables for processing characters whose code values  are
+        less  than 256. By default, PCRE is built with a set of tables that are
+        distributed in the file pcre_chartables.c.dist. These  tables  are  for
+        ASCII codes only. If you add
+          --enable-rebuild-chartables
+        to  the  configure  command, the distributed tables are no longer used.
+        Instead, a program called dftables is compiled and  run.  This  outputs
+        the source for new set of tables, created in the default locale of your
+        C runtime system. (This method of replacing the tables does not work if
+        you  are cross compiling, because dftables is run on the local host. If
+        you need to create alternative tables when cross  compiling,  you  will
+        have to do so "by hand".)
  USING EBCDIC CODE
-        PCRE assumes by default that it will run in an  environment  where  the
+        PCRE  assumes  by  default that it will run in an environment where the
-        character  code  is  ASCII  (or Unicode, which is a superset of ASCII).
+        character code is ASCII (or Unicode, which is  a  superset  of  ASCII).
-        PCRE can, however, be compiled to  run  in  an  EBCDIC  environment  by
+        This  is  the  case for most computer operating systems. PCRE can, how-
-        adding
+        ever, be compiled to run in an EBCDIC environment by adding
           --enable-ebcdic
-        to the configure command.
+        to the configure command. This setting implies --enable-rebuild-charta-
+        bles.  You  should  only  use  it if you know that you are in an EBCDIC
+        environment (for example,  an  IBM  mainframe  operating  system).  The
+        --enable-ebcdic option is incompatible with --enable-utf8.
+ PCREGREP OPTIONS FOR COMPRESSED FILE SUPPORT
+        By default, pcregrep reads all files as plain text. You can build it so
+        that it recognizes files whose names end in .gz or .bz2, and reads them
+        with libz or libbz2, respectively, by adding one or both of
+          --enable-pcregrep-libz
+          --enable-pcregrep-libbz2
+        to the configure command. These options naturally require that the rel-
+        evant libraries are installed on your system. Configuration  will  fail
+        if they are not.
+ PCREGREP BUFFER SIZE
+        pcregrep  uses  an internal buffer to hold a "window" on the file it is
+        scanning, in order to be able to output "before" and "after" lines when
+        it  finds  a match. The size of the buffer is controlled by a parameter
+        whose default value is 20K. The buffer itself is three times this size,
+        but because of the way it is used for holding "before" lines, the long-
+        est line that is guaranteed to be processable is  the  parameter  size.
+        You can change the default parameter value by adding, for example,
+          --with-pcregrep-bufsize=50K
+        to the configure command. The caller of pcregrep can, however, override
+        this value by specifying a run-time option.
+ PCRETEST OPTION FOR LIBREADLINE SUPPORT
+        If you add
+          --enable-pcretest-libreadline
+        to the configure command,  pcretest  is  linked  with  the  libreadline
+        library,  and  when its input is from a terminal, it reads it using the
+        readline() function. This provides line-editing and history facilities.
+        Note that libreadline is GPL-licensed, so if you distribute a binary of
+        pcretest linked in this way, there may be licensing issues.
+        Setting this option causes the -lreadline option to  be  added  to  the
+        pcretest  build.  In many operating environments with a sytem-installed
+        libreadline this is sufficient. However, in some environments (e.g.  if
+        an  unmodified  distribution version of readline is in use), some extra
+        configuration may be necessary. The INSTALL file for  libreadline  says
+        this:
+          "Readline uses the termcap functions, but does not link with the
+          termcap or curses library itself, allowing applications which link
+          with readline the to choose an appropriate library."
+        If  your environment has not been set up so that an appropriate library
+        is automatically included, you may need to add something like
+          LIBS="-ncurses"
+        immediately before the configure command.
  SEE ALSO
-Line 455 
 AUTHOR
+Line 619 
 AUTHOR
  REVISION
-        Last updated: 06 March 2007
+        Last updated: 02 August 2011
-        Copyright (c) 1997-2007 University of Cambridge.
+        Copyright (c) 1997-2011 University of Cambridge.
  ------------------------------------------------------------------------------
-Line 508 
 REGULAR EXPRESSIONS AS TREES
+Line 672 
 REGULAR EXPRESSIONS AS TREES
  THE STANDARD MATCHING ALGORITHM
-        In the terminology of Jeffrey Friedl's book Mastering  Regular  Expres-
+        In the terminology of Jeffrey Friedl's book "Mastering Regular  Expres-
-        sions,  the  standard  algorithm  is  an "NFA algorithm". It conducts a
+        sions",  the  standard  algorithm  is an "NFA algorithm". It conducts a
         depth-first search of the pattern tree. That is, it  proceeds  along  a
         single path through the tree, checking that the subject matches what is
         required. When there is a mismatch, the algorithm  tries  any  alterna-
-Line 543 
 THE ALTERNATIVE MATCHING ALGORITHM
+Line 707 
 THE ALTERNATIVE MATCHING ALGORITHM
         though  it is not implemented as a traditional finite state machine (it
         keeps multiple states active simultaneously).
+        Although the general principle of this matching algorithm  is  that  it
+        scans  the subject string only once, without backtracking, there is one
+        exception: when a lookaround assertion is encountered,  the  characters
+        following  or  preceding  the  current  point  have to be independently
+        inspected.
         The scan continues until either the end of the subject is  reached,  or
         there  are  no more unterminated paths. At this point, terminated paths
         represent the different matching possibilities (if there are none,  the
         match  has  failed).   Thus,  if there is more than one possible match,
         this algorithm finds all of them, and in particular, it finds the long-
-        est.  In PCRE, there is an option to stop the algorithm after the first
+        est.  The  matches are returned in decreasing order of length. There is
-        match (which is necessarily the shortest) has been found.
+        an option to stop the algorithm after the first match (which is  neces-
+        sarily the shortest) is found.
         Note that all the matches that are found start at the same point in the
         subject. If the pattern
-          cat(er(pillar)?)
+          cat(er(pillar)?)?
-        is  matched  against the string "the caterpillar catchment", the result
+        is matched against the string "the caterpillar catchment",  the  result
-        will be the three strings "cat", "cater", and "caterpillar" that  start
+        will  be the three strings "caterpillar", "cater", and "cat" that start
-        at the fourth character of the subject. The algorithm does not automat-
+        at the fifth character of the subject. The algorithm does not automati-
-        ically move on to find matches that start at later positions.
+        cally move on to find matches that start at later positions.
         There are a number of features of PCRE regular expressions that are not
         supported by the alternative matching algorithm. They are as follows:
-.  Because  the  algorithm  finds  all possible matches, the greedy or
+. Because the algorithm finds all  possible  matches,  the  greedy  or
-        ungreedy nature of repetition quantifiers is not relevant.  Greedy  and
+        ungreedy  nature  of repetition quantifiers is not relevant. Greedy and
         ungreedy quantifiers are treated in exactly the same way. However, pos-
-        sessive quantifiers can make a difference when what follows could  also
+        sessive  quantifiers can make a difference when what follows could also
         match what is quantified, for example in a pattern like this:
           ^a++\w!
-        This  pattern matches "aaab!" but not "aaa!", which would be matched by
+        This pattern matches "aaab!" but not "aaa!", which would be matched  by
-        a non-possessive quantifier. Similarly, if an atomic group is  present,
+        a  non-possessive quantifier. Similarly, if an atomic group is present,
-        it  is matched as if it were a standalone pattern at the current point,
+        it is matched as if it were a standalone pattern at the current  point,
-        and the longest match is then "locked in" for the rest of  the  overall
+        and  the  longest match is then "locked in" for the rest of the overall
         pattern.
 . When dealing with multiple paths through the tree simultaneously, it
-        is not straightforward to keep track of  captured  substrings  for  the
+        is  not  straightforward  to  keep track of captured substrings for the
-        different  matching  possibilities,  and  PCRE's implementation of this
+        different matching possibilities, and  PCRE's  implementation  of  this
         algorithm does not attempt to do this. This means that no captured sub-
         strings are available.
-.  Because no substrings are captured, back references within the pat-
+. Because no substrings are captured, back references within the  pat-
         tern are not supported, and cause errors if encountered.
-. For the same reason, conditional expressions that use  a  backrefer-
+.  For  the same reason, conditional expressions that use a backrefer-
-        ence  as  the  condition or test for a specific group recursion are not
+        ence as the condition or test for a specific group  recursion  are  not
         supported.
-. Callouts are supported, but the value of the  capture_top  field  is
+.  Because  many  paths  through the tree may be active, the \K escape
+        sequence, which resets the start of the match when encountered (but may
+        be  on  some  paths  and not on others), is not supported. It causes an
+        error if encountered.
+. Callouts are supported, but the value of the  capture_top  field  is
         always 1, and the value of the capture_last field is always -1.
 .  The \C escape sequence, which (in the standard algorithm) matches a
         single byte, even in UTF-8 mode, is not supported because the  alterna-
         tive  algorithm  moves  through  the  subject string one character at a
         time, for all active paths through the tree.
+. Except for (*FAIL), the backtracking control verbs such as  (*PRUNE)
+        are  not  supported.  (*FAIL)  is supported, and behaves like a failing
+        negative assertion.
  ADVANTAGES OF THE ALTERNATIVE ALGORITHM
-Line 610 
 ADVANTAGES OF THE ALTERNATIVE ALGORITHM
+Line 790 
 ADVANTAGES OF THE ALTERNATIVE ALGORITHM
         more than one match using the standard algorithm, you have to do kludgy
         things with callouts.
-. There is much better support for partial matching. The  restrictions
+. Because the alternative algorithm  scans  the  subject  string  just
-        on  the content of the pattern that apply when using the standard algo-
-        rithm for partial matching do not apply to the  alternative  algorithm.
-        For  non-anchored patterns, the starting position of a partial match is
-        available.
-. Because the alternative algorithm  scans  the  subject  string  just
         once,  and  never  needs to backtrack, it is possible to pass very long
         subject strings to the matching function in  several  pieces,  checking
-        for partial matching each time.
+        for  partial  matching  each time. Although it is possible to do multi-
+        segment matching using the standard algorithm (pcre_exec()), by retain-
+        ing  partially matched substrings, it is more complicated. The pcrepar-
+        tial documentation gives details  of  partial  matching  and  discusses
+        multi-segment matching.
  DISADVANTAGES OF THE ALTERNATIVE ALGORITHM
-Line 645 
 AUTHOR
+Line 823 
 AUTHOR
  REVISION
-        Last updated: 06 March 2007
+        Last updated: 17 November 2010
-        Copyright (c) 1997-2007 University of Cambridge.
+        Copyright (c) 1997-2010 University of Cambridge.
  ------------------------------------------------------------------------------
-Line 753 
 PCRE API OVERVIEW
+Line 931 
 PCRE API OVERVIEW
         bers for the library.  Applications can use these  to  include  support
         for different releases of PCRE.
+        In a Windows environment, if you want to statically link an application
+        program against a non-dll pcre.a  file,  you  must  define  PCRE_STATIC
+        before  including  pcre.h or pcrecpp.h, because otherwise the pcre_mal-
+        loc()   and   pcre_free()   exported   functions   will   be   declared
+        __declspec(dllimport), with unwanted results.
         The   functions   pcre_compile(),  pcre_compile2(),  pcre_study(),  and
         pcre_exec() are used for compiling and matching regular expressions  in
         a  Perl-compatible  manner. A sample program that demonstrates the sim-
         plest way of using them is provided in the file  called  pcredemo.c  in
-        the  source distribution. The pcresample documentation describes how to
+        the PCRE source distribution. A listing of this program is given in the
-        run it.
+        pcredemo documentation, and the pcresample documentation describes  how
+        to compile and run it.
         A second matching function, pcre_dfa_exec(), which is not Perl-compati-
-        ble,  is  also provided. This uses a different algorithm for the match-
+        ble, is also provided. This uses a different algorithm for  the  match-
-        ing. The alternative algorithm finds all possible matches (at  a  given
+        ing.  The  alternative algorithm finds all possible matches (at a given
-        point  in  the subject), and scans the subject just once. However, this
+        point in the subject), and scans the subject just  once  (unless  there
-        algorithm does not return captured substrings. A description of the two
+        are  lookbehind  assertions).  However,  this algorithm does not return
-        matching  algorithms and their advantages and disadvantages is given in
+        captured substrings. A description of the two matching  algorithms  and
-        the pcrematching documentation.
+        their  advantages  and disadvantages is given in the pcrematching docu-
+        mentation.
         In addition to the main compiling and  matching  functions,  there  are
         convenience functions for extracting captured substrings from a subject
-Line 828 
 PCRE API OVERVIEW
+Line 1014 
 PCRE API OVERVIEW
  NEWLINES
-        PCRE  supports four different conventions for indicating line breaks in
+        PCRE  supports five different conventions for indicating line breaks in
         strings: a single CR (carriage return) character, a  single  LF  (line-
-        feed)  character,  the two-character sequence CRLF, or any Unicode new-
+        feed) character, the two-character sequence CRLF, any of the three pre-
-        line sequence.  The Unicode newline sequences are the three  just  men-
+        ceding, or any Unicode newline sequence. The Unicode newline  sequences
-        tioned, plus the single characters VT (vertical tab, U+000B), FF (form-
+        are  the  three just mentioned, plus the single characters VT (vertical
-        feed, U+000C), NEL (next line, U+0085), LS  (line  separator,  U+2028),
+        tab, U+000B), FF (formfeed, U+000C), NEL (next line, U+0085), LS  (line
-        and PS (paragraph separator, U+2029).
+        separator, U+2028), and PS (paragraph separator, U+2029).
         Each  of  the first three conventions is used by at least one operating
         system as its standard newline sequence. When PCRE is built, a  default
-Line 842 
 NEWLINES
+Line 1028 
 NEWLINES
         dard. When PCRE is run, the default can be overridden,  either  when  a
         pattern is compiled, or when it is matched.
+        At compile time, the newline convention can be specified by the options
+        argument of pcre_compile(), or it can be specified by special  text  at
+        the start of the pattern itself; this overrides any other settings. See
+        the pcrepattern page for details of the special character sequences.
         In the PCRE documentation the word "newline" is used to mean "the char-
-        acter or pair of characters that indicate a line break". The choice  of
+        acter  or pair of characters that indicate a line break". The choice of
-        newline  convention  affects  the  handling of the dot, circumflex, and
+        newline convention affects the handling of  the  dot,  circumflex,  and
         dollar metacharacters, the handling of #-comments in /x mode, and, when
-        CRLF  is a recognized line ending sequence, the match position advance-
+        CRLF is a recognized line ending sequence, the match position  advance-
-        ment for a non-anchored pattern. The choice of newline convention  does
+        ment for a non-anchored pattern. There is more detail about this in the
-        not affect the interpretation of the \n or \r escape sequences.
+        section on pcre_exec() options below.
+        The choice of newline convention does not affect the interpretation  of
+        the  \n  or  \r  escape  sequences, nor does it affect what \R matches,
+        which is controlled in a similar way, but by separate options.
  MULTITHREADING
-        The  PCRE  functions  can be used in multi-threading applications, with
+        The PCRE functions can be used in  multi-threading  applications,  with
         the  proviso  that  the  memory  management  functions  pointed  to  by
         pcre_malloc, pcre_free, pcre_stack_malloc, and pcre_stack_free, and the
         callout function pointed to by pcre_callout, are shared by all threads.
-Line 868 
 SAVING PRECOMPILED PATTERNS FOR LATER US
+Line 1063 
 SAVING PRECOMPILED PATTERNS FOR LATER US
         The compiled form of a regular expression can be saved and re-used at a
         later time, possibly by a different program, and even on a  host  other
         than  the  one  on  which  it  was  compiled.  Details are given in the
-        pcreprecompile documentation.
+        pcreprecompile documentation. However, compiling a  regular  expression
+        with  one version of PCRE for use with a different version is not guar-
+        anteed to work and may cause crashes.
  CHECKING BUILD-TIME OPTIONS
-Line 899 
 CHECKING BUILD-TIME OPTIONS
+Line 1096 
 CHECKING BUILD-TIME OPTIONS
         The output is an integer whose value specifies  the  default  character
         sequence  that is recognized as meaning "newline". The four values that
-        are supported are: 10 for LF, 13 for CR, 3338 for CRLF, and -1 for ANY.
+        are supported are: 10 for LF, 13 for CR, 3338 for CRLF, -2 for ANYCRLF,
-        The default should normally be the standard sequence for your operating
+        and  -1  for  ANY.  Though they are derived from ASCII, the same values
-        system.
+        are returned in EBCDIC environments. The default should normally corre-
+        spond to the standard sequence for your operating system.
+          PCRE_CONFIG_BSR
+        The output is an integer whose value indicates what character sequences
+        the \R escape sequence matches by default. A value of 0 means  that  \R
+        matches  any  Unicode  line ending sequence; a value of 1 means that \R
+        matches only CR, LF, or CRLF. The default can be overridden when a pat-
+        tern is compiled or matched.
           PCRE_CONFIG_LINK_SIZE
-        The output is an integer that contains the number  of  bytes  used  for
+        The  output  is  an  integer that contains the number of bytes used for
         internal linkage in compiled regular expressions. The value is 2, 3, or
-. Larger values allow larger regular expressions to  be  compiled,  at
+.  Larger  values  allow larger regular expressions to be compiled, at
-        the  expense  of  slower matching. The default value of 2 is sufficient
+        the expense of slower matching. The default value of  2  is  sufficient
-        for all but the most massive patterns, since  it  allows  the  compiled
+        for  all  but  the  most massive patterns, since it allows the compiled
         pattern to be up to 64K in size.
           PCRE_CONFIG_POSIX_MALLOC_THRESHOLD
-        The  output  is  an integer that contains the threshold above which the
+        The output is an integer that contains the threshold  above  which  the
-        POSIX interface uses malloc() for output vectors. Further  details  are
+        POSIX  interface  uses malloc() for output vectors. Further details are
         given in the pcreposix documentation.
           PCRE_CONFIG_MATCH_LIMIT
-        The output is an integer that gives the default limit for the number of
+        The output is a long integer that gives the default limit for the  num-
-        internal matching function calls in a  pcre_exec()  execution.  Further
+        ber  of  internal  matching  function calls in a pcre_exec() execution.
-        details are given with pcre_exec() below.
+        Further details are given with pcre_exec() below.
           PCRE_CONFIG_MATCH_LIMIT_RECURSION
-        The  output is an integer that gives the default limit for the depth of
+        The output is a long integer that gives the default limit for the depth
-        recursion when calling the internal matching function in a  pcre_exec()
+        of   recursion  when  calling  the  internal  matching  function  in  a
-        execution. Further details are given with pcre_exec() below.
+        pcre_exec() execution.  Further  details  are  given  with  pcre_exec()
+        below.
           PCRE_CONFIG_STACKRECURSE
-Line 955 
 COMPILING A PATTERN
+Line 1162 
 COMPILING A PATTERN
         Either of the functions pcre_compile() or pcre_compile2() can be called
         to compile a pattern into an internal form. The only difference between
         the  two interfaces is that pcre_compile2() has an additional argument,
-        errorcodeptr, via which a numerical error code can be returned.
+        errorcodeptr, via which a numerical error  code  can  be  returned.  To
+        avoid  too  much repetition, we refer just to pcre_compile() below, but
+        the information applies equally to pcre_compile2().
         The pattern is a C string terminated by a binary zero, and is passed in
         the  pattern  argument.  A  pointer to a single block of memory that is
-Line 972 
 COMPILING A PATTERN
+Line 1181 
 COMPILING A PATTERN
         The options argument contains various bit settings that affect the com-
         pilation. It should be zero if no options are required.  The  available
-        options  are  described  below. Some of them, in particular, those that
+        options  are  described  below. Some of them (in particular, those that
-        are compatible with Perl, can also be set and  unset  from  within  the
+        are compatible with Perl, but some others as well) can also be set  and
-        pattern  (see  the  detailed  description in the pcrepattern documenta-
+        unset  from  within  the  pattern  (see the detailed description in the
-        tion). For these options, the contents of the options  argument  speci-
+        pcrepattern documentation). For those options that can be different  in
-        fies  their initial settings at the start of compilation and execution.
+        different  parts  of  the pattern, the contents of the options argument
-        The PCRE_ANCHORED and PCRE_NEWLINE_xxx options can be set at  the  time
+        specifies their settings at the start of compilation and execution. The
-        of matching as well as at compile time.
+        PCRE_ANCHORED,  PCRE_BSR_xxx, PCRE_NEWLINE_xxx, PCRE_NO_UTF8_CHECK, and
+        PCRE_NO_START_OPT options can be set at the time of matching as well as
+        at compile time.
         If errptr is NULL, pcre_compile() returns NULL immediately.  Otherwise,
         if compilation of a pattern fails,  pcre_compile()  returns  NULL,  and
         sets the variable pointed to by errptr to point to a textual error mes-
         sage. This is a static string that is part of the library. You must not
-        try to free it. The offset from the start of the pattern to the charac-
+        try  to  free it. Normally, the offset from the start of the pattern to
-        ter where the error was discovered is placed in the variable pointed to
+        the byte that was being processed when  the  error  was  discovered  is
-        by  erroffset,  which must not be NULL. If it is, an immediate error is
+        placed  in the variable pointed to by erroffset, which must not be NULL
-        given.
+        (if it is, an immediate error is given). However, for an invalid  UTF-8
+        string,  the offset is that of the first byte of the failing character.
-        If pcre_compile2() is used instead of pcre_compile(),  and  the  error-
+        Also, some errors are not detected until checks are  carried  out  when
-        codeptr  argument is not NULL, a non-zero error code number is returned
+        the  whole  pattern  has been scanned; in these cases the offset passed
-        via this argument in the event of an error. This is in addition to  the
+        back is the length of the pattern.
+        Note that the offset is in bytes, not characters, even in  UTF-8  mode.
+        It may sometimes point into the middle of a UTF-8 character.
+        If  pcre_compile2()  is  used instead of pcre_compile(), and the error-
+        codeptr argument is not NULL, a non-zero error code number is  returned
+        via  this argument in the event of an error. This is in addition to the
         textual error message. Error codes and messages are listed below.
-        If  the  final  argument, tableptr, is NULL, PCRE uses a default set of
+        If the final argument, tableptr, is NULL, PCRE uses a  default  set  of
-        character tables that are  built  when  PCRE  is  compiled,  using  the
+        character  tables  that  are  built  when  PCRE  is compiled, using the
-        default  C  locale.  Otherwise, tableptr must be an address that is the
+        default C locale. Otherwise, tableptr must be an address  that  is  the
-        result of a call to pcre_maketables(). This value is  stored  with  the
+        result  of  a  call to pcre_maketables(). This value is stored with the
-        compiled  pattern,  and used again by pcre_exec(), unless another table
+        compiled pattern, and used again by pcre_exec(), unless  another  table
         pointer is passed to it. For more discussion, see the section on locale
         support below.
-        This  code  fragment  shows a typical straightforward call to pcre_com-
+        This code fragment shows a typical straightforward  call  to  pcre_com-
         pile():
           pcre *re;
-Line 1015 
 COMPILING A PATTERN
+Line 1233 
 COMPILING A PATTERN
             &erroffset,       /* for error offset */
             NULL);            /* use default character tables */
-        The following names for option bits are defined in  the  pcre.h  header
+        The  following  names  for option bits are defined in the pcre.h header
         file:
           PCRE_ANCHORED
         If this bit is set, the pattern is forced to be "anchored", that is, it
-        is constrained to match only at the first matching point in the  string
+        is  constrained to match only at the first matching point in the string
-        that  is being searched (the "subject string"). This effect can also be
+        that is being searched (the "subject string"). This effect can also  be
-        achieved by appropriate constructs in the pattern itself, which is  the
+        achieved  by appropriate constructs in the pattern itself, which is the
         only way to do it in Perl.
           PCRE_AUTO_CALLOUT
         If this bit is set, pcre_compile() automatically inserts callout items,
-        all with number 255, before each pattern item. For  discussion  of  the
+        all  with  number  255, before each pattern item. For discussion of the
         callout facility, see the pcrecallout documentation.
+          PCRE_BSR_ANYCRLF
+          PCRE_BSR_UNICODE
+        These options (which are mutually exclusive) control what the \R escape
+        sequence  matches.  The choice is either to match only CR, LF, or CRLF,
+        or to match any Unicode newline sequence. The default is specified when
+        PCRE is built. It can be overridden from within the pattern, or by set-
+        ting an option when a compiled pattern is matched.
           PCRE_CASELESS
-        If  this  bit is set, letters in the pattern match both upper and lower
+        If this bit is set, letters in the pattern match both upper  and  lower
-        case letters. It is equivalent to Perl's  /i  option,  and  it  can  be
+        case  letters.  It  is  equivalent  to  Perl's /i option, and it can be
-        changed  within a pattern by a (?i) option setting. In UTF-8 mode, PCRE
+        changed within a pattern by a (?i) option setting. In UTF-8 mode,  PCRE
-        always understands the concept of case for characters whose values  are
+        always  understands the concept of case for characters whose values are
-        less  than 128, so caseless matching is always possible. For characters
+        less than 128, so caseless matching is always possible. For  characters
-        with higher values, the concept of case is supported if  PCRE  is  com-
+        with  higher  values,  the concept of case is supported if PCRE is com-
-        piled  with Unicode property support, but not otherwise. If you want to
+        piled with Unicode property support, but not otherwise. If you want  to
-        use caseless matching for characters 128 and  above,  you  must  ensure
+        use  caseless  matching  for  characters 128 and above, you must ensure
-        that  PCRE  is  compiled  with Unicode property support as well as with
+        that PCRE is compiled with Unicode property support  as  well  as  with
         UTF-8 support.
           PCRE_DOLLAR_ENDONLY
-        If this bit is set, a dollar metacharacter in the pattern matches  only
+        If  this bit is set, a dollar metacharacter in the pattern matches only
-        at  the  end  of the subject string. Without this option, a dollar also
+        at the end of the subject string. Without this option,  a  dollar  also
-        matches immediately before a newline at the end of the string (but  not
+        matches  immediately before a newline at the end of the string (but not
-        before  any  other newlines). The PCRE_DOLLAR_ENDONLY option is ignored
+        before any other newlines). The PCRE_DOLLAR_ENDONLY option  is  ignored
-        if PCRE_MULTILINE is set.  There is no equivalent  to  this  option  in
+        if  PCRE_MULTILINE  is  set.   There is no equivalent to this option in
         Perl, and no way to set it within a pattern.
           PCRE_DOTALL
-        If this bit is set, a dot metacharater in the pattern matches all char-
+        If this bit is set, a dot metacharacter in the pattern matches a  char-
-        acters, including those that indicate newline. Without it, a  dot  does
+        acter of any value, including one that indicates a newline. However, it
-        not  match  when  the  current position is at a newline. This option is
+        only ever matches one character, even if newlines are  coded  as  CRLF.
-        equivalent to Perl's /s option, and it can be changed within a  pattern
+        Without  this option, a dot does not match when the current position is
-        by  a (?s) option setting. A negative class such as [^a] always matches
+        at a newline. This option is equivalent to Perl's /s option, and it can
-        newline characters, independent of the setting of this option.
+        be  changed within a pattern by a (?s) option setting. A negative class
+        such as [^a] always matches newline characters, independent of the set-
+        ting of this option.
           PCRE_DUPNAMES
-        If this bit is set, names used to identify capturing  subpatterns  need
+        If  this  bit is set, names used to identify capturing subpatterns need
         not be unique. This can be helpful for certain types of pattern when it
-        is known that only one instance of the named  subpattern  can  ever  be
+        is  known  that  only  one instance of the named subpattern can ever be
-        matched.  There  are  more details of named subpatterns below; see also
+        matched. There are more details of named subpatterns  below;  see  also
         the pcrepattern documentation.
           PCRE_EXTENDED
-        If this bit is set, whitespace  data  characters  in  the  pattern  are
+        If  this  bit  is  set,  whitespace  data characters in the pattern are
         totally ignored except when escaped or inside a character class. White-
         space does not include the VT character (code 11). In addition, charac-
         ters between an unescaped # outside a character class and the next new-
-        line, inclusive, are also ignored. This  is  equivalent  to  Perl's  /x
+        line,  inclusive,  are  also  ignored.  This is equivalent to Perl's /x
-        option,  and  it  can be changed within a pattern by a (?x) option set-
+        option, and it can be changed within a pattern by a  (?x)  option  set-
         ting.
+        Which  characters  are  interpreted  as  newlines  is controlled by the
+        options passed to pcre_compile() or by a special sequence at the  start
+        of  the  pattern, as described in the section entitled "Newline conven-
+        tions" in the pcrepattern documentation. Note that the end of this type
+        of  comment  is  a  literal  newline  sequence  in  the pattern; escape
+        sequences that happen to represent a newline do not count.
         This option makes it possible to include  comments  inside  complicated
         patterns.   Note,  however,  that this applies only to data characters.
         Whitespace  characters  may  never  appear  within  special   character
-        sequences  in  a  pattern,  for  example  within the sequence (?( which
+        sequences in a pattern, for example within the sequence (?( that intro-
-        introduces a conditional subpattern.
+        duces a conditional subpattern.
           PCRE_EXTRA
-Line 1095 
 COMPILING A PATTERN
+Line 1331 
 COMPILING A PATTERN
         letter  that  has  no  special  meaning causes an error, thus reserving
         these combinations for future expansion. By  default,  as  in  Perl,  a
         backslash  followed by a letter with no special meaning is treated as a
-        literal. (Perl can, however, be persuaded to give a warning for  this.)
+        literal. (Perl can, however, be persuaded to give an error for this, by
-        There  are  at  present no other features controlled by this option. It
+        running  it with the -w option.) There are at present no other features
-        can also be set by a (?X) option setting within a pattern.
+        controlled by this option. It can also be set by a (?X) option  setting
+        within a pattern.
           PCRE_FIRSTLINE
-        If this option is set, an  unanchored  pattern  is  required  to  match
+        If  this  option  is  set,  an  unanchored pattern is required to match
-        before  or  at  the  first  newline  in  the subject string, though the
+        before or at the first  newline  in  the  subject  string,  though  the
         matched text may continue over the newline.
+          PCRE_JAVASCRIPT_COMPAT
+        If this option is set, PCRE's behaviour is changed in some ways so that
+        it is compatible with JavaScript rather than Perl. The changes  are  as
+        follows:
+        (1)  A  lone  closing square bracket in a pattern causes a compile-time
+        error, because this is illegal in JavaScript (by default it is  treated
+        as a data character). Thus, the pattern AB]CD becomes illegal when this
+        option is set.
+        (2) At run time, a back reference to an unset subpattern group  matches
+        an  empty  string (by default this causes the current matching alterna-
+        tive to fail). A pattern such as (\1)(a) succeeds when this  option  is
+        set  (assuming  it can find an "a" in the subject), whereas it fails by
+        default, for Perl compatibility.
           PCRE_MULTILINE
         By default, PCRE treats the subject string as consisting  of  a  single
-Line 1125 
 COMPILING A PATTERN
+Line 1379 
 COMPILING A PATTERN
           PCRE_NEWLINE_CR
           PCRE_NEWLINE_LF
           PCRE_NEWLINE_CRLF
+          PCRE_NEWLINE_ANYCRLF
           PCRE_NEWLINE_ANY
         These  options  override the default newline definition that was chosen
         when PCRE was built. Setting the first or the second specifies  that  a
         newline  is  indicated  by a single character (CR or LF, respectively).
         Setting PCRE_NEWLINE_CRLF specifies that a newline is indicated by  the
-        two-character  CRLF  sequence.  Setting PCRE_NEWLINE_ANY specifies that
+        two-character  CRLF  sequence.  Setting  PCRE_NEWLINE_ANYCRLF specifies
-        any Unicode newline sequence should be recognized. The Unicode  newline
+        that any of the three preceding sequences should be recognized. Setting
-        sequences  are  the three just mentioned, plus the single characters VT
+        PCRE_NEWLINE_ANY  specifies that any Unicode newline sequence should be
-        (vertical tab, U+000B), FF (formfeed, U+000C), NEL (next line, U+0085),
+        recognized. The Unicode newline sequences are the three just mentioned,
-        LS  (line separator, U+2028), and PS (paragraph separator, U+2029). The
+        plus  the  single  characters  VT (vertical tab, U+000B), FF (formfeed,
-        last two are recognized only in UTF-8 mode.
+        U+000C), NEL (next line, U+0085), LS (line separator, U+2028),  and  PS
+        (paragraph  separator,  U+2029).  The  last  two are recognized only in
+        UTF-8 mode.
         The newline setting in the  options  word  uses  three  bits  that  are
-        treated  as  a  number, giving eight possibilities. Currently only five
+        treated as a number, giving eight possibilities. Currently only six are
-        are used (default plus the four values above). This means that  if  you
+        used (default plus the five values above). This means that if  you  set
-        set  more  than  one  newline option, the combination may or may not be
+        more  than one newline option, the combination may or may not be sensi-
-        sensible. For example, PCRE_NEWLINE_CR with PCRE_NEWLINE_LF is  equiva-
+        ble. For example, PCRE_NEWLINE_CR with PCRE_NEWLINE_LF is equivalent to
-        lent  to PCRE_NEWLINE_CRLF, but other combinations yield unused numbers
+        PCRE_NEWLINE_CRLF,  but other combinations may yield unused numbers and
-        and cause an error.
+        cause an error.
-        The only time that a line break is specially recognized when  compiling
+        The only time that a line break in a pattern  is  specially  recognized
-        a  pattern  is  if  PCRE_EXTENDED  is set, and an unescaped # outside a
+        when  compiling  is when PCRE_EXTENDED is set. CR and LF are whitespace
-        character class is encountered. This indicates  a  comment  that  lasts
+        characters, and so are ignored in this mode. Also, an unescaped #  out-
-        until  after the next line break sequence. In other circumstances, line
+        side  a  character class indicates a comment that lasts until after the
-        break  sequences  are  treated  as  literal  data,   except   that   in
+        next line break sequence. In other circumstances, line break  sequences
-        PCRE_EXTENDED mode, both CR and LF are treated as whitespace characters
+        in patterns are treated as literal data.
-        and are therefore ignored.
         The newline option that is set at compile time becomes the default that
-        is  used for pcre_exec() and pcre_dfa_exec(), but it can be overridden.
+        is used for pcre_exec() and pcre_dfa_exec(), but it can be overridden.
           PCRE_NO_AUTO_CAPTURE
-Line 1165 
 COMPILING A PATTERN
+Line 1421 
 COMPILING A PATTERN
         be  used  for  capturing  (and  they acquire numbers in the usual way).
         There is no equivalent of this option in Perl.
+          NO_START_OPTIMIZE
+        This is an option that acts at matching time; that is, it is really  an
+        option  for  pcre_exec()  or  pcre_dfa_exec().  If it is set at compile
+        time, it is remembered with the compiled pattern and assumed at  match-
+        ing  time.  For  details  see  the discussion of PCRE_NO_START_OPTIMIZE
+        below.
+          PCRE_UCP
+        This option changes the way PCRE processes \B, \b, \D, \d, \S, \s,  \W,
+        \w,  and  some  of  the POSIX character classes. By default, only ASCII
+        characters are recognized, but if PCRE_UCP is set,  Unicode  properties
+        are  used instead to classify characters. More details are given in the
+        section on generic character types in the pcrepattern page. If you  set
+        PCRE_UCP,  matching  one of the items it affects takes much longer. The
+        option is available only if PCRE has been compiled with  Unicode  prop-
+        erty support.
           PCRE_UNGREEDY
-        This option inverts the "greediness" of the quantifiers  so  that  they
+        This  option  inverts  the "greediness" of the quantifiers so that they
-        are  not greedy by default, but become greedy if followed by "?". It is
+        are not greedy by default, but become greedy if followed by "?". It  is
-        not compatible with Perl. It can also be set by a (?U)  option  setting
+        not  compatible  with Perl. It can also be set by a (?U) option setting
         within the pattern.
           PCRE_UTF8
-        This  option  causes PCRE to regard both the pattern and the subject as
+        This option causes PCRE to regard both the pattern and the  subject  as
-        strings of UTF-8 characters instead of single-byte  character  strings.
+        strings  of  UTF-8 characters instead of single-byte character strings.
-        However,  it is available only when PCRE is built to include UTF-8 sup-
+        However, it is available only when PCRE is built to include UTF-8  sup-
-        port. If not, the use of this option provokes an error. Details of  how
+        port.  If not, the use of this option provokes an error. Details of how
-        this  option  changes the behaviour of PCRE are given in the section on
+        this option changes the behaviour of PCRE are given in the  section  on
         UTF-8 support in the main pcre page.
           PCRE_NO_UTF8_CHECK
         When PCRE_UTF8 is set, the validity of the pattern as a UTF-8 string is
-        automatically  checked. If an invalid UTF-8 sequence of bytes is found,
+        automatically checked. There is a  discussion  about  the  validity  of
-        pcre_compile() returns an error. If you already know that your  pattern
+        UTF-8  strings  in  the main pcre page. If an invalid UTF-8 sequence of
-        is  valid, and you want to skip this check for performance reasons, you
+        bytes is found, pcre_compile() returns an error. If  you  already  know
-        can set the PCRE_NO_UTF8_CHECK option. When it is set,  the  effect  of
+        that your pattern is valid, and you want to skip this check for perfor-
-        passing an invalid UTF-8 string as a pattern is undefined. It may cause
+        mance reasons, you can set the PCRE_NO_UTF8_CHECK option.  When  it  is
-        your program to crash.  Note that this option can  also  be  passed  to
+        set,  the  effect  of  passing  an invalid UTF-8 string as a pattern is
-        pcre_exec()  and pcre_dfa_exec(), to suppress the UTF-8 validity check-
+        undefined. It may cause your program to crash. Note  that  this  option
-        ing of subject strings.
+        can  also be passed to pcre_exec() and pcre_dfa_exec(), to suppress the
+        UTF-8 validity checking of subject strings.
  COMPILATION ERROR CODES
-Line 1213 
 COMPILATION ERROR CODES
+Line 1489 
 COMPILATION ERROR CODES
  nothing to repeat
  [this code is not in use]
  internal error: unexpected repeat
- unrecognized character after (?
+ unrecognized character after (? or (?-
  POSIX named classes are supported only within a class
  missing )
  reference to non-existent subpattern
-Line 1221 
 COMPILATION ERROR CODES
+Line 1497 
 COMPILATION ERROR CODES
  unknown option bit(s) set
  missing ) after comment
  [this code is not in use]
- regular expression too large
+ regular expression is too large
  failed to get memory
  unmatched parentheses
  internal error: code overflow
-Line 1230 
 COMPILATION ERROR CODES
+Line 1506 
 COMPILATION ERROR CODES
  malformed number or name after (?(
  conditional group contains more than two branches
  assertion expected after (?(
- (?R or (?digits must be followed by )
+ (?R or (?[+-]digits must be followed by )
  unknown POSIX class name
  POSIX collating elements are not supported
  this version of PCRE is not compiled with PCRE_UTF8 support
-Line 1250 
 COMPILATION ERROR CODES
+Line 1526 
 COMPILATION ERROR CODES
  malformed \P or \p sequence
  unknown property name after \P or \p
  subpattern name is too long (maximum 32 characters)
- too many named subpatterns (maximum 10,000)
+ too many named subpatterns (maximum 10000)
- repeated subpattern is too long
+ [this code is not in use]
  octal value is greater than \377 (not in UTF-8 mode)
  internal error: overran compiling workspace
-  internal  error:  previously-checked  referenced  subpattern not
+ internal error: previously-checked referenced subpattern
-        found
+                not found
  DEFINE group contains more than one branch
  repeating a DEFINE group is not allowed
- inconsistent NEWLINE options"
+ inconsistent NEWLINE options
+ \g is not followed by a braced, angle-bracketed, or quoted
+                name/number or by a plain number
+ a numbered reference must not be zero
+ an argument is not allowed for (*ACCEPT), (*FAIL), or (*COMMIT)
+ (*VERB) not recognized
+ number is too big
+ subpattern name expected
+ digit expected after (?+
+ ] is an invalid data character in JavaScript compatibility mode
+ different names for subpatterns of the same number are
+                not allowed
+ (*MARK) must have an argument
+ this version of PCRE is not compiled with PCRE_UCP support
+        The  numbers  32  and 10000 in errors 48 and 49 are defaults; different
+        values may be used if the limits were changed when PCRE was built.
  STUDYING A PATTERN
-Line 1275 
 STUDYING A PATTERN
+Line 1567 
 STUDYING A PATTERN
         the results of the study.
         The  returned  value  from  pcre_study()  can  be  passed  directly  to
-        pcre_exec().  However,  a  pcre_extra  block also contains other fields
+        pcre_exec()  or  pcre_dfa_exec(). However, a pcre_extra block also con-
-        that can be set by the caller before the block  is  passed;  these  are
+        tains other fields that can be set by the caller before  the  block  is
-        described below in the section on matching a pattern.
+        passed; these are described below in the section on matching a pattern.
-        If  studying  the  pattern  does not produce any additional information
+        If  studying  the  pattern  does  not  produce  any useful information,
         pcre_study() returns NULL. In that circumstance, if the calling program
-        wants  to  pass  any of the other fields to pcre_exec(), it must set up
+        wants   to   pass   any   of   the   other  fields  to  pcre_exec()  or
-        its own pcre_extra block.
+        pcre_dfa_exec(), it must set up its own pcre_extra block.
         The second argument of pcre_study() contains option bits.  At  present,
         no options are defined, and this argument should always be zero.
-Line 1302 
 STUDYING A PATTERN
+Line 1594 
 STUDYING A PATTERN
 ,              /* no options exist */
             &error);        /* set to NULL or points to a message */
-        At present, studying a pattern is useful only for non-anchored patterns
+        Studying a pattern does two things: first, a lower bound for the length
-        that  do not have a single fixed starting character. A bitmap of possi-
+        of subject string that is needed to match the pattern is computed. This
-        ble starting bytes is created.
+        does not mean that there are any strings of that length that match, but
+        it  does  guarantee that no shorter strings match. The value is used by
+        pcre_exec() and pcre_dfa_exec() to avoid  wasting  time  by  trying  to
+        match  strings  that are shorter than the lower bound. You can find out
+        the value in a calling program via the pcre_fullinfo() function.
+        Studying a pattern is also useful for non-anchored patterns that do not
+        have  a  single fixed starting character. A bitmap of possible starting
+        bytes is created. This speeds up finding a position in the  subject  at
+        which to start matching.
+        The  two  optimizations  just  described can be disabled by setting the
+        PCRE_NO_START_OPTIMIZE   option    when    calling    pcre_exec()    or
+        pcre_dfa_exec().  You  might  want  to do this if your pattern contains
+        callouts or (*MARK), and you want to make use of  these  facilities  in
+        cases  where  matching fails. See the discussion of PCRE_NO_START_OPTI-
+        MIZE below.
  LOCALE SUPPORT
         PCRE handles caseless matching, and determines whether  characters  are
-        letters  digits,  or whatever, by reference to a set of tables, indexed
+        letters,  digits, or whatever, by reference to a set of tables, indexed
         by character value. When running in UTF-8 mode, this  applies  only  to
-        characters  with  codes  less than 128. Higher-valued codes never match
+        characters  with  codes  less than 128. By default, higher-valued codes
-        escapes such as \w or \d, but can be tested with \p if  PCRE  is  built
+        never match escapes such as \w or \d, but they can be tested with \p if
-        with  Unicode  character property support. The use of locales with Uni-
+        PCRE  is  built with Unicode character property support. Alternatively,
-        code is discouraged.
+        the PCRE_UCP option can be set at compile  time;  this  causes  \w  and
+        friends to use Unicode property support instead of built-in tables. The
-        An internal set of tables is created in the default C locale when  PCRE
+        use of locales with Unicode is discouraged. If you are handling charac-
-        is  built.  This  is  used when the final argument of pcre_compile() is
+        ters  with codes greater than 128, you should either use UTF-8 and Uni-
-        NULL, and is sufficient for many applications. An  alternative  set  of
+        code, or use locales, but not try to mix the two.
-        tables  can,  however, be supplied. These may be created in a different
-        locale from the default. As more and more applications change to  using
+        PCRE contains an internal set of tables that are used  when  the  final
-        Unicode, the need for this locale support is expected to die away.
+        argument  of  pcre_compile()  is  NULL.  These  are sufficient for many
+        applications.  Normally, the internal tables recognize only ASCII char-
-        External  tables  are  built by calling the pcre_maketables() function,
+        acters. However, when PCRE is built, it is possible to cause the inter-
-        which has no arguments, in the relevant locale. The result can then  be
+        nal tables to be rebuilt in the default "C" locale of the local system,
-        passed  to  pcre_compile()  or  pcre_exec()  as often as necessary. For
+        which may cause them to be different.
-        example, to build and use tables that are appropriate  for  the  French
-        locale  (where  accented  characters  with  values greater than 128 are
+        The  internal tables can always be overridden by tables supplied by the
+        application that calls PCRE. These may be created in a different locale
+        from  the  default.  As more and more applications change to using Uni-
+        code, the need for this locale support is expected to die away.
+        External tables are built by calling  the  pcre_maketables()  function,
+        which  has no arguments, in the relevant locale. The result can then be
+        passed to pcre_compile() or pcre_exec()  as  often  as  necessary.  For
+        example,  to  build  and use tables that are appropriate for the French
+        locale (where accented characters with  values  greater  than  128  are
         treated as letters), the following code could be used:
           setlocale(LC_CTYPE, "fr_FR");
           tables = pcre_maketables();
           re = pcre_compile(..., tables);
+        The  locale  name "fr_FR" is used on Linux and other Unix-like systems;
+        if you are using Windows, the name for the French locale is "french".
         When pcre_maketables() runs, the tables are built  in  memory  that  is
         obtained  via  pcre_malloc. It is the caller's responsibility to ensure
         that the memory containing the tables remains available for as long  as
-Line 1437 
 INFORMATION ABOUT A PATTERN
+Line 1757 
 INFORMATION ABOUT A PATTERN
         returned. The fourth argument should point to an unsigned char *  vari-
         able.
+          PCRE_INFO_HASCRORLF
+        Return  1  if  the  pattern  contains any explicit matches for CR or LF
+        characters, otherwise 0. The fourth argument should  point  to  an  int
+        variable.  An explicit match is either a literal CR or LF character, or
+        \r or \n.
+          PCRE_INFO_JCHANGED
+        Return 1 if the (?J) or (?-J) option setting is used  in  the  pattern,
+        otherwise  0. The fourth argument should point to an int variable. (?J)
+        and (?-J) set and unset the local PCRE_DUPNAMES option, respectively.
           PCRE_INFO_LASTLITERAL
-        Return  the  value of the rightmost literal byte that must exist in any
+        Return the value of the rightmost literal byte that must exist  in  any
-        matched string, other than at its  start,  if  such  a  byte  has  been
+        matched  string,  other  than  at  its  start,  if such a byte has been
         recorded. The fourth argument should point to an int variable. If there
-        is no such byte, -1 is returned. For anchored patterns, a last  literal
+        is  no such byte, -1 is returned. For anchored patterns, a last literal
-        byte  is  recorded only if it follows something of variable length. For
+        byte is recorded only if it follows something of variable  length.  For
         example, for the pattern /^a\d+z\d+/ the returned value is "z", but for
         /^a\dz\d/ the returned value is -1.
+          PCRE_INFO_MINLENGTH
+        If the pattern was studied and a minimum length  for  matching  subject
+        strings  was  computed,  its  value is returned. Otherwise the returned
+        value is -1. The value is a number of characters, not bytes  (this  may
+        be  relevant in UTF-8 mode). The fourth argument should point to an int
+        variable. A non-negative value is a lower bound to the  length  of  any
+        matching  string.  There  may not be any strings of that length that do
+        actually match, but every string that does match is at least that long.
           PCRE_INFO_NAMECOUNT
           PCRE_INFO_NAMEENTRYSIZE
           PCRE_INFO_NAMETABLE
-        PCRE  supports the use of named as well as numbered capturing parenthe-
+        PCRE supports the use of named as well as numbered capturing  parenthe-
-        ses. The names are just an additional way of identifying the  parenthe-
+        ses.  The names are just an additional way of identifying the parenthe-
         ses, which still acquire numbers. Several convenience functions such as
-        pcre_get_named_substring() are provided for  extracting  captured  sub-
+        pcre_get_named_substring()  are  provided  for extracting captured sub-
-        strings  by  name. It is also possible to extract the data directly, by
+        strings by name. It is also possible to extract the data  directly,  by
-        first converting the name to a number in order to  access  the  correct
+        first  converting  the  name to a number in order to access the correct
         pointers in the output vector (described with pcre_exec() below). To do
-        the conversion, you need  to  use  the  name-to-number  map,  which  is
+        the  conversion,  you  need  to  use  the  name-to-number map, which is
         described by these three values.
         The map consists of a number of fixed-size entries. PCRE_INFO_NAMECOUNT
         gives the number of entries, and PCRE_INFO_NAMEENTRYSIZE gives the size
-        of  each  entry;  both  of  these  return  an int value. The entry size
+        of each entry; both of these  return  an  int  value.  The  entry  size
-        depends on the length of the longest name. PCRE_INFO_NAMETABLE  returns
+        depends  on the length of the longest name. PCRE_INFO_NAMETABLE returns
-        a  pointer  to  the  first  entry of the table (a pointer to char). The
+        a pointer to the first entry of the table  (a  pointer  to  char).  The
         first two bytes of each entry are the number of the capturing parenthe-
-        sis,  most  significant byte first. The rest of the entry is the corre-
+        sis, most significant byte first. The rest of the entry is  the  corre-
-        sponding name, zero terminated. The names are  in  alphabetical  order.
+        sponding name, zero terminated.
-        When PCRE_DUPNAMES is set, duplicate names are in order of their paren-
-        theses numbers. For example, consider  the  following  pattern  (assume
+        The  names are in alphabetical order. Duplicate names may appear if (?|
-        PCRE_EXTENDED  is  set,  so  white  space  -  including  newlines  - is
+        is used to create multiple groups with the same number, as described in
-        ignored):
+        the  section  on  duplicate subpattern numbers in the pcrepattern page.
+        Duplicate names for subpatterns with different  numbers  are  permitted
+        only  if  PCRE_DUPNAMES  is  set. In all cases of duplicate names, they
+        appear in the table in the order in which they were found in  the  pat-
+        tern.  In  the  absence  of (?| this is the order of increasing number;
+        when (?| is used this is not necessarily the case because later subpat-
+        terns may have lower numbers.
+        As  a  simple  example of the name/number table, consider the following
+        pattern (assume PCRE_EXTENDED is set, so white space -  including  new-
+        lines - is ignored):
           (?<date> (?<year>(\d\d)?\d\d) -
           (?<month>\d\d) - (?<day>\d\d) )
-        There are four named subpatterns, so the table has  four  entries,  and
+        There  are  four  named subpatterns, so the table has four entries, and
-        each  entry  in the table is eight bytes long. The table is as follows,
+        each entry in the table is eight bytes long. The table is  as  follows,
         with non-printing bytes shows in hexadecimal, and undefined bytes shown
         as ??:
-Line 1487 
 INFORMATION ABOUT A PATTERN
+Line 1840 
 INFORMATION ABOUT A PATTERN
 04 m  o  n  t  h  00
 02 y  e  a  r  00 ??
-        When  writing  code  to  extract  data from named subpatterns using the
+        When writing code to extract data  from  named  subpatterns  using  the
-        name-to-number map, remember that the length of the entries  is  likely
+        name-to-number  map,  remember that the length of the entries is likely
         to be different for each compiled pattern.
+          PCRE_INFO_OKPARTIAL
+        Return 1  if  the  pattern  can  be  used  for  partial  matching  with
+        pcre_exec(),  otherwise  0.  The fourth argument should point to an int
+        variable. From  release  8.00,  this  always  returns  1,  because  the
+        restrictions  that  previously  applied  to  partial matching have been
+        lifted. The pcrepartial documentation gives details of  partial  match-
+        ing.
           PCRE_INFO_OPTIONS
         Return  a  copy of the options with which the pattern was compiled. The
         fourth argument should point to an unsigned long  int  variable.  These
         option bits are those specified in the call to pcre_compile(), modified
-        by any top-level option settings within the pattern itself.
+        by any top-level option settings at the start of the pattern itself. In
+        other  words,  they are the options that will be in force when matching
+        starts. For example, if the pattern /(?im)abc(?-i)d/ is  compiled  with
+        the  PCRE_EXTENDED option, the result is PCRE_CASELESS, PCRE_MULTILINE,
+        and PCRE_EXTENDED.
         A pattern is automatically anchored by PCRE if  all  of  its  top-level
         alternatives begin with one of the following:
-Line 1522 
 INFORMATION ABOUT A PATTERN
+Line 1888 
 INFORMATION ABOUT A PATTERN
         Return the size of the data block pointed to by the study_data field in
         a pcre_extra block. That is,  it  is  the  value  that  was  passed  to
         pcre_malloc() when PCRE was getting memory into which to place the data
-        created by pcre_study(). The fourth argument should point to  a  size_t
+        created by pcre_study(). If pcre_extra is NULL, or there  is  no  study
+        data,  zero  is  returned. The fourth argument should point to a size_t
         variable.
-Line 1530 
 OBSOLETE INFO FUNCTION
+Line 1897 
 OBSOLETE INFO FUNCTION
         int pcre_info(const pcre *code, int *optptr, int *firstcharptr);
-        The  pcre_info()  function is now obsolete because its interface is too
+        The pcre_info() function is now obsolete because its interface  is  too
-        restrictive to return all the available data about a compiled  pattern.
+        restrictive  to return all the available data about a compiled pattern.
-        New   programs   should  use  pcre_fullinfo()  instead.  The  yield  of
+        New  programs  should  use  pcre_fullinfo()  instead.  The   yield   of
-        pcre_info() is the number of capturing subpatterns, or one of the  fol-
+        pcre_info()  is the number of capturing subpatterns, or one of the fol-
         lowing negative numbers:
           PCRE_ERROR_NULL       the argument code was NULL
           PCRE_ERROR_BADMAGIC   the "magic number" was not found
-        If  the  optptr  argument is not NULL, a copy of the options with which
+        If the optptr argument is not NULL, a copy of the  options  with  which
-        the pattern was compiled is placed in the integer  it  points  to  (see
+        the  pattern  was  compiled  is placed in the integer it points to (see
         PCRE_INFO_OPTIONS above).
-        If  the  pattern  is  not anchored and the firstcharptr argument is not
+        If the pattern is not anchored and the  firstcharptr  argument  is  not
-        NULL, it is used to pass back information about the first character  of
+        NULL,  it is used to pass back information about the first character of
         any matched string (see PCRE_INFO_FIRSTBYTE above).
-Line 1552 
 REFERENCE COUNTS
+Line 1919 
 REFERENCE COUNTS
         int pcre_refcount(pcre *code, int adjust);
-        The  pcre_refcount()  function is used to maintain a reference count in
+        The pcre_refcount() function is used to maintain a reference  count  in
         the data block that contains a compiled pattern. It is provided for the
-        benefit  of  applications  that  operate  in an object-oriented manner,
+        benefit of applications that  operate  in  an  object-oriented  manner,
         where different parts of the application may be using the same compiled
         pattern, but you want to free the block when they are all done.
         When a pattern is compiled, the reference count field is initialized to
-        zero.  It is changed only by calling this function, whose action is  to
+        zero.   It is changed only by calling this function, whose action is to
-        add  the  adjust  value  (which may be positive or negative) to it. The
+        add the adjust value (which may be positive or  negative)  to  it.  The
         yield of the function is the new value. However, the value of the count
-        is  constrained to lie between 0 and 65535, inclusive. If the new value
+        is constrained to lie between 0 and 65535, inclusive. If the new  value
         is outside these limits, it is forced to the appropriate limit value.
-        Except when it is zero, the reference count is not correctly  preserved
+        Except  when it is zero, the reference count is not correctly preserved
-        if  a  pattern  is  compiled on one host and then transferred to a host
+        if a pattern is compiled on one host and then  transferred  to  a  host
         whose byte-order is different. (This seems a highly unlikely scenario.)
-Line 1578 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
+Line 1945 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
         The  function pcre_exec() is called to match a subject string against a
         compiled pattern, which is passed in the code argument. If the  pattern
-        has been studied, the result of the study should be passed in the extra
+        was  studied,  the  result  of  the study should be passed in the extra
         argument. This function is the main matching facility of  the  library,
         and it operates in a Perl-like manner. For specialist use there is also
         an alternative matching function, which is described below in the  sec-
-Line 1618 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
+Line 1985 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
           unsigned long int match_limit_recursion;
           void *callout_data;
           const unsigned char *tables;
+          unsigned char **mark;
         The  flags  field  is a bitmap that specifies which of the other fields
         are set. The flag bits are:
-Line 1627 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
+Line 1995 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
           PCRE_EXTRA_MATCH_LIMIT_RECURSION
           PCRE_EXTRA_CALLOUT_DATA
           PCRE_EXTRA_TABLES
+          PCRE_EXTRA_MARK
         Other flag bits should be set to zero. The study_data field is  set  in
         the  pcre_extra  block  that is returned by pcre_study(), together with
-Line 1637 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
+Line 2006 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
         The match_limit field provides a means of preventing PCRE from using up
         a  vast amount of resources when running patterns that are not going to
         match, but which have a very large number  of  possibilities  in  their
-        search  trees.  The  classic  example  is  the  use of nested unlimited
+        search  trees. The classic example is a pattern that uses nested unlim-
-        repeats.
+        ited repeats.
         Internally, PCRE uses a function called match() which it calls  repeat-
         edly  (sometimes  recursively). The limit set by match_limit is imposed
-Line 1660 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
+Line 2029 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
         the  total number of calls, because not all calls to match() are recur-
         sive.  This limit is of use only if it is set smaller than match_limit.
-        Limiting  the  recursion  depth  limits the amount of stack that can be
+        Limiting the recursion depth limits the amount of  stack  that  can  be
         used, or, when PCRE has been compiled to use memory on the heap instead
         of the stack, the amount of heap memory that can be used.
-        The  default  value  for  match_limit_recursion can be set when PCRE is
+        The default value for match_limit_recursion can be  set  when  PCRE  is
-        built; the default default  is  the  same  value  as  the  default  for
+        built;  the  default  default  is  the  same  value  as the default for
-        match_limit.  You can override the default by suppling pcre_exec() with
+        match_limit. You can override the default by suppling pcre_exec()  with
-        a  pcre_extra  block  in  which  match_limit_recursion  is   set,   and
+        a   pcre_extra   block  in  which  match_limit_recursion  is  set,  and
-        PCRE_EXTRA_MATCH_LIMIT_RECURSION  is  set  in  the  flags field. If the
+        PCRE_EXTRA_MATCH_LIMIT_RECURSION is set in  the  flags  field.  If  the
         limit is exceeded, pcre_exec() returns PCRE_ERROR_RECURSIONLIMIT.
-        The pcre_callout field is used in conjunction with the  "callout"  fea-
+        The  callout_data  field is used in conjunction with the "callout" fea-
-        ture, which is described in the pcrecallout documentation.
+        ture, and is described in the pcrecallout documentation.
-        The  tables  field  is  used  to  pass  a  character  tables pointer to
+        The tables field  is  used  to  pass  a  character  tables  pointer  to
-        pcre_exec(); this overrides the value that is stored with the  compiled
+        pcre_exec();  this overrides the value that is stored with the compiled
-        pattern.  A  non-NULL value is stored with the compiled pattern only if
+        pattern. A non-NULL value is stored with the compiled pattern  only  if
-        custom tables were supplied to pcre_compile() via  its  tableptr  argu-
+        custom  tables  were  supplied to pcre_compile() via its tableptr argu-
         ment.  If NULL is passed to pcre_exec() using this mechanism, it forces
-        PCRE's internal tables to be used. This facility is  helpful  when  re-
+        PCRE's  internal  tables  to be used. This facility is helpful when re-
-        using  patterns  that  have been saved after compiling with an external
+        using patterns that have been saved after compiling  with  an  external
-        set of tables, because the external tables  might  be  at  a  different
+        set  of  tables,  because  the  external tables might be at a different
-        address  when  pcre_exec() is called. See the pcreprecompile documenta-
+        address when pcre_exec() is called. See the  pcreprecompile  documenta-
         tion for a discussion of saving compiled patterns for later use.
+        If  PCRE_EXTRA_MARK  is  set in the flags field, the mark field must be
+        set to point to a char * variable. If the pattern  contains  any  back-
+        tracking  control verbs such as (*MARK:NAME), and the execution ends up
+        with a name to pass back, a pointer to the  name  string  (zero  termi-
+        nated)  is  placed  in  the  variable pointed to by the mark field. The
+        names are within the compiled pattern; if you wish  to  retain  such  a
+        name  you must copy it before freeing the memory of a compiled pattern.
+        If there is no name to pass back, the variable pointed to by  the  mark
+        field  set  to NULL. For details of the backtracking control verbs, see
+        the section entitled "Backtracking control" in the pcrepattern documen-
+        tation.
     Option bits for pcre_exec()
-        The unused bits of the options argument for pcre_exec() must  be  zero.
+        The  unused  bits of the options argument for pcre_exec() must be zero.
-        The  only  bits  that  may  be set are PCRE_ANCHORED, PCRE_NEWLINE_xxx,
+        The only bits that may  be  set  are  PCRE_ANCHORED,  PCRE_NEWLINE_xxx,
-        PCRE_NOTBOL,   PCRE_NOTEOL,   PCRE_NOTEMPTY,   PCRE_NO_UTF8_CHECK   and
+        PCRE_NOTBOL,    PCRE_NOTEOL,    PCRE_NOTEMPTY,   PCRE_NOTEMPTY_ATSTART,
-        PCRE_PARTIAL.
+        PCRE_NO_START_OPTIMIZE,  PCRE_NO_UTF8_CHECK,   PCRE_PARTIAL_SOFT,   and
+        PCRE_PARTIAL_HARD.
           PCRE_ANCHORED
-Line 1699 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
+Line 2081 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
         turned  out to be anchored by virtue of its contents, it cannot be made
         unachored at matching time.
+          PCRE_BSR_ANYCRLF
+          PCRE_BSR_UNICODE
+        These options (which are mutually exclusive) control what the \R escape
+        sequence  matches.  The choice is either to match only CR, LF, or CRLF,
+        or to match any Unicode newline sequence. These  options  override  the
+        choice that was made or defaulted when the pattern was compiled.
           PCRE_NEWLINE_CR
           PCRE_NEWLINE_LF
           PCRE_NEWLINE_CRLF
+          PCRE_NEWLINE_ANYCRLF
           PCRE_NEWLINE_ANY
-        These options override  the  newline  definition  that  was  chosen  or
+        These  options  override  the  newline  definition  that  was chosen or
-        defaulted  when the pattern was compiled. For details, see the descrip-
+        defaulted when the pattern was compiled. For details, see the  descrip-
-        tion of pcre_compile()  above.  During  matching,  the  newline  choice
+        tion  of  pcre_compile()  above.  During  matching,  the newline choice
-        affects  the  behaviour  of the dot, circumflex, and dollar metacharac-
+        affects the behaviour of the dot, circumflex,  and  dollar  metacharac-
-        ters. It may also alter the way the match position is advanced after  a
+        ters.  It may also alter the way the match position is advanced after a
-        match  failure  for  an  unanchored  pattern. When PCRE_NEWLINE_CRLF or
+        match failure for an unanchored pattern.
-        PCRE_NEWLINE_ANY is set, and a match attempt  fails  when  the  current
-        position  is  at a CRLF sequence, the match position is advanced by two
+        When PCRE_NEWLINE_CRLF, PCRE_NEWLINE_ANYCRLF,  or  PCRE_NEWLINE_ANY  is
-        characters instead of one, in other words, to after the CRLF.
+        set,  and a match attempt for an unanchored pattern fails when the cur-
+        rent position is at a  CRLF  sequence,  and  the  pattern  contains  no
+        explicit  matches  for  CR  or  LF  characters,  the  match position is
+        advanced by two characters instead of one, in other words, to after the
+        CRLF.
+        The above rule is a compromise that makes the most common cases work as
+        expected. For example, if the  pattern  is  .+A  (and  the  PCRE_DOTALL
+        option is not set), it does not match the string "\r\nA" because, after
+        failing at the start, it skips both the CR and the LF before  retrying.
+        However,  the  pattern  [\r\n]A does match that string, because it con-
+        tains an explicit CR or LF reference, and so advances only by one char-
+        acter after the first failure.
+        An explicit match for CR of LF is either a literal appearance of one of
+        those characters, or one of the \r or  \n  escape  sequences.  Implicit
+        matches  such  as [^X] do not count, nor does \s (which includes CR and
+        LF in the characters that it matches).
+        Notwithstanding the above, anomalous effects may still occur when  CRLF
+        is a valid newline sequence and explicit \r or \n escapes appear in the
+        pattern.
           PCRE_NOTBOL
-Line 1740 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
+Line 2152 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
           a?b?
-        is applied to a string not beginning with "a" or "b",  it  matches  the
+        is applied to a string not beginning with "a" or  "b",  it  matches  an
         empty  string at the start of the subject. With PCRE_NOTEMPTY set, this
         match is not valid, so PCRE searches further into the string for occur-
         rences of "a" or "b".
-        Perl has no direct equivalent of PCRE_NOTEMPTY, but it does make a spe-
+          PCRE_NOTEMPTY_ATSTART
-        cial case of a pattern match of the empty  string  within  its  split()
-        function,  and  when  using  the /g modifier. It is possible to emulate
+        This  is  like PCRE_NOTEMPTY, except that an empty string match that is
-        Perl's behaviour after matching a null string by first trying the match
+        not at the start of  the  subject  is  permitted.  If  the  pattern  is
-        again at the same offset with PCRE_NOTEMPTY and PCRE_ANCHORED, and then
+        anchored, such a match can occur only if the pattern contains \K.
-        if that fails by advancing the starting offset (see below)  and  trying
-        an ordinary match again. There is some code that demonstrates how to do
+        Perl     has    no    direct    equivalent    of    PCRE_NOTEMPTY    or
-        this in the pcredemo.c sample program.
+        PCRE_NOTEMPTY_ATSTART, but it does make a special  case  of  a  pattern
+        match  of  the empty string within its split() function, and when using
+        the /g modifier. It is  possible  to  emulate  Perl's  behaviour  after
+        matching a null string by first trying the match again at the same off-
+        set with PCRE_NOTEMPTY_ATSTART and  PCRE_ANCHORED,  and  then  if  that
+        fails, by advancing the starting offset (see below) and trying an ordi-
+        nary match again. There is some code that demonstrates how to  do  this
+        in  the  pcredemo sample program. In the most general case, you have to
+        check to see if the newline convention recognizes CRLF  as  a  newline,
+        and  if so, and the current character is CR followed by LF, advance the
+        starting offset by two characters instead of one.
+          PCRE_NO_START_OPTIMIZE
+        There are a number of optimizations that pcre_exec() uses at the  start
+        of  a  match,  in  order to speed up the process. For example, if it is
+        known that an unanchored match must start with a specific character, it
+        searches  the  subject  for that character, and fails immediately if it
+        cannot find it, without actually running the  main  matching  function.
+        This means that a special item such as (*COMMIT) at the start of a pat-
+        tern is not considered until after a suitable starting  point  for  the
+        match  has been found. When callouts or (*MARK) items are in use, these
+        "start-up" optimizations can cause them to be skipped if the pattern is
+        never  actually  used.  The start-up optimizations are in effect a pre-
+        scan of the subject that takes place before the pattern is run.
+        The PCRE_NO_START_OPTIMIZE option disables the start-up  optimizations,
+        possibly  causing  performance  to  suffer,  but ensuring that in cases
+        where the result is "no match", the callouts do occur, and  that  items
+        such as (*COMMIT) and (*MARK) are considered at every possible starting
+        position in the subject string. If  PCRE_NO_START_OPTIMIZE  is  set  at
+        compile time, it cannot be unset at matching time.
+        Setting  PCRE_NO_START_OPTIMIZE  can  change  the outcome of a matching
+        operation.  Consider the pattern
+          (*COMMIT)ABC
+        When this is compiled, PCRE records the fact that a  match  must  start
+        with  the  character  "A".  Suppose the subject string is "DEFABC". The
+        start-up optimization scans along the subject, finds "A" and  runs  the
+        first  match attempt from there. The (*COMMIT) item means that the pat-
+        tern must match the current starting position, which in this  case,  it
+        does.  However,  if  the  same match is run with PCRE_NO_START_OPTIMIZE
+        set, the initial scan along the subject string  does  not  happen.  The
+        first  match  attempt  is  run  starting  from "D" and when this fails,
+        (*COMMIT) prevents any further matches  being  tried,  so  the  overall
+        result  is  "no  match". If the pattern is studied, more start-up opti-
+        mizations may be used. For example, a minimum length  for  the  subject
+        may be recorded. Consider the pattern
+          (*MARK:A)(X|Y)
+        The  minimum  length  for  a  match is one character. If the subject is
+        "ABC", there will be attempts to  match  "ABC",  "BC",  "C",  and  then
+        finally  an empty string.  If the pattern is studied, the final attempt
+        does not take place, because PCRE knows that the subject is too  short,
+        and  so  the  (*MARK) is never encountered.  In this case, studying the
+        pattern does not affect the overall match result, which  is  still  "no
+        match", but it does affect the auxiliary information that is returned.
           PCRE_NO_UTF8_CHECK
         When PCRE_UTF8 is set at compile time, the validity of the subject as a
-        UTF-8  string is automatically checked when pcre_exec() is subsequently
+        UTF-8 string is automatically checked when pcre_exec() is  subsequently
-        called.  The value of startoffset is also checked  to  ensure  that  it
+        called.   The  value  of  startoffset is also checked to ensure that it
-        points  to the start of a UTF-8 character. If an invalid UTF-8 sequence
+        points to the start of a UTF-8 character. There is a  discussion  about
-        of bytes is found, pcre_exec() returns the error PCRE_ERROR_BADUTF8. If
+        the  validity  of  UTF-8 strings in the section on UTF-8 support in the
-        startoffset  contains  an  invalid  value, PCRE_ERROR_BADUTF8_OFFSET is
+        main pcre page. If  an  invalid  UTF-8  sequence  of  bytes  is  found,
-        returned.
+        pcre_exec()  returns  the  error  PCRE_ERROR_BADUTF8  or,  if PCRE_PAR-
+        TIAL_HARD is set and the problem is a truncated UTF-8 character at  the
+        end  of  the  subject, PCRE_ERROR_SHORTUTF8. In both cases, information
+        about the precise nature of the error may also  be  returned  (see  the
+        descriptions  of these errors in the section entitled Error return val-
+        ues from pcre_exec() below).  If startoffset contains a value that does
+        not  point to the start of a UTF-8 character (or to the end of the sub-
+        ject), PCRE_ERROR_BADUTF8_OFFSET is returned.
         If you already know that your subject is valid, and you  want  to  skip
         these    checks    for   performance   reasons,   you   can   set   the
-Line 1770 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
+Line 2248 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
         do  this  for the second and subsequent calls to pcre_exec() if you are
         making repeated calls to find all  the  matches  in  a  single  subject
         string.  However,  you  should  be  sure  that the value of startoffset
-        points to the start of a UTF-8 character.  When  PCRE_NO_UTF8_CHECK  is
+        points to the start of a UTF-8 character (or the end of  the  subject).
-        set,  the  effect of passing an invalid UTF-8 string as a subject, or a
+        When  PCRE_NO_UTF8_CHECK is set, the effect of passing an invalid UTF-8
-        value of startoffset that does not point to the start of a UTF-8  char-
+        string as a subject or an invalid value of  startoffset  is  undefined.
-        acter, is undefined. Your program may crash.
+        Your program may crash.
-          PCRE_PARTIAL
+          PCRE_PARTIAL_HARD
+          PCRE_PARTIAL_SOFT
-        This  option  turns  on  the  partial  matching feature. If the subject
-        string fails to match the pattern, but at some point during the  match-
+        These  options turn on the partial matching feature. For backwards com-
-        ing  process  the  end of the subject was reached (that is, the subject
+        patibility, PCRE_PARTIAL is a synonym for PCRE_PARTIAL_SOFT. A  partial
-        partially matches the pattern and the failure to  match  occurred  only
+        match  occurs if the end of the subject string is reached successfully,
-        because  there were not enough subject characters), pcre_exec() returns
+        but there are not enough subject characters to complete the  match.  If
-        PCRE_ERROR_PARTIAL instead of PCRE_ERROR_NOMATCH. When PCRE_PARTIAL  is
+        this happens when PCRE_PARTIAL_SOFT (but not PCRE_PARTIAL_HARD) is set,
-        used,  there  are restrictions on what may appear in the pattern. These
+        matching continues by testing any remaining alternatives.  Only  if  no
-        are discussed in the pcrepartial documentation.
+        complete  match  can be found is PCRE_ERROR_PARTIAL returned instead of
+        PCRE_ERROR_NOMATCH. In other words,  PCRE_PARTIAL_SOFT  says  that  the
+        caller  is  prepared to handle a partial match, but only if no complete
+        match can be found.
+        If PCRE_PARTIAL_HARD is set, it overrides  PCRE_PARTIAL_SOFT.  In  this
+        case,  if  a  partial  match  is found, pcre_exec() immediately returns
+        PCRE_ERROR_PARTIAL, without  considering  any  other  alternatives.  In
+        other  words, when PCRE_PARTIAL_HARD is set, a partial match is consid-
+        ered to be more important that an alternative complete match.
+        In both cases, the portion of the string that was  inspected  when  the
+        partial match was found is set as the first matching string. There is a
+        more detailed discussion of partial and  multi-segment  matching,  with
+        examples, in the pcrepartial documentation.
     The string to be matched by pcre_exec()
-        The subject string is passed to pcre_exec() as a pointer in subject,  a
+        The  subject string is passed to pcre_exec() as a pointer in subject, a
-        length  in  length, and a starting byte offset in startoffset. In UTF-8
+        length (in bytes) in length, and a starting byte offset in startoffset.
-        mode, the byte offset must point to the start  of  a  UTF-8  character.
+        If  this  is  negative  or  greater  than  the  length  of the subject,
-        Unlike  the  pattern string, the subject may contain binary zero bytes.
+        pcre_exec() returns PCRE_ERROR_BADOFFSET. When the starting  offset  is
-        When the starting offset is zero, the search for a match starts at  the
+        zero,  the  search  for a match starts at the beginning of the subject,
-        beginning of the subject, and this is by far the most common case.
+        and this is by far the most common case. In UTF-8 mode, the byte offset
+        must  point  to  the start of a UTF-8 character (or the end of the sub-
+        ject). Unlike the pattern string, the subject may contain  binary  zero
+        bytes.
         A  non-zero  starting offset is useful when searching for another match
         in the same subject by calling pcre_exec() again after a previous  suc-
-Line 1814 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
+Line 2309 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
         rence  of "iss" because it is able to look behind the starting point to
         discover that it is preceded by a letter.
-        If a non-zero starting offset is passed when the pattern  is  anchored,
+        Finding all the matches in a subject is tricky  when  the  pattern  can
+        match an empty string. It is possible to emulate Perl's /g behaviour by
+        first  trying  the  match  again  at  the   same   offset,   with   the
+        PCRE_NOTEMPTY_ATSTART  and  PCRE_ANCHORED  options,  and  then  if that
+        fails, advancing the starting  offset  and  trying  an  ordinary  match
+        again. There is some code that demonstrates how to do this in the pcre-
+        demo sample program. In the most general case, you have to check to see
+        if  the newline convention recognizes CRLF as a newline, and if so, and
+        the current character is CR followed by LF, advance the starting offset
+        by two characters instead of one.
+        If  a  non-zero starting offset is passed when the pattern is anchored,
         one attempt to match at the given offset is made. This can only succeed
-        if the pattern does not require the match to be at  the  start  of  the
+        if  the  pattern  does  not require the match to be at the start of the
         subject.
     How pcre_exec() returns captured substrings
-        In  general, a pattern matches a certain portion of the subject, and in
+        In general, a pattern matches a certain portion of the subject, and  in
-        addition, further substrings from the subject  may  be  picked  out  by
+        addition,  further  substrings  from  the  subject may be picked out by
-        parts  of  the  pattern.  Following the usage in Jeffrey Friedl's book,
+        parts of the pattern. Following the usage  in  Jeffrey  Friedl's  book,
-        this is called "capturing" in what follows, and the  phrase  "capturing
+        this  is  called "capturing" in what follows, and the phrase "capturing
-        subpattern"  is  used for a fragment of a pattern that picks out a sub-
+        subpattern" is used for a fragment of a pattern that picks out  a  sub-
-        string. PCRE supports several other kinds of  parenthesized  subpattern
+        string.  PCRE  supports several other kinds of parenthesized subpattern
         that do not cause substrings to be captured.
-        Captured  substrings are returned to the caller via a vector of integer
+        Captured substrings are returned to the caller via a vector of integers
-        offsets whose address is passed in ovector. The number of  elements  in
+        whose  address is passed in ovector. The number of elements in the vec-
-        the  vector is passed in ovecsize, which must be a non-negative number.
+        tor is passed in ovecsize, which must be a non-negative  number.  Note:
-        Note: this argument is NOT the size of ovector in bytes.
+        this argument is NOT the size of ovector in bytes.
-        The first two-thirds of the vector is used to pass back  captured  sub-
+        The  first  two-thirds of the vector is used to pass back captured sub-
-        strings,  each  substring using a pair of integers. The remaining third
+        strings, each substring using a pair of integers. The  remaining  third
-        of the vector is used as workspace by pcre_exec() while  matching  cap-
+        of  the  vector is used as workspace by pcre_exec() while matching cap-
-        turing  subpatterns, and is not available for passing back information.
+        turing subpatterns, and is not available for passing back  information.
-        The length passed in ovecsize should always be a multiple of three.  If
+        The  number passed in ovecsize should always be a multiple of three. If
         it is not, it is rounded down.
-        When  a  match  is successful, information about captured substrings is
+        When a match is successful, information about  captured  substrings  is
-        returned in pairs of integers, starting at the  beginning  of  ovector,
+        returned  in  pairs  of integers, starting at the beginning of ovector,
-        and  continuing  up  to two-thirds of its length at the most. The first
+        and continuing up to two-thirds of its length at the  most.  The  first
-        element of a pair is set to the offset of the first character in a sub-
+        element  of  each pair is set to the byte offset of the first character
-        string,  and  the  second  is  set to the offset of the first character
+        in a substring, and the second is set to the byte offset of  the  first
-        after the end of a substring. The  first  pair,  ovector[0]  and  ovec-
+        character  after  the end of a substring. Note: these values are always
-        tor[1],  identify  the  portion  of  the  subject string matched by the
+        byte offsets, even in UTF-8 mode. They are not character counts.
-        entire pattern. The next pair is used for the first  capturing  subpat-
-        tern, and so on. The value returned by pcre_exec() is one more than the
+        The first pair of integers, ovector[0]  and  ovector[1],  identify  the
-        highest numbered pair that has been set. For example, if two substrings
+        portion  of  the subject string matched by the entire pattern. The next
-        have  been captured, the returned value is 3. If there are no capturing
+        pair is used for the first capturing subpattern, and so on.  The  value
-        subpatterns, the return value from a successful match is 1,  indicating
+        returned by pcre_exec() is one more than the highest numbered pair that
-        that just the first pair of offsets has been set.
+        has been set.  For example, if two substrings have been  captured,  the
+        returned  value is 3. If there are no capturing subpatterns, the return
+        value from a successful match is 1, indicating that just the first pair
+        of offsets has been set.
         If a capturing subpattern is matched repeatedly, it is the last portion
         of the string that it matched that is returned.
         If the vector is too small to hold all the captured substring  offsets,
         it is used as far as possible (up to two-thirds of its length), and the
-        function returns a value of zero. In particular, if the substring  off-
+        function returns a value of zero. If the substring offsets are  not  of
-        sets are not of interest, pcre_exec() may be called with ovector passed
+        interest,  pcre_exec()  may  be  called with ovector passed as NULL and
-        as NULL and ovecsize as zero. However, if  the  pattern  contains  back
+        ovecsize as zero. However, if the pattern contains back references  and
-        references  and  the  ovector is not big enough to remember the related
+        the  ovector is not big enough to remember the related substrings, PCRE
-        substrings, PCRE has to get additional memory for use during  matching.
+        has to get additional memory for use during matching. Thus it  is  usu-
-        Thus it is usually advisable to supply an ovector.
+        ally advisable to supply an ovector.
-        The  pcre_info()  function  can  be used to find out how many capturing
+        The pcre_fullinfo() function can be used to find out how many capturing
         subpatterns there are in a compiled  pattern.  The  smallest  size  for
         ovector  that  will allow for n captured substrings, in addition to the
         offsets of the substring matched by the whole pattern, is (n+1)*3.
-Line 1883 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
+Line 2392 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
         expression are also set to -1. For example,  if  the  string  "abc"  is
         matched  against the pattern (abc)(x(yz)?)? subpatterns 2 and 3 are not
         matched. The return from the function is 2, because  the  highest  used
-        capturing subpattern number is 1. However, you can refer to the offsets
+        capturing  subpattern  number  is 1, and the offsets for for the second
-        for the second and third capturing subpatterns if  you  wish  (assuming
+        and third capturing subpatterns (assuming the vector is  large  enough,
-        the vector is large enough, of course).
+        of course) are set to -1.
+        Note: Elements of ovector that do not correspond to capturing parenthe-
+        ses in the pattern are never changed. That is, if a pattern contains  n
+        capturing parentheses, no more than ovector[0] to ovector[2n+1] are set
+        by pcre_exec(). The other elements retain whatever values  they  previ-
+        ously had.
         Some  convenience  functions  are  provided for extracting the captured
         substrings as separate strings. These are described below.
-Line 1930 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
+Line 2445 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
         purpose.  If the call via pcre_malloc() fails, this error is given. The
         memory is automatically freed at the end of matching.
+        This error is also given if pcre_stack_malloc() fails  in  pcre_exec().
+        This  can happen only when PCRE has been compiled with --disable-stack-
+        for-recursion.
           PCRE_ERROR_NOSUBSTRING    (-7)
         This error is used by the pcre_copy_substring(),  pcre_get_substring(),
-Line 1951 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
+Line 2470 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
           PCRE_ERROR_BADUTF8        (-10)
         A string that contains an invalid UTF-8 byte sequence was passed  as  a
-        subject.
+        subject,  and the PCRE_NO_UTF8_CHECK option was not set. If the size of
+        the output vector (ovecsize) is at least 2,  the  byte  offset  to  the
+        start  of  the  the invalid UTF-8 character is placed in the first ele-
+        ment, and a reason code is placed in the  second  element.  The  reason
+        codes are listed in the following section.  For backward compatibility,
+        if PCRE_PARTIAL_HARD is set and the problem is a truncated UTF-8  char-
+        acter   at   the   end   of   the   subject  (reason  codes  1  to  5),
+        PCRE_ERROR_SHORTUTF8 is returned instead of PCRE_ERROR_BADUTF8.
           PCRE_ERROR_BADUTF8_OFFSET (-11)
-        The UTF-8 byte sequence that was passed as a subject was valid, but the
+        The UTF-8 byte sequence that was passed as a subject  was  checked  and
+        found  to be valid (the PCRE_NO_UTF8_CHECK option was not set), but the
         value of startoffset did not point to the beginning of a UTF-8  charac-
-        ter.
+        ter or the end of the subject.
           PCRE_ERROR_PARTIAL        (-12)
-Line 1966 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
+Line 2493 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
           PCRE_ERROR_BADPARTIAL     (-13)
-        The PCRE_PARTIAL option was used with  a  compiled  pattern  containing
+        This code is no longer in  use.  It  was  formerly  returned  when  the
-        items  that are not supported for partial matching. See the pcrepartial
+        PCRE_PARTIAL  option  was used with a compiled pattern containing items
-        documentation for details of partial matching.
+        that were  not  supported  for  partial  matching.  From  release  8.00
+        onwards, there are no restrictions on partial matching.
           PCRE_ERROR_INTERNAL       (-14)
-        An unexpected internal error has occurred. This error could  be  caused
+        An  unexpected  internal error has occurred. This error could be caused
         by a bug in PCRE or by overwriting of the compiled pattern.
           PCRE_ERROR_BADCOUNT       (-15)
-        This  error is given if the value of the ovecsize argument is negative.
+        This error is given if the value of the ovecsize argument is negative.
           PCRE_ERROR_RECURSIONLIMIT (-21)
-Line 1985 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
+Line 2513 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
         field  in  a  pcre_extra  structure (or defaulted) was reached. See the
         description above.
-          PCRE_ERROR_NULLWSLIMIT    (-22)
-        When a group that can match an empty  substring  is  repeated  with  an
-        unbounded  upper  limit, the subject position at the start of the group
-        must be remembered, so that a test for an empty string can be made when
-        the  end  of the group is reached. Some workspace is required for this;
-        if it runs out, this error is given.
           PCRE_ERROR_BADNEWLINE     (-23)
         An invalid combination of PCRE_NEWLINE_xxx options was given.
-        Error numbers -16 to -20 are not used by pcre_exec().
+          PCRE_ERROR_BADOFFSET      (-24)
+        The value of startoffset was negative or greater than the length of the
+        subject, that is, the value in length.
+          PCRE_ERROR_SHORTUTF8      (-25)
+        This  error  is returned instead of PCRE_ERROR_BADUTF8 when the subject
+        string ends with a truncated UTF-8 character and the  PCRE_PARTIAL_HARD
+        option  is  set.   Information  about  the  failure  is returned as for
+        PCRE_ERROR_BADUTF8. It is in fact sufficient to detect this  case,  but
+        this  special error code for PCRE_PARTIAL_HARD precedes the implementa-
+        tion of returned information; it is retained for backwards  compatibil-
+        ity.
+          PCRE_ERROR_RECURSELOOP    (-26)
+        This error is returned when pcre_exec() detects a recursion loop within
+        the pattern. Specifically, it means that either the whole pattern or  a
+        subpattern  has been called recursively for the second time at the same
+        position in the subject string. Some simple patterns that might do this
+        are  detected  and faulted at compile time, but more complicated cases,
+        in particular mutual recursions between two different subpatterns, can-
+        not be detected until run time.
+        Error numbers -16 to -20 and -22 are not used by pcre_exec().
+    Reason codes for invalid UTF-8 strings
+        When pcre_exec() returns either PCRE_ERROR_BADUTF8 or PCRE_ERROR_SHORT-
+        UTF8, and the size of the output vector (ovecsize) is at least  2,  the
+        offset  of  the  start  of the invalid UTF-8 character is placed in the
+        first output vector element (ovector[0]) and a reason code is placed in
+        the  second  element  (ovector[1]). The reason codes are given names in
+        the pcre.h header file:
+          PCRE_UTF8_ERR1
+          PCRE_UTF8_ERR2
+          PCRE_UTF8_ERR3
+          PCRE_UTF8_ERR4
+          PCRE_UTF8_ERR5
+        The string ends with a truncated UTF-8 character;  the  code  specifies
+        how  many bytes are missing (1 to 5). Although RFC 3629 restricts UTF-8
+        characters to be no longer than 4 bytes, the  encoding  scheme  (origi-
+        nally  defined  by  RFC  2279)  allows  for  up to 6 bytes, and this is
+        checked first; hence the possibility of 4 or 5 missing bytes.
+          PCRE_UTF8_ERR6
+          PCRE_UTF8_ERR7
+          PCRE_UTF8_ERR8
+          PCRE_UTF8_ERR9
+          PCRE_UTF8_ERR10
+        The two most significant bits of the 2nd, 3rd, 4th, 5th, or 6th byte of
+        the  character  do  not have the binary value 0b10 (that is, either the
+        most significant bit is 0, or the next bit is 1).
+          PCRE_UTF8_ERR11
+          PCRE_UTF8_ERR12
+        A character that is valid by the RFC 2279 rules is either 5 or 6  bytes
+        long; these code points are excluded by RFC 3629.
+          PCRE_UTF8_ERR13
+        A  4-byte character has a value greater than 0x10fff; these code points
+        are excluded by RFC 3629.
+          PCRE_UTF8_ERR14
+        A 3-byte character has a value in the  range  0xd800  to  0xdfff;  this
+        range  of code points are reserved by RFC 3629 for use with UTF-16, and
+        so are excluded from UTF-8.
+          PCRE_UTF8_ERR15
+          PCRE_UTF8_ERR16
+          PCRE_UTF8_ERR17
+          PCRE_UTF8_ERR18
+          PCRE_UTF8_ERR19
+        A 2-, 3-, 4-, 5-, or 6-byte character is "overlong", that is, it  codes
+        for  a  value that can be represented by fewer bytes, which is invalid.
+        For example, the two bytes 0xc0, 0xae give the value 0x2e,  whose  cor-
+        rect coding uses just one byte.
+          PCRE_UTF8_ERR20
+        The two most significant bits of the first byte of a character have the
+        binary value 0b10 (that is, the most significant bit is 1 and the  sec-
+        ond  is  0). Such a byte can only validly occur as the second or subse-
+        quent byte of a multi-byte character.
+          PCRE_UTF8_ERR21
+        The first byte of a character has the value 0xfe or 0xff. These  values
+        can never occur in a valid UTF-8 string.
  EXTRACTING CAPTURED SUBSTRINGS BY NUMBER
-Line 2013 
 EXTRACTING CAPTURED SUBSTRINGS BY NUMBER
+Line 2629 
 EXTRACTING CAPTURED SUBSTRINGS BY NUMBER
         int pcre_get_substring_list(const char *subject,
              int *ovector, int stringcount, const char ***listptr);
-        Captured substrings can be  accessed  directly  by  using  the  offsets
+        Captured  substrings  can  be  accessed  directly  by using the offsets
-        returned  by  pcre_exec()  in  ovector.  For convenience, the functions
+        returned by pcre_exec() in  ovector.  For  convenience,  the  functions
         pcre_copy_substring(),    pcre_get_substring(),    and    pcre_get_sub-
-        string_list()  are  provided for extracting captured substrings as new,
+        string_list() are provided for extracting captured substrings  as  new,
-        separate, zero-terminated strings. These functions identify  substrings
+        separate,  zero-terminated strings. These functions identify substrings
-        by  number.  The  next section describes functions for extracting named
+        by number. The next section describes functions  for  extracting  named
         substrings.
-        A substring that contains a binary zero is correctly extracted and  has
+        A  substring that contains a binary zero is correctly extracted and has
-        a  further zero added on the end, but the result is not, of course, a C
+        a further zero added on the end, but the result is not, of course, a  C
-        string.  However, you can process such a string  by  referring  to  the
+        string.   However,  you  can  process such a string by referring to the
-        length  that  is  returned  by  pcre_copy_substring() and pcre_get_sub-
+        length that is  returned  by  pcre_copy_substring()  and  pcre_get_sub-
         string().  Unfortunately, the interface to pcre_get_substring_list() is
-        not  adequate for handling strings containing binary zeros, because the
+        not adequate for handling strings containing binary zeros, because  the
         end of the final string is not independently indicated.
-        The first three arguments are the same for all  three  of  these  func-
+        The  first  three  arguments  are the same for all three of these func-
-        tions:  subject  is  the subject string that has just been successfully
+        tions: subject is the subject string that has  just  been  successfully
         matched, ovector is a pointer to the vector of integer offsets that was
         passed to pcre_exec(), and stringcount is the number of substrings that
-        were captured by the match, including the substring  that  matched  the
+        were  captured  by  the match, including the substring that matched the
         entire regular expression. This is the value returned by pcre_exec() if
-        it is greater than zero. If pcre_exec() returned zero, indicating  that
+        it  is greater than zero. If pcre_exec() returned zero, indicating that
-        it  ran out of space in ovector, the value passed as stringcount should
+        it ran out of space in ovector, the value passed as stringcount  should
         be the number of elements in the vector divided by three.
-        The functions pcre_copy_substring() and pcre_get_substring() extract  a
+        The  functions pcre_copy_substring() and pcre_get_substring() extract a
-        single  substring,  whose  number  is given as stringnumber. A value of
+        single substring, whose number is given as  stringnumber.  A  value  of
-        zero extracts the substring that matched the  entire  pattern,  whereas
+        zero  extracts  the  substring that matched the entire pattern, whereas
-        higher  values  extract  the  captured  substrings.  For pcre_copy_sub-
+        higher values  extract  the  captured  substrings.  For  pcre_copy_sub-
-        string(), the string is placed in buffer,  whose  length  is  given  by
+        string(),  the  string  is  placed  in buffer, whose length is given by
-        buffersize,  while  for  pcre_get_substring()  a new block of memory is
+        buffersize, while for pcre_get_substring() a new  block  of  memory  is
-        obtained via pcre_malloc, and its address is  returned  via  stringptr.
+        obtained  via  pcre_malloc,  and its address is returned via stringptr.
-        The  yield  of  the function is the length of the string, not including
+        The yield of the function is the length of the  string,  not  including
         the terminating zero, or one of these error codes:
           PCRE_ERROR_NOMEMORY       (-6)
-        The buffer was too small for pcre_copy_substring(), or the  attempt  to
+        The  buffer  was too small for pcre_copy_substring(), or the attempt to
         get memory failed for pcre_get_substring().
           PCRE_ERROR_NOSUBSTRING    (-7)
         There is no substring whose number is stringnumber.
-        The  pcre_get_substring_list()  function  extracts  all  available sub-
+        The pcre_get_substring_list()  function  extracts  all  available  sub-
-        strings and builds a list of pointers to them. All this is  done  in  a
+        strings  and  builds  a list of pointers to them. All this is done in a
         single block of memory that is obtained via pcre_malloc. The address of
-        the memory block is returned via listptr, which is also  the  start  of
+        the  memory  block  is returned via listptr, which is also the start of
-        the  list  of  string pointers. The end of the list is marked by a NULL
+        the list of string pointers. The end of the list is marked  by  a  NULL
-        pointer. The yield of the function is zero if all  went  well,  or  the
+        pointer.  The  yield  of  the function is zero if all went well, or the
         error code
           PCRE_ERROR_NOMEMORY       (-6)
         if the attempt to get the memory block failed.
-        When  any of these functions encounter a substring that is unset, which
+        When any of these functions encounter a substring that is unset,  which
-        can happen when capturing subpattern number n+1 matches  some  part  of
+        can  happen  when  capturing subpattern number n+1 matches some part of
-        the  subject, but subpattern n has not been used at all, they return an
+        the subject, but subpattern n has not been used at all, they return  an
         empty string. This can be distinguished from a genuine zero-length sub-
-        string  by inspecting the appropriate offset in ovector, which is nega-
+        string by inspecting the appropriate offset in ovector, which is  nega-
         tive for unset substrings.
-        The two convenience functions pcre_free_substring() and  pcre_free_sub-
+        The  two convenience functions pcre_free_substring() and pcre_free_sub-
-        string_list()  can  be  used  to free the memory returned by a previous
+        string_list() can be used to free the memory  returned  by  a  previous
         call  of  pcre_get_substring()  or  pcre_get_substring_list(),  respec-
-        tively.  They  do  nothing  more  than  call the function pointed to by
+        tively. They do nothing more than  call  the  function  pointed  to  by
-        pcre_free, which of course could be called directly from a  C  program.
+        pcre_free,  which  of course could be called directly from a C program.
-        However,  PCRE is used in some situations where it is linked via a spe-
+        However, PCRE is used in some situations where it is linked via a  spe-
-        cial  interface  to  another  programming  language  that  cannot   use
+        cial   interface  to  another  programming  language  that  cannot  use
-        pcre_free  directly;  it is for these cases that the functions are pro-
+        pcre_free directly; it is for these cases that the functions  are  pro-
         vided.
-Line 2103 
 EXTRACTING CAPTURED SUBSTRINGS BY NAME
+Line 2719 
 EXTRACTING CAPTURED SUBSTRINGS BY NAME
              int stringcount, const char *stringname,
              const char **stringptr);
-        To extract a substring by name, you first have to find associated  num-
+        To  extract a substring by name, you first have to find associated num-
         ber.  For example, for this pattern
           (a+)b(?<xxx>\d+)...
-Line 2112 
 EXTRACTING CAPTURED SUBSTRINGS BY NAME
+Line 2728 
 EXTRACTING CAPTURED SUBSTRINGS BY NAME
         be unique (PCRE_DUPNAMES was not set), you can find the number from the
         name by calling pcre_get_stringnumber(). The first argument is the com-
         piled pattern, and the second is the name. The yield of the function is
-        the  subpattern  number,  or PCRE_ERROR_NOSUBSTRING (-7) if there is no
+        the subpattern number, or PCRE_ERROR_NOSUBSTRING (-7) if  there  is  no
         subpattern of that name.
         Given the number, you can extract the substring directly, or use one of
         the functions described in the previous section. For convenience, there
         are also two functions that do the whole job.
-        Most   of   the   arguments    of    pcre_copy_named_substring()    and
+        Most    of    the    arguments   of   pcre_copy_named_substring()   and
-        pcre_get_named_substring()  are  the  same  as  those for the similarly
+        pcre_get_named_substring() are the same  as  those  for  the  similarly
-        named functions that extract by number. As these are described  in  the
+        named  functions  that extract by number. As these are described in the
-        previous  section,  they  are not re-described here. There are just two
+        previous section, they are not re-described here. There  are  just  two
         differences:
-        First, instead of a substring number, a substring name is  given.  Sec-
+        First,  instead  of a substring number, a substring name is given. Sec-
         ond, there is an extra argument, given at the start, which is a pointer
-        to the compiled pattern. This is needed in order to gain access to  the
+        to  the compiled pattern. This is needed in order to gain access to the
         name-to-number translation table.
-        These  functions call pcre_get_stringnumber(), and if it succeeds, they
+        These functions call pcre_get_stringnumber(), and if it succeeds,  they
-        then call pcre_copy_substring() or pcre_get_substring(),  as  appropri-
+        then  call  pcre_copy_substring() or pcre_get_substring(), as appropri-
-        ate.
+        ate. NOTE: If PCRE_DUPNAMES is set and there are duplicate  names,  the
+        behaviour may not be what you want (see the next section).
+        Warning: If the pattern uses the (?| feature to set up multiple subpat-
+        terns with the same number, as described in the  section  on  duplicate
+        subpattern  numbers  in  the  pcrepattern page, you cannot use names to
+        distinguish the different subpatterns, because names are  not  included
+        in  the compiled code. The matching process uses only numbers. For this
+        reason, the use of different names for subpatterns of the  same  number
+        causes an error at compile time.
  DUPLICATE SUBPATTERN NAMES
-Line 2141 
 DUPLICATE SUBPATTERN NAMES
+Line 2766 
 DUPLICATE SUBPATTERN NAMES
              const char *name, char **first, char **last);
         When  a  pattern  is  compiled with the PCRE_DUPNAMES option, names for
-        subpatterns are not required to  be  unique.  Normally,  patterns  with
+        subpatterns are not required to be unique. (Duplicate names are  always
-        duplicate  names  are such that in any one match, only one of the named
+        allowed  for subpatterns with the same number, created by using the (?|
-        subpatterns participates. An example is shown in the pcrepattern  docu-
+        feature. Indeed, if such subpatterns are named, they  are  required  to
-        mentation. When duplicates are present, pcre_copy_named_substring() and
+        use the same names.)
+        Normally, patterns with duplicate names are such that in any one match,
+        only one of the named subpatterns participates. An example is shown  in
+        the pcrepattern documentation.
+        When    duplicates   are   present,   pcre_copy_named_substring()   and
         pcre_get_named_substring() return the first substring corresponding  to
-        the  given  name  that  is  set.  If  none  are set, an empty string is
+        the  given  name  that  is set. If none are set, PCRE_ERROR_NOSUBSTRING
-        returned.  The pcre_get_stringnumber() function returns one of the num-
+        (-7) is returned; no  data  is  returned.  The  pcre_get_stringnumber()
-        bers  that are associated with the name, but it is not defined which it
+        function  returns one of the numbers that are associated with the name,
-        is.
+        but it is not defined which it is.
         If you want to get full details of all captured substrings for a  given
         name,  you  must  use  the pcre_get_stringtable_entries() function. The
-Line 2159 
 DUPLICATE SUBPATTERN NAMES
+Line 2790 
 DUPLICATE SUBPATTERN NAMES
         the  name-to-number  table  for  the  given  name.  The function itself
         returns the length of each entry,  or  PCRE_ERROR_NOSUBSTRING  (-7)  if
         there  are none. The format of the table is described above in the sec-
-        tion entitled Information about a  pattern.   Given  all  the  relevant
+        tion entitled Information about a pattern above.  Given all  the  rele-
-        entries  for the name, you can extract each of their numbers, and hence
+        vant  entries  for the name, you can extract each of their numbers, and
-        the captured data, if any.
+        hence the captured data, if any.
  FINDING ALL POSSIBLE MATCHES
-Line 2195 
 MATCHING A PATTERN: THE ALTERNATIVE FUNC
+Line 2826 
 MATCHING A PATTERN: THE ALTERNATIVE FUNC
         characteristics to the normal algorithm, and  is  not  compatible  with
         Perl.  Some  of the features of PCRE patterns are not supported. Never-
         theless, there are times when this kind of matching can be useful.  For
-        a discussion of the two matching algorithms, see the pcrematching docu-
+        a  discussion  of  the  two matching algorithms, and a list of features
-        mentation.
+        that pcre_dfa_exec() does not support, see the pcrematching  documenta-
+        tion.
-        The arguments for the pcre_dfa_exec() function  are  the  same  as  for
+        The  arguments  for  the  pcre_dfa_exec()  function are the same as for
         pcre_exec(), plus two extras. The ovector argument is used in a differ-
-        ent way, and this is described below. The other  common  arguments  are
+        ent  way,  and  this is described below. The other common arguments are
-        used  in  the  same way as for pcre_exec(), so their description is not
+        used in the same way as for pcre_exec(), so their  description  is  not
         repeated here.
-        The two additional arguments provide workspace for  the  function.  The
+        The  two  additional  arguments provide workspace for the function. The
-        workspace  vector  should  contain at least 20 elements. It is used for
+        workspace vector should contain at least 20 elements. It  is  used  for
         keeping  track  of  multiple  paths  through  the  pattern  tree.  More
-        workspace  will  be  needed for patterns and subjects where there are a
+        workspace will be needed for patterns and subjects where  there  are  a
         lot of potential matches.
         Here is an example of a simple call to pcre_dfa_exec():
-Line 2229 
 MATCHING A PATTERN: THE ALTERNATIVE FUNC
+Line 2861 
 MATCHING A PATTERN: THE ALTERNATIVE FUNC
     Option bits for pcre_dfa_exec()
-        The unused bits of the options argument  for  pcre_dfa_exec()  must  be
+        The  unused  bits  of  the options argument for pcre_dfa_exec() must be
-        zero.  The  only  bits  that  may  be  set are PCRE_ANCHORED, PCRE_NEW-
+        zero. The only bits  that  may  be  set  are  PCRE_ANCHORED,  PCRE_NEW-
-        LINE_xxx, PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY,  PCRE_NO_UTF8_CHECK,
+        LINE_xxx,        PCRE_NOTBOL,        PCRE_NOTEOL,        PCRE_NOTEMPTY,
-        PCRE_PARTIAL, PCRE_DFA_SHORTEST, and PCRE_DFA_RESTART. All but the last
+        PCRE_NOTEMPTY_ATSTART,      PCRE_NO_UTF8_CHECK,       PCRE_BSR_ANYCRLF,
-        three of these are the same as for pcre_exec(), so their description is
+        PCRE_BSR_UNICODE,  PCRE_NO_START_OPTIMIZE, PCRE_PARTIAL_HARD, PCRE_PAR-
-        not repeated here.
+        TIAL_SOFT, PCRE_DFA_SHORTEST, and PCRE_DFA_RESTART.  All but  the  last
+        four  of  these  are  exactly  the  same  as  for pcre_exec(), so their
-          PCRE_PARTIAL
+        description is not repeated here.
-        This  has  the  same general effect as it does for pcre_exec(), but the
+          PCRE_PARTIAL_HARD
-        details  are  slightly  different.  When  PCRE_PARTIAL   is   set   for
+          PCRE_PARTIAL_SOFT
-        pcre_dfa_exec(),  the  return code PCRE_ERROR_NOMATCH is converted into
-        PCRE_ERROR_PARTIAL if the end of the subject  is  reached,  there  have
+        These have the same general effect as they do for pcre_exec(), but  the
-        been no complete matches, but there is still at least one matching pos-
+        details  are  slightly  different.  When  PCRE_PARTIAL_HARD  is set for
-        sibility. The portion of the string that provided the partial match  is
+        pcre_dfa_exec(), it returns PCRE_ERROR_PARTIAL if the end of  the  sub-
-        set as the first matching string.
+        ject  is  reached  and there is still at least one matching possibility
+        that requires additional characters. This happens even if some complete
+        matches have also been found. When PCRE_PARTIAL_SOFT is set, the return
+        code PCRE_ERROR_NOMATCH is converted into PCRE_ERROR_PARTIAL if the end
+        of  the  subject  is  reached, there have been no complete matches, but
+        there is still at least one matching possibility. The  portion  of  the
+        string  that  was inspected when the longest partial match was found is
+        set as the first matching string  in  both  cases.   There  is  a  more
+        detailed  discussion  of partial and multi-segment matching, with exam-
+        ples, in the pcrepartial documentation.
           PCRE_DFA_SHORTEST
-        Setting  the  PCRE_DFA_SHORTEST option causes the matching algorithm to
+        Setting the PCRE_DFA_SHORTEST option causes the matching  algorithm  to
         stop as soon as it has found one match. Because of the way the alterna-
-        tive  algorithm  works, this is necessarily the shortest possible match
+        tive algorithm works, this is necessarily the shortest  possible  match
         at the first possible matching point in the subject string.
           PCRE_DFA_RESTART
-        When pcre_dfa_exec()  is  called  with  the  PCRE_PARTIAL  option,  and
+        When pcre_dfa_exec() returns a partial match, it is possible to call it
-        returns  a  partial  match, it is possible to call it again, with addi-
+        again, with additional subject characters, and have  it  continue  with
-        tional subject characters, and have it continue with  the  same  match.
+        the  same match. The PCRE_DFA_RESTART option requests this action; when
-        The  PCRE_DFA_RESTART  option requests this action; when it is set, the
+        it is set, the workspace and wscount options must  reference  the  same
-        workspace and wscount options must reference the same vector as  before
+        vector  as  before  because data about the match so far is left in them
-        because  data  about  the  match so far is left in them after a partial
+        after a partial match. There is more discussion of this facility in the
-        match. There is more discussion of this  facility  in  the  pcrepartial
+        pcrepartial documentation.
-        documentation.
     Successful returns from pcre_dfa_exec()
-Line 2339 
 MATCHING A PATTERN: THE ALTERNATIVE FUNC
+Line 2979 
 MATCHING A PATTERN: THE ALTERNATIVE FUNC
  SEE ALSO
         pcrebuild(3), pcrecallout(3), pcrecpp(3)(3), pcrematching(3),  pcrepar-
-        tial(3),  pcreposix(3), pcreprecompile(3), pcresample(3), pcrestack(3).
+        tial(3), pcreposix(3), pcreprecompile(3), pcresample(3), pcrestack(3).
  AUTHOR
-Line 2351 
 AUTHOR
+Line 2991 
 AUTHOR
  REVISION
-        Last updated: 06 March 2007
+        Last updated: 28 July 2011
-        Copyright (c) 1997-2007 University of Cambridge.
+        Copyright (c) 1997-2011 University of Cambridge.
  ------------------------------------------------------------------------------
-Line 2379 
 PCRE CALLOUTS
+Line 3019 
 PCRE CALLOUTS
         default value is zero.  For  example,  this  pattern  has  two  callout
         points:
-          (?C1)eabc(?C2)def
+          (?C1)abc(?C2)def
-        If  the  PCRE_AUTO_CALLOUT  option  bit  is  set when pcre_compile() is
+        If  the  PCRE_AUTO_CALLOUT  option  bit  is  set when pcre_compile() or
-        called, PCRE automatically  inserts  callouts,  all  with  number  255,
+        pcre_compile2() is called, PCRE  automatically  inserts  callouts,  all
-        before  each  item in the pattern. For example, if PCRE_AUTO_CALLOUT is
+        with  number  255,  before  each  item  in the pattern. For example, if
-        used with the pattern
+        PCRE_AUTO_CALLOUT is used with the pattern
           A(\d{2}|--)
-Line 2403 
 PCRE CALLOUTS
+Line 3043 
 PCRE CALLOUTS
  MISSING CALLOUTS
         You  should  be  aware  that,  because of optimizations in the way PCRE
-        matches patterns, callouts sometimes do not happen. For example, if the
+        matches patterns by default, callouts  sometimes  do  not  happen.  For
-        pattern is
+        example, if the pattern is
           ab(?C4)cd
-Line 2413 
 MISSING CALLOUTS
+Line 3053 
 MISSING CALLOUTS
         ever  start,  and  the  callout is never reached. However, with "abyd",
         though the result is still no match, the callout is obeyed.
+        If the pattern is studied, PCRE knows the minimum length of a  matching
+        string,  and will immediately give a "no match" return without actually
+        running a match if the subject is not long enough, or,  for  unanchored
+        patterns, if it has been scanned far enough.
+        You  can disable these optimizations by passing the PCRE_NO_START_OPTI-
+        MIZE option to pcre_compile(), pcre_exec(), or pcre_dfa_exec(),  or  by
+        starting the pattern with (*NO_START_OPT). This slows down the matching
+        process, but does ensure that callouts such as the  example  above  are
+        obeyed.
  THE CALLOUT INTERFACE
-        During matching, when PCRE reaches a callout point, the external  func-
+        During  matching, when PCRE reaches a callout point, the external func-
-        tion  defined by pcre_callout is called (if it is set). This applies to
+        tion defined by pcre_callout is called (if it is set). This applies  to
-        both the pcre_exec() and the pcre_dfa_exec()  matching  functions.  The
+        both  the  pcre_exec()  and the pcre_dfa_exec() matching functions. The
-        only  argument  to  the callout function is a pointer to a pcre_callout
+        only argument to the callout function is a pointer  to  a  pcre_callout
         block. This structure contains the following fields:
-          int          version;
+          int         version;
-          int          callout_number;
+          int         callout_number;
-          int         *offset_vector;
+          int        *offset_vector;
-          const char  *subject;
+          const char *subject;
-          int          subject_length;
+          int         subject_length;
-          int          start_match;
+          int         start_match;
-          int          current_position;
+          int         current_position;
-          int          capture_top;
+          int         capture_top;
-          int          capture_last;
+          int         capture_last;
-          void        *callout_data;
+          void       *callout_data;
-          int          pattern_position;
+          int         pattern_position;
-          int          next_item_length;
+          int         next_item_length;
+          const unsigned char *mark;
-        The version field is an integer containing the version  number  of  the
-        block  format. The initial version was 0; the current version is 1. The
+        The  version  field  is an integer containing the version number of the
-        version number will change again in future  if  additional  fields  are
+        block format. The initial version was 0; the current version is 2.  The
+        version  number  will  change  again in future if additional fields are
         added, but the intention is never to remove any of the existing fields.
         The callout_number field contains the number of the  callout,  as  com-
-Line 2454 
 THE CALLOUT INTERFACE
+Line 3106 
 THE CALLOUT INTERFACE
         The subject and subject_length fields contain copies of the values that
         were passed to pcre_exec().
-        The start_match field contains the offset within the subject  at  which
+        The start_match field normally contains the offset within  the  subject
-        the  current match attempt started. If the pattern is not anchored, the
+        at  which  the  current  match  attempt started. However, if the escape
-        callout function may be called several times from the same point in the
+        sequence \K has been encountered, this value is changed to reflect  the
-        pattern for different starting points in the subject.
+        modified  starting  point.  If the pattern is not anchored, the callout
+        function may be called several times from the same point in the pattern
+        for different starting points in the subject.
         The  current_position  field  contains the offset within the subject of
         the current match pointer.
-Line 2494 
 THE CALLOUT INTERFACE
+Line 3148 
 THE CALLOUT INTERFACE
         in  distinguishing between different automatic callouts, which all have
         the same callout number. However, they are set for all callouts.
+        The mark field is present from version 2 of the pcre_callout structure.
+        In  callouts  from pcre_exec() it contains a pointer to the zero-termi-
+        nated name of the most recently passed (*MARK) item in  the  match,  or
+        NULL if there are no (*MARK)s in the current matching path. In callouts
+        from pcre_dfa_exec() this field always contains NULL.
  RETURN VALUES
-Line 2502 
 RETURN VALUES
+Line 3162 
 RETURN VALUES
         zero, matching fails at the current point, but  the  testing  of  other
         matching possibilities goes ahead, just as if a lookahead assertion had
         failed. If the value is less than zero, the  match  is  abandoned,  and
-        pcre_exec() (or pcre_dfa_exec()) returns the negative value.
+        pcre_exec() or pcre_dfa_exec() returns the negative value.
         Negative   values   should   normally   be   chosen  from  the  set  of
         PCRE_ERROR_xxx values. In particular, PCRE_ERROR_NOMATCH forces a stan-
-Line 2520 
 AUTHOR
+Line 3180 
 AUTHOR
  REVISION
-        Last updated: 06 March 2007
+        Last updated: 31 July 2011
-        Copyright (c) 1997-2007 University of Cambridge.
+        Copyright (c) 1997-2011 University of Cambridge.
  ------------------------------------------------------------------------------
-Line 2535 
 NAME
+Line 3195 
 NAME
  DIFFERENCES BETWEEN PCRE AND PERL
         This  document describes the differences in the ways that PCRE and Perl
-        handle regular expressions. The differences described here  are  mainly
+        handle regular expressions. The differences  described  here  are  with
-        with  respect  to  Perl 5.8, though PCRE version 7.0 contains some fea-
+        respect to Perl versions 5.10 and above.
-        tures that are expected to be in the forthcoming Perl 5.10.
-. PCRE has only a subset of Perl's UTF-8 and Unicode support.  Details
+.  PCRE has only a subset of Perl's UTF-8 and Unicode support. Details
-        of  what  it does have are given in the section on UTF-8 support in the
+        of what it does have are given in the section on UTF-8 support  in  the
         main pcre page.
-. PCRE does not allow repeat quantifiers on lookahead assertions. Perl
+. PCRE allows repeat quantifiers only on parenthesized assertions, but
-        permits  them,  but they do not mean what you might think. For example,
+        they do not mean what you might think. For example, (?!a){3}  does  not
-        (?!a){3} does not assert that the next three characters are not "a". It
+        assert that the next three characters are not "a". It just asserts that
-        just asserts that the next character is not "a" three times.
+        the next character is not "a" three times (in principle: PCRE optimizes
+        this to run the assertion just once). Perl allows repeat quantifiers on
-.  Capturing  subpatterns  that occur inside negative lookahead asser-
+        other assertions such as \b, but these do not seem to have any use.
-        tions are counted, but their entries in the offsets  vector  are  never
-        set.  Perl sets its numerical variables from any such patterns that are
+. 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
+        ing), but only if the negative lookahead assertion  contains  just  one
         branch.
-. Though binary zero characters are supported in the  subject  string,
+.  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.
-.  The  following Perl escape sequences are not supported: \l, \u, \L,
+. The following Perl escape sequences are not supported: \l,  \u,  \L,
-        \U, and \N. In fact these are implemented by Perl's general string-han-
+        \U,  and  \N when followed by a character name or Unicode value. (\N on
-        dling  and are not part of its pattern matching engine. If any of these
+        its own, matching a non-newline character, is supported.) In fact these
-        are encountered by PCRE, an error is generated.
+        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,
-. The Perl escape sequences \p, \P, and \X are supported only if  PCRE
+        an error is generated.
-        is  built  with Unicode character property support. The properties that
-        can be tested with \p and \P are limited to the general category  prop-
+.  The Perl escape sequences \p, \P, and \X are supported only if PCRE
-        erties  such  as  Lu and Nd, script names such as Greek or Han, and the
+        is built with Unicode character property support. The  properties  that
-        derived properties Any and L&.
+        can  be tested with \p and \P are limited to the general category prop-
+        erties such as Lu and Nd, script names such as Greek or  Han,  and  the
+        derived  properties  Any  and  L&. PCRE does support the Cs (surrogate)
+        property, which Perl does not; the  Perl  documentation  says  "Because
+        Perl hides the need for the user to understand the internal representa-
+        tion of Unicode characters, there is no need to implement the  somewhat
+        messy concept of surrogates."
+.  PCRE implements a simpler version of \X than Perl, which changed to
+        make \X match what Unicode calls an "extended grapheme  cluster".  This
+        is  more  complicated  than an extended Unicode sequence, which is what
+        PCRE matches.
 . 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
-Line 2587 
 DIFFERENCES BETWEEN PCRE AND PERL
+Line 3259 
 DIFFERENCES BETWEEN PCRE AND PERL
         The \Q...\E sequence is recognized both inside  and  outside  character
         classes.
 . Fairly obviously, PCRE does not support the (?{code}) and (??{code})
         constructions. However, there is support for recursive  patterns.  This
-        is  not available in Perl 5.8, but will be in Perl 5.10. Also, the PCRE
+        is  not  available  in Perl 5.8, but it is in Perl 5.10. Also, the PCRE
         "callout" feature allows an external function to be called during  pat-
         tern matching. See the pcrecallout documentation for details.
-.  Subpatterns  that  are  called  recursively or as "subroutines" are
+.  Subpatterns  that  are  called recursively or as "subroutines" are
         always treated as atomic groups in  PCRE.  This  is  like  Python,  but
-        unlike Perl.
+        unlike  Perl. There is a discussion of an example that explains this in
+        more detail in the section on recursion differences from  Perl  in  the
+        pcrepattern page.
 .  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".
-. PCRE provides some extensions to the Perl regular expression facil-
+. PCRE's handling of duplicate subpattern numbers and duplicate  sub-
-        ities.   Perl  5.10  will  include new features that are not in earlier
+        pattern names is not as general as Perl's. This is a consequence of the
-        versions, some of which (such as named parentheses) have been  in  PCRE
+        fact the PCRE works internally just with numbers, using an external ta-
-        for some time. This list is with respect to Perl 5.10:
+        ble  to  translate  between numbers and names. In particular, a pattern
+        such as (?|(?<a>A)|(?<b)B), where the two  capturing  parentheses  have
-        (a)  Although  lookbehind  assertions  must match fixed length strings,
+        the  same  number  but different names, is not supported, and causes an
-        each alternative branch of a lookbehind assertion can match a different
+        error at compile time. If it were allowed, it would not be possible  to
-        length of string. Perl requires them all to have the same length.
+        distinguish  which  parentheses matched, because both names map to cap-
+        turing subpattern number 1. To avoid this confusing situation, an error
+        is given at compile time.
+.  Perl  recognizes  comments  in some places that PCRE does not, for
+        example, between the ( and ? at the start of a subpattern.  If  the  /x
+        modifier  is set, Perl allows whitespace between ( and ? but PCRE never
+        does, even if the PCRE_EXTENDED option is set.
+. PCRE provides some extensions to the Perl regular expression facil-
+        ities.   Perl  5.10  includes new features that are not in earlier ver-
+        sions of Perl, some of which (such as named parentheses) have  been  in
+        PCRE for some time. This list is with respect to Perl 5.10:
+        (a)  Although  lookbehind  assertions  in  PCRE 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 $
+        (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.  Otherwise,  like  Perl,  the  backslash is
+        cial meaning is faulted. Otherwise, like Perl, the backslash is quietly
-        ignored. (Perl can be made to issue a warning.)
+        ignored.  (Perl can be made to issue a warning.)
-        (d) If PCRE_UNGREEDY is set, the greediness of the  repetition  quanti-
+        (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 at matching time 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-
+        (f) The PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NOTEMPTY_ATSTART,
-        TURE options for pcre_exec() have no Perl equivalents.
+        and  PCRE_NO_AUTO_CAPTURE  options for pcre_exec() have no Perl equiva-
+        lents.
+        (g) The \R escape sequence can be restricted to match only CR,  LF,  or
+        CRLF by the PCRE_BSR_ANYCRLF option.
-        (g) The callout facility is PCRE-specific.
+        (h) The callout facility is PCRE-specific.
-        (h) The partial matching facility is PCRE-specific.
+        (i) The partial matching facility is PCRE-specific.
-        (i) Patterns compiled by PCRE can be saved and re-used at a later time,
+        (j) Patterns compiled by PCRE can be saved and re-used at a later time,
         even on different hosts that have the other endianness.
-        (j)  The  alternative  matching function (pcre_dfa_exec()) matches in a
+        (k) The alternative matching function (pcre_dfa_exec())  matches  in  a
         different way and is not Perl-compatible.
+        (l)  PCRE  recognizes some special sequences such as (*CR) at the start
+        of a pattern that set overall options that cannot be changed within the
+        pattern.
  AUTHOR
-Line 2648 
 AUTHOR
+Line 3347 
 AUTHOR
  REVISION
-        Last updated: 06 March 2007
+        Last updated: 24 July 2011
-        Copyright (c) 1997-2007 University of Cambridge.
+        Copyright (c) 1997-2011 University of Cambridge.
  ------------------------------------------------------------------------------
-Line 2662 
 NAME
+Line 3361 
 NAME
  PCRE REGULAR EXPRESSION DETAILS
-        The  syntax  and semantics of the regular expressions supported by PCRE
+        The  syntax and semantics of the regular expressions that are supported
-        are described below. Regular expressions are also described in the Perl
+        by PCRE are described in detail below. There is a quick-reference  syn-
-        documentation  and  in  a  number  of books, some of which have copious
+        tax summary in the pcresyntax page. PCRE tries to match Perl syntax and
-        examples.  Jeffrey Friedl's "Mastering Regular Expressions",  published
+        semantics as closely as it can. PCRE  also  supports  some  alternative
-        by  O'Reilly, covers regular expressions in great detail. This descrip-
+        regular  expression  syntax (which does not conflict with the Perl syn-
-        tion of PCRE's regular expressions is intended as reference material.
+        tax) in order to provide some compatibility with regular expressions in
+        Python, .NET, and Oniguruma.
+        Perl's  regular expressions are described in its own documentation, and
+        regular expressions in general are covered in a number of  books,  some
+        of  which  have  copious  examples. Jeffrey Friedl's "Mastering Regular
+        Expressions", published by  O'Reilly,  covers  regular  expressions  in
+        great  detail.  This  description  of  PCRE's  regular  expressions  is
+        intended as reference material.
         The original operation of PCRE was on strings of  one-byte  characters.
         However,  there is now also support for UTF-8 character strings. To use
-        this, you must build PCRE to  include  UTF-8  support,  and  then  call
+        this, PCRE must be built to include UTF-8 support, and  you  must  call
-        pcre_compile()  with  the  PCRE_UTF8  option.  How this affects pattern
+        pcre_compile()  or  pcre_compile2() with the PCRE_UTF8 option. There is
-        matching is mentioned in several places below. There is also a  summary
+        also a special sequence that can be given at the start of a pattern:
-        of  UTF-8  features  in  the  section on UTF-8 support in the main pcre
-        page.
+          (*UTF8)
+        Starting a pattern with this sequence  is  equivalent  to  setting  the
+        PCRE_UTF8  option.  This  feature  is  not Perl-compatible. How setting
+        UTF-8 mode affects pattern matching  is  mentioned  in  several  places
+        below.  There  is  also  a  summary of UTF-8 features in the section on
+        UTF-8 support in the main pcre page.
+        Another special sequence that may appear at the start of a  pattern  or
+        in combination with (*UTF8) is:
-        The remainder of this document discusses the  patterns  that  are  sup-
+          (*UCP)
-        ported  by  PCRE when its main matching function, pcre_exec(), is used.
-        From  release  6.0,   PCRE   offers   a   second   matching   function,
+        This  has  the  same  effect  as setting the PCRE_UCP option: it causes
-        pcre_dfa_exec(),  which matches using a different algorithm that is not
+        sequences such as \d and \w to  use  Unicode  properties  to  determine
-        Perl-compatible. The advantages and disadvantages  of  the  alternative
+        character types, instead of recognizing only characters with codes less
-        function, and how it differs from the normal function, are discussed in
+        than 128 via a lookup table.
-        the pcrematching page.
+        If a pattern starts with (*NO_START_OPT), it has  the  same  effect  as
+        setting the PCRE_NO_START_OPTIMIZE option either at compile or matching
+        time. There are also some more of these special sequences that are con-
+        cerned with the handling of newlines; they are described below.
+        The  remainder  of  this  document discusses the patterns that are sup-
+        ported by PCRE when its main matching function, pcre_exec(),  is  used.
+        From   release   6.0,   PCRE   offers   a   second  matching  function,
+        pcre_dfa_exec(), which matches using a different algorithm that is  not
+        Perl-compatible. Some of the features discussed below are not available
+        when pcre_dfa_exec() is used. The advantages and disadvantages  of  the
+        alternative  function, and how it differs from the normal function, are
+        discussed in the pcrematching page.
+ NEWLINE CONVENTIONS
+        PCRE supports five different conventions for indicating line breaks  in
+        strings:  a  single  CR (carriage return) character, a single LF (line-
+        feed) character, the two-character sequence CRLF, any of the three pre-
+        ceding,  or  any Unicode newline sequence. The pcreapi page has further
+        discussion about newlines, and shows how to set the newline  convention
+        in the options arguments for the compiling and matching functions.
+        It  is also possible to specify a newline convention by starting a pat-
+        tern string with one of the following five sequences:
+          (*CR)        carriage return
+          (*LF)        linefeed
+          (*CRLF)      carriage return, followed by linefeed
+          (*ANYCRLF)   any of the three above
+          (*ANY)       all Unicode newline sequences
+        These override the default and the options given to  pcre_compile()  or
+        pcre_compile2().  For example, on a Unix system where LF is the default
+        newline sequence, the pattern
+          (*CR)a.b
+        changes the convention to CR. That pattern matches "a\nb" because LF is
+        no  longer  a  newline. Note that these special settings, which are not
+        Perl-compatible, are recognized only at the very start  of  a  pattern,
+        and  that  they  must  be  in  upper  case. If more than one of them is
+        present, the last one is used.
+        The newline convention affects the interpretation of the dot  metachar-
+        acter  when  PCRE_DOTALL is not set, and also the behaviour of \N. How-
+        ever, it does not affect  what  the  \R  escape  sequence  matches.  By
+        default,  this is any Unicode newline sequence, for Perl compatibility.
+        However, this can be changed; see the description of \R in the  section
+        entitled  "Newline sequences" below. A change of \R setting can be com-
+        bined with a change of newline convention.
  CHARACTERS AND METACHARACTERS
-Line 2741 
 CHARACTERS AND METACHARACTERS
+Line 3509 
 CHARACTERS AND METACHARACTERS
                    syntax)
           ]      terminates the character class
-        The following sections describe the use of each of the  metacharacters.
+        The following sections describe the use of each of the metacharacters.
  BACKSLASH
         The backslash character has several uses. Firstly, if it is followed by
-        a non-alphanumeric character, it takes away any  special  meaning  that
+        a character that is not a number or a letter, it takes away any special
-        character  may  have.  This  use  of  backslash  as an escape character
+        meaning that character may have. This use of  backslash  as  an  escape
-        applies both inside and outside character classes.
+        character applies both inside and outside character classes.
-        For example, if you want to match a * character, you write  \*  in  the
+        For  example,  if  you want to match a * character, you write \* in the
-        pattern.   This  escaping  action  applies whether or not the following
+        pattern.  This escaping action applies whether  or  not  the  following
-        character would otherwise be interpreted as a metacharacter, so  it  is
+        character  would  otherwise be interpreted as a metacharacter, so it is
-        always  safe  to  precede  a non-alphanumeric with backslash to specify
+        always safe to precede a non-alphanumeric  with  backslash  to  specify
-        that it stands for itself. In particular, if you want to match a  back-
+        that  it stands for itself. In particular, if you want to match a back-
         slash, you write \\.
-        If  a  pattern is compiled with the PCRE_EXTENDED option, whitespace in
+        In UTF-8 mode, only ASCII numbers and letters have any special  meaning
-        the pattern (other than in a character class) and characters between  a
+        after  a  backslash.  All  other characters (in particular, those whose
+        codepoints are greater than 127) are treated as literals.
+        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 are ignored. An escap-
-        ing backslash can be used to include a whitespace  or  #  character  as
+        ing  backslash  can  be  used to include a whitespace or # character as
         part of the pattern.
-        If  you  want  to remove the special meaning from a sequence of charac-
+        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-
+        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
+        ent from Perl in that $ and  @  are  handled  as  literals  in  \Q...\E
-        sequences in PCRE, whereas in Perl, $ and @ cause  variable  interpola-
+        sequences  in  PCRE, whereas in Perl, $ and @ cause variable interpola-
         tion. Note the following examples:
           Pattern            PCRE matches   Perl matches
-Line 2777 
 BACKSLASH
+Line 3549 
 BACKSLASH
           \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
+        The \Q...\E sequence is recognized both inside  and  outside  character
-        classes.
+        classes.   An  isolated \E that is not preceded by \Q is ignored. If \Q
+        is not followed by \E later in the pattern, the literal  interpretation
+        continues  to  the  end  of  the pattern (that is, \E is assumed at the
+        end). If the isolated \Q is inside a character class,  this  causes  an
+        error, because the character class is not terminated.
     Non-printing characters
         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
+        acters in patterns in a visible manner. There is no restriction on  the
-        appearance of non-printing characters, apart from the binary zero  that
+        appearance  of non-printing characters, apart from the binary zero that
-        terminates  a  pattern,  but  when  a pattern is being prepared by text
+        terminates a pattern, but when a pattern  is  being  prepared  by  text
-        editing, it is usually easier  to  use  one  of  the  following  escape
+        editing,  it  is  often  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
+          \cx       "control-x", where x is any ASCII character
           \e        escape (hex 1B)
           \f        formfeed (hex 0C)
-          \n        newline (hex 0A)
+          \n        linefeed (hex 0A)
           \r        carriage return (hex 0D)
           \t        tab (hex 09)
-          \ddd      character with octal code ddd, or backreference
+          \ddd      character with octal code ddd, or back reference
           \xhh      character with hex code hh
           \x{hhh..} character with hex code hhh..
-        The  precise  effect of \cx is as follows: if x is a lower case letter,
+        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
+        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;
+        inverted.  Thus \cz becomes hex 1A (z is 7A), but \c{ becomes hex 3B ({
-        becomes hex 7B.
+        is  7B),  while  \c; becomes hex 7B (; is 3B). If the byte following \c
+        has a value greater than 127, a compile-time error occurs.  This  locks
-        After \x, from zero to two hexadecimal digits are read (letters can  be
+        out  non-ASCII  characters in both byte mode and UTF-8 mode. (When PCRE
-        in  upper  or  lower case). Any number of hexadecimal digits may appear
+        is compiled in EBCDIC mode, all byte values are  valid.  A  lower  case
-        between \x{ and }, but the value of the character  code  must  be  less
+        letter is converted to upper case, and then the 0xc0 bits are flipped.)
-        than 256 in non-UTF-8 mode, and less than 2**31 in UTF-8 mode (that is,
-        the maximum hexadecimal value is 7FFFFFFF). If  characters  other  than
+        After  \x, from zero to two hexadecimal digits are read (letters can be
-        hexadecimal  digits  appear between \x{ and }, or if there is no termi-
+        in upper or lower case). Any number of hexadecimal  digits  may  appear
-        nating }, this form of escape is not recognized.  Instead, the  initial
+        between  \x{  and  },  but the value of the character code must be less
-        \x will be interpreted as a basic hexadecimal escape, with no following
+        than 256 in non-UTF-8 mode, and less than 2**31 in UTF-8 mode. That is,
-        digits, giving a character whose value is zero.
+        the  maximum value in hexadecimal is 7FFFFFFF. Note that this is bigger
+        than the largest Unicode code point, which is 10FFFF.
+        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  hexadecimal
+        escape,  with  no  following  digits, giving a character whose value is
+        zero.
         Characters whose value is less than 256 can be defined by either of the
         two  syntaxes  for  \x. There is no difference in the way they are han-
-Line 2862 
 BACKSLASH
+Line 3645 
 BACKSLASH
         All the sequences that define a single character value 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
-), and the sequences \R and \X are interpreted as the characters  "R"
+). The sequences \B, \N, \R, and \X are not special inside a  charac-
-        and  "X", respectively. Outside a character class, these sequences have
+        ter  class.  Like  any  other  unrecognized  escape sequences, they are
-        different meanings (see below).
+        treated as the literal characters "B", "N", "R", and  "X"  by  default,
+        but cause an error if the PCRE_EXTRA option is set. Outside a character
+        class, these sequences have different meanings.
     Absolute and relative back references
-        The sequence \g followed by a positive or negative  number,  optionally
+        The sequence \g followed by an unsigned or a negative  number,  option-
-        enclosed  in  braces,  is  an absolute or relative back reference. Back
+        ally  enclosed  in braces, is an absolute or relative back reference. A
-        references are discussed later, following the discussion  of  parenthe-
+        named back reference can be coded as \g{name}. Back references are dis-
-        sized subpatterns.
+        cussed later, following the discussion of parenthesized subpatterns.
+    Absolute and relative subroutine calls
+        For  compatibility with Oniguruma, the non-Perl syntax \g followed by a
+        name or a number enclosed either in angle brackets or single quotes, is
+        an  alternative  syntax for referencing a subpattern as a "subroutine".
+        Details are discussed later.   Note  that  \g{...}  (Perl  syntax)  and
+        \g<...>  (Oniguruma  syntax)  are  not synonymous. The former is a back
+        reference; the latter is a subroutine call.
     Generic character types
-        Another use of backslash is for specifying generic character types. The
+        Another use of backslash is for specifying generic character types:
-        following are always recognized:
           \d     any decimal digit
           \D     any character that is not a decimal digit
+          \h     any horizontal whitespace character
+          \H     any character that is not a horizontal whitespace character
           \s     any whitespace character
           \S     any character that is not a whitespace character
+          \v     any vertical whitespace character
+          \V     any character that is not a vertical whitespace character
           \w     any "word" character
           \W     any "non-word" character
-        Each pair of escape sequences partitions the complete set of characters
+        There is also the single sequence \N, which matches a non-newline char-
-        into  two disjoint sets. Any given character matches one, and only one,
+        acter.   This  is the same as the "." metacharacter when PCRE_DOTALL is
-        of each pair.
+        not set.
-        These character type sequences can appear both inside and outside char-
+        Each pair of lower and upper case escape sequences partitions the  com-
-        acter  classes.  They each match one character of the appropriate type.
+        plete  set  of  characters  into two disjoint sets. Any given character
-        If the current matching point is at the end of the subject string,  all
+        matches one, and only one, of each pair. The sequences can appear  both
-        of them fail, since there is no character to match.
+        inside  and outside character classes. They each match one character of
+        the appropriate type. If the current matching point is at  the  end  of
-        For  compatibility  with Perl, \s does not match the VT character (code
+        the  subject string, all of them fail, because there is no character to
-).  This makes it different from the the POSIX "space" class. The  \s
+        match.
-        characters  are  HT (9), LF (10), FF (12), CR (13), and space (32). (If
+        For compatibility with Perl, \s does not match the VT  character  (code
+).   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).  If
         "use locale;" is included in a Perl script, \s may match the VT charac-
-        ter. In PCRE, it never does.)
+        ter. In PCRE, it never does.
-        A "word" character is an underscore or any character less than 256 that
+        A "word" character is an underscore or any character that is  a  letter
-        is a letter or digit. The definition of  letters  and  digits  is  con-
+        or  digit.   By  default,  the definition of letters and digits is con-
-        trolled  by PCRE's low-valued character tables, and may vary if locale-
+        trolled by PCRE's low-valued character tables, and may vary if  locale-
-        specific matching is taking place (see "Locale support" in the  pcreapi
+        specific  matching is taking place (see "Locale support" in the pcreapi
-        page).  For  example,  in  the  "fr_FR" (French) locale, some character
+        page). For example, in a French locale such  as  "fr_FR"  in  Unix-like
-        codes greater than 128 are used for accented  letters,  and  these  are
+        systems,  or "french" in Windows, some character codes greater than 128
-        matched by \w.
+        are used for accented letters, and these are then matched  by  \w.  The
+        use of locales with Unicode is discouraged.
-        In  UTF-8 mode, characters with values greater than 128 never match \d,
-        \s, or \w, and always match \D, \S, and \W. This is true even when Uni-
+        By  default,  in  UTF-8  mode,  characters with values greater than 128
-        code  character  property support is available. The use of locales with
+        never match \d, \s, or \w, and always  match  \D,  \S,  and  \W.  These
-        Unicode is discouraged.
+        sequences  retain their original meanings from before UTF-8 support was
+        available, mainly for efficiency reasons. However, if PCRE is  compiled
+        with  Unicode property support, and the PCRE_UCP option is set, the be-
+        haviour is changed so that Unicode properties  are  used  to  determine
+        character types, as follows:
+          \d  any character that \p{Nd} matches (decimal digit)
+          \s  any character that \p{Z} matches, plus HT, LF, FF, CR
+          \w  any character that \p{L} or \p{N} matches, plus underscore
+        The  upper case escapes match the inverse sets of characters. Note that
+        \d matches only decimal digits, whereas \w matches any  Unicode  digit,
+        as  well as any Unicode letter, and underscore. Note also that PCRE_UCP
+        affects \b, and \B because they are defined in  terms  of  \w  and  \W.
+        Matching these sequences is noticeably slower when PCRE_UCP is set.
+        The  sequences  \h, \H, \v, and \V are features that were added to Perl
+        at release 5.10. In contrast to the other sequences, which  match  only
+        ASCII  characters  by  default,  these always match certain high-valued
+        codepoints in UTF-8 mode, whether or not PCRE_UCP is set. The  horizon-
+        tal space characters are:
+          U+0009     Horizontal tab
+          U+0020     Space
+          U+00A0     Non-break space
+          U+1680     Ogham space mark
+          U+180E     Mongolian vowel separator
+          U+2000     En quad
+          U+2001     Em quad
+          U+2002     En space
+          U+2003     Em space
+          U+2004     Three-per-em space
+          U+2005     Four-per-em space
+          U+2006     Six-per-em space
+          U+2007     Figure space
+          U+2008     Punctuation space
+          U+2009     Thin space
+          U+200A     Hair space
+          U+202F     Narrow no-break space
+          U+205F     Medium mathematical space
+          U+3000     Ideographic space
+        The vertical space characters are:
+          U+000A     Linefeed
+          U+000B     Vertical tab
+          U+000C     Formfeed
+          U+000D     Carriage return
+          U+0085     Next line
+          U+2028     Line separator
+          U+2029     Paragraph separator
     Newline sequences
-        Outside a character class, the escape sequence \R matches  any  Unicode
+        Outside  a  character class, by default, the escape sequence \R matches
-        newline sequence. This is an extension to Perl. In non-UTF-8 mode \R is
+        any Unicode newline sequence. In non-UTF-8 mode \R is equivalent to the
-        equivalent to the following:
+        following:
           (?>\r\n|\n|\x0b|\f|\r|\x85)
-        This is an example of an "atomic group", details  of  which  are  given
+        This  is  an  example  of an "atomic group", details of which are given
         below.  This particular group matches either the two-character sequence
-        CR followed by LF, or  one  of  the  single  characters  LF  (linefeed,
+        CR  followed  by  LF,  or  one  of  the single characters LF (linefeed,
         U+000A), VT (vertical tab, U+000B), FF (formfeed, U+000C), CR (carriage
         return, U+000D), or NEL (next line, U+0085). The two-character sequence
         is treated as a single unit that cannot be split.
-        In  UTF-8  mode, two additional characters whose codepoints are greater
+        In UTF-8 mode, two additional characters whose codepoints  are  greater
         than 255 are added: LS (line separator, U+2028) and PS (paragraph sepa-
-        rator,  U+2029).   Unicode character property support is not needed for
+        rator, U+2029).  Unicode character property support is not  needed  for
         these characters to be recognized.
-        Inside a character class, \R matches the letter "R".
+        It is possible to restrict \R to match only CR, LF, or CRLF (instead of
+        the complete set  of  Unicode  line  endings)  by  setting  the  option
+        PCRE_BSR_ANYCRLF either at compile time or when the pattern is matched.
+        (BSR is an abbrevation for "backslash R".) This can be made the default
+        when  PCRE  is  built;  if this is the case, the other behaviour can be
+        requested via the PCRE_BSR_UNICODE option.   It  is  also  possible  to
+        specify  these  settings  by  starting a pattern string with one of the
+        following sequences:
+          (*BSR_ANYCRLF)   CR, LF, or CRLF only
+          (*BSR_UNICODE)   any Unicode newline sequence
+        These override the default and the options given to  pcre_compile()  or
+        pcre_compile2(),  but  they  can  be  overridden  by  options  given to
+        pcre_exec() or pcre_dfa_exec(). Note that these special settings, which
+        are  not  Perl-compatible,  are  recognized only at the very start of a
+        pattern, and that they must be in upper case. If more than one of  them
+        is present, the last one is used. They can be combined with a change of
+        newline convention; for example, a pattern can start with:
+          (*ANY)(*BSR_ANYCRLF)
+        They can also be combined with the (*UTF8) or (*UCP) special sequences.
+        Inside  a  character  class,  \R  is  treated as an unrecognized escape
+        sequence, and so matches the letter "R" by default, but causes an error
+        if PCRE_EXTRA is set.
     Unicode character properties
         When PCRE is built with Unicode character property support, three addi-
-        tional  escape  sequences  to  match character properties are available
+        tional escape sequences that match characters with specific  properties
-        when UTF-8 mode is selected. They are:
+        are  available.   When not in UTF-8 mode, these sequences are of course
+        limited to testing characters whose codepoints are less than  256,  but
+        they do work in this mode.  The extra escape sequences are:
           \p{xx}   a character with the xx property
           \P{xx}   a character without the xx property
           \X       an extended Unicode sequence
-        The property names represented by xx above are limited to  the  Unicode
+        The  property  names represented by xx above are limited to the Unicode
-        script names, the general category properties, and "Any", which matches
+        script names, the general category properties, "Any", which matches any
-        any character (including newline). Other properties such as "InMusical-
+        character   (including  newline),  and  some  special  PCRE  properties
-        Symbols"  are  not  currently supported by PCRE. Note that \P{Any} does
+        (described in the next section).  Other Perl properties such as  "InMu-
-        not match any characters, so always causes a match failure.
+        sicalSymbols"  are  not  currently supported by PCRE. Note that \P{Any}
+        does not match any characters, so always causes a match failure.
         Sets of Unicode characters are defined as belonging to certain scripts.
         A  character from one of these sets can be matched using a script name.
-Line 2961 
 BACKSLASH
+Line 3839 
 BACKSLASH
         Those that are not part of an identified script are lumped together  as
         "Common". The current list of scripts is:
-        Arabic,  Armenian,  Balinese,  Bengali,  Bopomofo,  Braille,  Buginese,
+        Arabic, Armenian, Avestan, Balinese, Bamum, Bengali, Bopomofo, Braille,
-        Buhid,  Canadian_Aboriginal,  Cherokee,  Common,   Coptic,   Cuneiform,
+        Buginese, Buhid, Canadian_Aboriginal, Carian, Cham,  Cherokee,  Common,
-        Cypriot, Cyrillic, Deseret, Devanagari, Ethiopic, Georgian, Glagolitic,
+        Coptic,   Cuneiform,  Cypriot,  Cyrillic,  Deseret,  Devanagari,  Egyp-
-        Gothic, Greek, Gujarati, Gurmukhi, Han, Hangul, Hanunoo, Hebrew,  Hira-
+        tian_Hieroglyphs,  Ethiopic,  Georgian,  Glagolitic,   Gothic,   Greek,
-        gana,  Inherited,  Kannada,  Katakana,  Kharoshthi,  Khmer, Lao, Latin,
+        Gujarati,  Gurmukhi,  Han,  Hangul,  Hanunoo,  Hebrew,  Hiragana, Impe-
-        Limbu,  Linear_B,  Malayalam,  Mongolian,  Myanmar,  New_Tai_Lue,  Nko,
+        rial_Aramaic, Inherited, Inscriptional_Pahlavi, Inscriptional_Parthian,
-        Ogham,  Old_Italic,  Old_Persian, Oriya, Osmanya, Phags_Pa, Phoenician,
+        Javanese,  Kaithi, Kannada, Katakana, Kayah_Li, Kharoshthi, Khmer, Lao,
-        Runic,  Shavian,  Sinhala,  Syloti_Nagri,  Syriac,  Tagalog,  Tagbanwa,
+        Latin,  Lepcha,  Limbu,  Linear_B,  Lisu,  Lycian,  Lydian,  Malayalam,
-        Tai_Le, Tamil, Telugu, Thaana, Thai, Tibetan, Tifinagh, Ugaritic, Yi.
+        Meetei_Mayek,  Mongolian, Myanmar, New_Tai_Lue, Nko, Ogham, Old_Italic,
+        Old_Persian, Old_South_Arabian, Old_Turkic, Ol_Chiki,  Oriya,  Osmanya,
-        Each  character has exactly one general category property, specified by
+        Phags_Pa,  Phoenician,  Rejang,  Runic, Samaritan, Saurashtra, Shavian,
-        a two-letter abbreviation. For compatibility with Perl, negation can be
+        Sinhala, Sundanese, Syloti_Nagri, Syriac,  Tagalog,  Tagbanwa,  Tai_Le,
     &