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

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

Parent Directory | Revision Log | View Patch Patch

-revision 416 by ph10,
Sat Apr 11 14:34:02 2009 UTC
+revision 429 by ph10,
Tue Sep  1 16:10:16 2009 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 24 
 INTRODUCTION
+Line 25 
 INTRODUCTION
         tax items, and there is an option for  requesting  some  minor  changes
         that give better JavaScript compatibility.
-        The  current  implementation of PCRE (release 7.x) corresponds approxi-
+        The  current implementation of PCRE (release 8.xx) corresponds approxi-
         mately with Perl 5.10, including support for UTF-8 encoded strings  and
         Unicode general category properties. However, UTF-8 and Unicode support
         has to be explicitly enabled; it is not the default. The Unicode tables
-Line 71 
 USER DOCUMENTATION
+Line 72 
 USER DOCUMENTATION
         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
         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
-Line 81 
 USER DOCUMENTATION
+Line 83 
 USER DOCUMENTATION
           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 90 
 USER DOCUMENTATION
+Line 93 
 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
           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.
-Line 119 
 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, or the  pattern  must  start  with  the
+        with  the  PCRE_UTF8  option  flag,  or the pattern must start with the
-        sequence  (*UTF8).  When  either of these is the case, both the pattern
+        sequence (*UTF8). When either of these is the case,  both  the  pattern
-        and any subject strings that are matched  against  it  are  treated  as
+        and  any  subject  strings  that  are matched against it are treated as
         UTF-8 strings instead of just strings of bytes.
-        If  you compile PCRE with UTF-8 support, but do not use it at run time,
+        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
+        the  library will be a bit bigger, but the additional run time overhead
         is limited to testing the PCRE_UTF8 flag occasionally, so should not be
         very big.
         If PCRE is built with Unicode character property support (which implies
-        UTF-8  support),  the  escape sequences \p{..}, \P{..}, and \X are sup-
+        UTF-8 support), the escape sequences \p{..}, \P{..}, and  \X  are  sup-
         ported.  The available properties that can be tested are limited to the
-        general  category  properties such as Lu for an upper case letter or Nd
+        general category properties such as Lu for an upper case letter  or  Nd
-        for a decimal number, the Unicode script names such as Arabic  or  Han,
+        for  a  decimal number, the Unicode script names such as Arabic or Han,
-        and  the  derived  properties  Any  and L&. A full list is given in the
+        and the derived properties Any and L&. A full  list  is  given  in  the
         pcrepattern documentation. Only the short names for properties are sup-
-        ported.  For example, \p{L} matches a letter. Its Perl synonym, \p{Let-
+        ported. For example, \p{L} matches a letter. Its Perl synonym,  \p{Let-
-        ter}, is not supported.  Furthermore,  in  Perl,  many  properties  may
+        ter},  is  not  supported.   Furthermore,  in Perl, many properties may
-        optionally  be  prefixed by "Is", for compatibility with Perl 5.6. PCRE
+        optionally be prefixed by "Is", for compatibility with Perl  5.6.  PCRE
         does not support this.
     Validity of UTF-8 strings
-        When you set the PCRE_UTF8 flag, the strings  passed  as  patterns  and
+        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
+        functions.  From  release 7.3 of PCRE, the check is according the rules
-        of  RFC  3629, which are themselves derived from the Unicode specifica-
+        of RFC 3629, which are themselves derived from the  Unicode  specifica-
-        tion. Earlier releases of PCRE followed the rules of  RFC  2279,  which
+        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
+        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
+        The excluded code points are the "Low Surrogate Area"  of  Unicode,  of
-        which the Unicode Standard says this: "The Low Surrogate Area does  not
+        which  the Unicode Standard says this: "The Low Surrogate Area does not
-        contain  any  character  assignments,  consequently  no  character code
+        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
+        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
+        that  are  encoded  by  UTF-16  pairs are available as independent code
-        points  in  the  UTF-8  encoding.  (In other words, the whole surrogate
+        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
+        If  an  invalid  UTF-8  string  is  passed  to  PCRE,  an  error return
         (PCRE_ERROR_BADUTF8) 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
+        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
+        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  when  PCRE_NO_UTF8_CHECK  is  set,
+        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-
+        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,
+        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
+        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.
+        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
+        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
+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.
     General comments about UTF-8 mode
-. An unbraced hexadecimal escape sequence (such  as  \xb3)  matches  a
+.  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
+. 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-
+.  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-
+. 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
+.  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
+        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
+.  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 the characters that PCRE  recog-
-        nizes as digits, spaces, or word characters  remain  the  same  set  as
+        nizes  as  digits,  spaces,  or  word characters remain the same set as
         before, all with values less than 256. This remains true even when PCRE
-        includes Unicode property support, because to do otherwise  would  slow
+        includes  Unicode  property support, because to do otherwise would slow
-        down  PCRE in many common cases. If you really want to test for a wider
+        down PCRE in many common cases. If you really want to test for a  wider
-        sense of, say, "digit", you must use Unicode  property  tests  such  as
+        sense  of,  say,  "digit",  you must use Unicode property tests such as
-        \p{Nd}.  Note  that  this  also applies to \b, because it is defined in
+        \p{Nd}. Note that this also applies to \b, because  it  is  defined  in
         terms of \w and \W.
-. Similarly, characters that match the POSIX named  character  classes
+.  Similarly,  characters that match the POSIX named character classes
         are all low-valued characters.
-.  However,  the Perl 5.10 horizontal and vertical whitespace matching
+. However, the Perl 5.10 horizontal and vertical  whitespace  matching
         escapes (\h, \H, \v, and \V) do match all the appropriate Unicode char-
         acters.
-.  Case-insensitive  matching  applies only to characters whose values
+. Case-insensitive matching applies only to  characters  whose  values
-        are less than 128, unless PCRE is built with Unicode property  support.
+        are  less than 128, unless PCRE is built with Unicode property support.
-        Even  when  Unicode  property support is available, PCRE still uses its
+        Even when Unicode property support is available, PCRE  still  uses  its
-        own character tables when checking the case of  low-valued  characters,
+        own  character  tables when checking the case of low-valued characters,
-        so  as not to degrade performance.  The Unicode property information is
+        so as not to degrade performance.  The Unicode property information  is
         used only for characters with higher values. Even when Unicode property
         support is available, PCRE supports case-insensitive matching only when
-        there is a one-to-one mapping between a letter's  cases.  There  are  a
+        there  is  a  one-to-one  mapping between a letter's cases. There are a
-        small  number  of  many-to-one  mappings in Unicode; these are not sup-
+        small number of many-to-one mappings in Unicode;  these  are  not  sup-
         ported by PCRE.
-Line 253 
 AUTHOR
+Line 256 
 AUTHOR
         University Computing Service
         Cambridge CB2 3QH, England.
-        Putting an actual email address here seems to have been a spam  magnet,
+        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 two initials,
+        so I've taken it away. If you want to email me, use  my  two  initials,
         followed by the two digits 10, at the domain cam.ac.uk.
  REVISION
-        Last updated: 11 April 2009
+        Last updated: 01 September 2009
         Copyright (c) 1997-2009 University of Cambridge.
  ------------------------------------------------------------------------------
  PCREBUILD(3)                                                      PCREBUILD(3)
-Line 590 
 REVISION
+Line 593 
 REVISION
         Last updated: 17 March 2009
         Copyright (c) 1997-2009 University of Cambridge.
  ------------------------------------------------------------------------------
  PCREMATCHING(3)                                                PCREMATCHING(3)
-Line 751 
 ADVANTAGES OF THE ALTERNATIVE ALGORITHM
+Line 754 
 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.
-Line 786 
 AUTHOR
+Line 783 
 AUTHOR
  REVISION
-        Last updated: 19 April 2008
+        Last updated: 25 August 2009
-        Copyright (c) 1997-2008 University of Cambridge.
+        Copyright (c) 1997-2009 University of Cambridge.
  ------------------------------------------------------------------------------
  PCREAPI(3)                                                          PCREAPI(3)
-Line 898 
 PCRE API OVERVIEW
+Line 895 
 PCRE API OVERVIEW
         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
-        compile and 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.  However,  this
         algorithm does not return captured substrings. A description of the two
-        matching  algorithms and their advantages and disadvantages is given in
+        matching algorithms and their advantages and disadvantages is given  in
         the pcrematching documentation.
-        In addition to the main compiling and  matching  functions,  there  are
+        In  addition  to  the  main compiling and matching functions, there are
         convenience functions for extracting captured substrings from a subject
         string that is matched by pcre_exec(). They are:
-Line 924 
 PCRE API OVERVIEW
+Line 922 
 PCRE API OVERVIEW
         pcre_free_substring() and pcre_free_substring_list() are also provided,
         to free the memory used for extracted strings.
-        The  function  pcre_maketables()  is  used  to build a set of character
+        The function pcre_maketables() is used to  build  a  set  of  character
-        tables  in  the  current  locale   for   passing   to   pcre_compile(),
+        tables   in   the   current   locale  for  passing  to  pcre_compile(),
-        pcre_exec(),  or  pcre_dfa_exec(). This is an optional facility that is
+        pcre_exec(), or pcre_dfa_exec(). This is an optional facility  that  is
-        provided for specialist use.  Most  commonly,  no  special  tables  are
+        provided  for  specialist  use.  Most  commonly,  no special tables are
-        passed,  in  which case internal tables that are generated when PCRE is
+        passed, in which case internal tables that are generated when  PCRE  is
         built are used.
-        The function pcre_fullinfo() is used to find out  information  about  a
+        The  function  pcre_fullinfo()  is used to find out information about a
-        compiled  pattern; pcre_info() is an obsolete version that returns only
+        compiled pattern; pcre_info() is an obsolete version that returns  only
-        some of the available information, but is retained for  backwards  com-
+        some  of  the available information, but is retained for backwards com-
-        patibility.   The function pcre_version() returns a pointer to a string
+        patibility.  The function pcre_version() returns a pointer to a  string
         containing the version of PCRE and its date of release.
-        The function pcre_refcount() maintains a  reference  count  in  a  data
+        The  function  pcre_refcount()  maintains  a  reference count in a data
-        block  containing  a compiled pattern. This is provided for the benefit
+        block containing a compiled pattern. This is provided for  the  benefit
         of object-oriented applications.
-        The global variables pcre_malloc and pcre_free  initially  contain  the
+        The  global  variables  pcre_malloc and pcre_free initially contain the
-        entry  points  of  the  standard malloc() and free() functions, respec-
+        entry points of the standard malloc()  and  free()  functions,  respec-
         tively. PCRE calls the memory management functions via these variables,
-        so  a  calling  program  can replace them if it wishes to intercept the
+        so a calling program can replace them if it  wishes  to  intercept  the
         calls. This should be done before calling any PCRE functions.
-        The global variables pcre_stack_malloc  and  pcre_stack_free  are  also
+        The  global  variables  pcre_stack_malloc  and pcre_stack_free are also
-        indirections  to  memory  management functions. These special functions
+        indirections to memory management functions.  These  special  functions
-        are used only when PCRE is compiled to use  the  heap  for  remembering
+        are  used  only  when  PCRE is compiled to use the heap for remembering
         data, instead of recursive function calls, when running the pcre_exec()
-        function. See the pcrebuild documentation for  details  of  how  to  do
+        function.  See  the  pcrebuild  documentation  for details of how to do
-        this.  It  is  a non-standard way of building PCRE, for use in environ-
+        this. It is a non-standard way of building PCRE, for  use  in  environ-
-        ments that have limited stacks. Because of the greater  use  of  memory
+        ments  that  have  limited stacks. Because of the greater use of memory
-        management,  it  runs  more  slowly. Separate functions are provided so
+        management, it runs more slowly. Separate  functions  are  provided  so
-        that special-purpose external code can be  used  for  this  case.  When
+        that  special-purpose  external  code  can  be used for this case. When
-        used,  these  functions  are always called in a stack-like manner (last
+        used, these functions are always called in a  stack-like  manner  (last
-        obtained, first freed), and always for memory blocks of the same  size.
+        obtained,  first freed), and always for memory blocks of the same size.
-        There  is  a discussion about PCRE's stack usage in the pcrestack docu-
+        There is a discussion about PCRE's stack usage in the  pcrestack  docu-
         mentation.
         The global variable pcre_callout initially contains NULL. It can be set
-        by  the  caller  to  a "callout" function, which PCRE will then call at
+        by the caller to a "callout" function, which PCRE  will  then  call  at
-        specified points during a matching operation. Details are given in  the
+        specified  points during a matching operation. Details are given in the
         pcrecallout documentation.
  NEWLINES
-        PCRE  supports five 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-
+        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 Unicode newline  sequences
+        ceding,  or any Unicode newline sequence. The Unicode newline sequences
-        are  the  three just mentioned, plus the single characters VT (vertical
+        are the three just mentioned, plus the single characters  VT  (vertical
-        tab, U+000B), FF (formfeed, U+000C), NEL (next line, U+0085), LS  (line
+        tab,  U+000B), FF (formfeed, U+000C), NEL (next line, U+0085), LS (line
         separator, U+2028), and PS (paragraph separator, U+2029).
-        Each  of  the first three conventions is used by at least one operating
+        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
+        system  as its standard newline sequence. When PCRE is built, a default
-        can  be  specified.  The default default is LF, which is the Unix stan-
+        can be specified.  The default default is LF, which is the  Unix  stan-
-        dard. When PCRE is run, the default can be overridden,  either  when  a
+        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
+        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. There is more detail about this in the
         section on pcre_exec() options below.
-        The choice of newline convention does not affect the interpretation  of
+        The  choice of newline convention does not affect the interpretation of
-        the  \n  or  \r  escape  sequences, nor does it affect what \R matches,
+        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.
-        The  compiled form of a regular expression is not altered during match-
+        The compiled form of a regular expression is not altered during  match-
         ing, so the same compiled pattern can safely be used by several threads
         at once.
-Line 1016 
 MULTITHREADING
+Line 1014 
 MULTITHREADING
  SAVING PRECOMPILED PATTERNS FOR LATER USE
         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
+        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
+        than the one on which  it  was  compiled.  Details  are  given  in  the
-        pcreprecompile documentation. However, compiling a  regular  expression
+        pcreprecompile  documentation.  However, compiling a regular expression
-        with  one version of PCRE for use with a different version is not guar-
+        with one version of PCRE for use with a different version is not  guar-
         anteed to work and may cause crashes.
-Line 1027 
 CHECKING BUILD-TIME OPTIONS
+Line 1025 
 CHECKING BUILD-TIME OPTIONS
         int pcre_config(int what, void *where);
-        The function pcre_config() makes it possible for a PCRE client to  dis-
+        The  function pcre_config() makes it possible for a PCRE client to dis-
         cover which optional features have been compiled into the PCRE library.
-        The pcrebuild documentation has more details about these optional  fea-
+        The  pcrebuild documentation has more details about these optional fea-
         tures.
-        The  first  argument  for pcre_config() is an integer, specifying which
+        The first argument for pcre_config() is an  integer,  specifying  which
         information is required; the second argument is a pointer to a variable
-        into  which  the  information  is  placed. The following information is
+        into which the information is  placed.  The  following  information  is
         available:
           PCRE_CONFIG_UTF8
-        The output is an integer that is set to one if UTF-8 support is  avail-
+        The  output is an integer that is set to one if UTF-8 support is avail-
         able; otherwise it is set to zero.
           PCRE_CONFIG_UNICODE_PROPERTIES
-        The  output  is  an  integer  that is set to one if support for Unicode
+        The output is an integer that is set to  one  if  support  for  Unicode
         character properties is available; otherwise it is set to zero.
           PCRE_CONFIG_NEWLINE
-        The output is an integer whose value specifies  the  default  character
+        The  output  is  an integer whose value specifies the default character
-        sequence  that is recognized as meaning "newline". The four values that
+        sequence that is recognized as meaning "newline". The four values  that
         are supported are: 10 for LF, 13 for CR, 3338 for CRLF, -2 for ANYCRLF,
-        and  -1  for  ANY.  Though they are derived from ASCII, the same values
+        and -1 for ANY.  Though they are derived from ASCII,  the  same  values
         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
+        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 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 a long integer that gives the default limit for the  num-
+        The  output is a long integer that gives the default limit for the num-
-        ber  of  internal  matching  function calls in a pcre_exec() execution.
+        ber of internal matching function calls  in  a  pcre_exec()  execution.
         Further details are given with pcre_exec() below.
           PCRE_CONFIG_MATCH_LIMIT_RECURSION
         The output is a long integer that gives the default limit for the depth
-        of   recursion  when  calling  the  internal  matching  function  in  a
+        of  recursion  when  calling  the  internal  matching  function  in   a
-        pcre_exec() execution.  Further  details  are  given  with  pcre_exec()
+        pcre_exec()  execution.  Further  details  are  given  with pcre_exec()
         below.
           PCRE_CONFIG_STACKRECURSE
-        The  output is an integer that is set to one if internal recursion when
+        The output is an integer that is set to one if internal recursion  when
         running pcre_exec() is implemented by recursive function calls that use
-        the  stack  to remember their state. This is the usual way that PCRE is
+        the stack to remember their state. This is the usual way that  PCRE  is
         compiled. The output is zero if PCRE was compiled to use blocks of data
-        on  the  heap  instead  of  recursive  function  calls.  In  this case,
+        on the  heap  instead  of  recursive  function  calls.  In  this  case,
-        pcre_stack_malloc and  pcre_stack_free  are  called  to  manage  memory
+        pcre_stack_malloc  and  pcre_stack_free  are  called  to  manage memory
         blocks on the heap, thus avoiding the use of the stack.
-Line 1116 
 COMPILING A PATTERN
+Line 1114 
 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,
+        the two interfaces is that pcre_compile2() has an additional  argument,
         errorcodeptr, via which a numerical error code can be returned.
         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
+        the pattern argument. A pointer to a single block  of  memory  that  is
-        obtained via pcre_malloc is returned. This contains the  compiled  code
+        obtained  via  pcre_malloc is returned. This contains the compiled code
         and related data. The pcre type is defined for the returned block; this
         is a typedef for a structure whose contents are not externally defined.
         It is up to the caller to free the memory (via pcre_free) when it is no
         longer required.
-        Although the compiled code of a PCRE regex is relocatable, that is,  it
+        Although  the compiled code of a PCRE regex is relocatable, that is, it
         does not depend on memory location, the complete pcre data block is not
-        fully relocatable, because it may contain a copy of the tableptr  argu-
+        fully  relocatable, because it may contain a copy of the tableptr argu-
         ment, which is an address (see below).
         The options argument contains various bit settings that affect the com-
-        pilation. It should be zero if no options are required.  The  available
+        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, but also some others) can  also  be  set  and
+        are  compatible  with  Perl,  but also some others) can also be set and
-        unset  from  within  the  pattern  (see the detailed description in the
+        unset from within the pattern (see  the  detailed  description  in  the
-        pcrepattern documentation). For those options that can be different  in
+        pcrepattern  documentation). For those options that can be different in
-        different  parts  of  the pattern, the contents of the options argument
+        different parts of the pattern, the contents of  the  options  argument
         specifies their initial settings at the start of compilation and execu-
-        tion.  The PCRE_ANCHORED and PCRE_NEWLINE_xxx options can be set at the
+        tion. The PCRE_ANCHORED and PCRE_NEWLINE_xxx 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
+        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-
         ter where the error was discovered is placed in the variable pointed to
-        by erroffset, which must not be NULL. If it is, an immediate  error  is
+        by  erroffset,  which must not be NULL. If it is, an immediate error is
         given.
-        If  pcre_compile2()  is  used instead of pcre_compile(), and the error-
+        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
+        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
+        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 1178 
 COMPILING A PATTERN
+Line 1176 
 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,
+        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-
-        acters,  including  those that indicate newline. Without it, a dot does
+        acters, including those that indicate newline. Without it, a  dot  does
-        not match when the current position is at a  newline.  This  option  is
+        not  match  when  the  current position is at a newline. This option is
-        equivalent  to Perl's /s option, and it can be changed within a pattern
+        equivalent to Perl's /s option, and it can be changed within a  pattern
-        by a (?s) option setting. A negative class such as [^a] always  matches
+        by  a (?s) option setting. A negative class such as [^a] always matches
         newline characters, independent of the setting 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.
-        This  option  makes  it possible to include comments inside complicated
+        This option makes it possible to include  comments  inside  complicated
-        patterns.  Note, however, that this applies only  to  data  characters.
+        patterns.   Note,  however,  that this applies only to data characters.
-        Whitespace   characters  may  never  appear  within  special  character
+        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 (?( which
         introduces a conditional subpattern.
           PCRE_EXTRA
-        This  option  was invented in order to turn on additional functionality
+        This option was invented in order to turn on  additional  functionality
-        of PCRE that is incompatible with Perl, but it  is  currently  of  very
+        of  PCRE  that  is  incompatible with Perl, but it is currently of very
-        little  use. When set, any backslash in a pattern that is followed by a
+        little use. When set, any backslash in a pattern that is followed by  a
-        letter that has no special meaning  causes  an  error,  thus  reserving
+        letter  that  has  no  special  meaning causes an error, thus reserving
-        these  combinations  for  future  expansion.  By default, as in Perl, a
+        these combinations for future expansion. By  default,  as  in  Perl,  a
-        backslash followed by a letter with no special meaning is treated as  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 a warning for  this.)
-        There are at present no other features controlled by  this  option.  It
+        There  are  at  present no other features 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
+        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
+        (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
+        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
+        (2)  At run time, a back reference to an unset subpattern group matches
-        an  empty  string (by default this causes the current matching alterna-
+        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
+        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
+        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
+        By  default,  PCRE  treats the subject string as consisting of a single
-        line  of characters (even if it actually contains newlines). The "start
+        line of characters (even if it actually contains newlines). The  "start
-        of line" metacharacter (^) matches only at the  start  of  the  string,
+        of  line"  metacharacter  (^)  matches only at the start of the string,
-        while  the  "end  of line" metacharacter ($) matches only at the end of
+        while the "end of line" metacharacter ($) matches only at  the  end  of
         the string, or before a terminating newline (unless PCRE_DOLLAR_ENDONLY
         is set). This is the same as Perl.
-        When  PCRE_MULTILINE  it  is set, the "start of line" and "end of line"
+        When PCRE_MULTILINE it is set, the "start of line" and  "end  of  line"
-        constructs match immediately following or immediately  before  internal
+        constructs  match  immediately following or immediately before internal
-        newlines  in  the  subject string, respectively, as well as at the very
+        newlines in the subject string, respectively, as well as  at  the  very
-        start and end. This is equivalent to Perl's /m option, and  it  can  be
+        start  and  end.  This is equivalent to Perl's /m option, and it can be
         changed within a pattern by a (?m) option setting. If there are no new-
-        lines in a subject string, or no occurrences of ^ or $  in  a  pattern,
+        lines  in  a  subject string, or no occurrences of ^ or $ in a pattern,
         setting PCRE_MULTILINE has no effect.
           PCRE_NEWLINE_CR
-Line 1317 
 COMPILING A PATTERN
+Line 1315 
 COMPILING A PATTERN
           PCRE_NEWLINE_ANYCRLF
           PCRE_NEWLINE_ANY
-        These  options  override the default newline definition that was chosen
+        These options override the default newline definition that  was  chosen
-        when PCRE was built. Setting the first or the second specifies  that  a
+        when  PCRE  was built. Setting the first or the second specifies that a
-        newline  is  indicated  by a single character (CR or LF, respectively).
+        newline is indicated by a single character (CR  or  LF,  respectively).
-        Setting PCRE_NEWLINE_CRLF specifies that a newline is indicated by  the
+        Setting  PCRE_NEWLINE_CRLF specifies that a newline is indicated by the
-        two-character  CRLF  sequence.  Setting  PCRE_NEWLINE_ANYCRLF specifies
+        two-character CRLF  sequence.  Setting  PCRE_NEWLINE_ANYCRLF  specifies
         that any of the three preceding sequences should be recognized. Setting
-        PCRE_NEWLINE_ANY  specifies that any Unicode newline sequence should be
+        PCRE_NEWLINE_ANY specifies that any Unicode newline sequence should  be
         recognized. The Unicode newline sequences are the three just mentioned,
-        plus  the  single  characters  VT (vertical tab, U+000B), FF (formfeed,
+        plus the single characters VT (vertical  tab,  U+000B),  FF  (formfeed,
-        U+000C), NEL (next line, U+0085), LS (line separator, U+2028),  and  PS
+        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
+        (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
+        The  newline  setting  in  the  options  word  uses three bits that are
         treated as a number, giving eight possibilities. Currently only six are
-        used (default plus the five values above). This means that if  you  set
+        used  (default  plus the five values above). This means that if you set
-        more  than one newline option, the combination may or may not be sensi-
+        more than one newline option, the combination may or may not be  sensi-
         ble. For example, PCRE_NEWLINE_CR with PCRE_NEWLINE_LF is equivalent to
-        PCRE_NEWLINE_CRLF,  but other combinations may yield unused numbers and
+        PCRE_NEWLINE_CRLF, but other combinations may yield unused numbers  and
         cause an error.
-        The only time that a line break is specially recognized when  compiling
+        The  only time that a line break is specially recognized when compiling
-        a  pattern  is  if  PCRE_EXTENDED  is set, and an unescaped # outside a
+        a pattern is if PCRE_EXTENDED is set, and  an  unescaped  #  outside  a
-        character class is encountered. This indicates  a  comment  that  lasts
+        character  class  is  encountered.  This indicates a comment that lasts
-        until  after the next line break sequence. In other circumstances, line
+        until after the next line break sequence. In other circumstances,  line
-        break  sequences  are  treated  as  literal  data,   except   that   in
+        break   sequences   are   treated  as  literal  data,  except  that  in
         PCRE_EXTENDED mode, both CR and LF are treated as whitespace characters
         and are therefore ignored.
-Line 1352 
 COMPILING A PATTERN
+Line 1350 
 COMPILING A PATTERN
           PCRE_NO_AUTO_CAPTURE
         If this option is set, it disables the use of numbered capturing paren-
-        theses in the pattern. Any opening parenthesis that is not followed  by
+        theses  in the pattern. Any opening parenthesis that is not followed by
-        ?  behaves as if it were followed by ?: but named parentheses can still
+        ? behaves as if it were followed by ?: but named parentheses can  still
-        be used for capturing (and they acquire  numbers  in  the  usual  way).
+        be  used  for  capturing  (and  they acquire numbers in the usual way).
         There is no equivalent of this option in Perl.
           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. There is a  discussion  about  the  validity  of
+        automatically  checked.  There  is  a  discussion about the validity of
-        UTF-8  strings  in  the main pcre page. If an invalid UTF-8 sequence of
+        UTF-8 strings in the main pcre page. If an invalid  UTF-8  sequence  of
-        bytes is found, pcre_compile() returns an error. If  you  already  know
+        bytes  is  found,  pcre_compile() returns an error. If you already know
         that your pattern is valid, and you want to skip this check for perfor-
-        mance reasons, you can set the PCRE_NO_UTF8_CHECK option.  When  it  is
+        mance  reasons,  you  can set the PCRE_NO_UTF8_CHECK option. When it is
-        set,  the  effect  of  passing  an invalid UTF-8 string as a pattern is
+        set, the effect of passing an invalid UTF-8  string  as  a  pattern  is
-        undefined. It may cause your program to crash. Note  that  this  option
+        undefined.  It  may  cause your program to crash. Note that this option
-        can  also be passed to pcre_exec() and pcre_dfa_exec(), to suppress the
+        can also be passed to pcre_exec() and pcre_dfa_exec(), to suppress  the
         UTF-8 validity checking of subject strings.
  COMPILATION ERROR CODES
-        The following table lists the error  codes  than  may  be  returned  by
+        The  following  table  lists  the  error  codes than may be returned by
-        pcre_compile2(),  along with the error messages that may be returned by
+        pcre_compile2(), along with the error messages that may be returned  by
-        both compiling functions. As PCRE has developed, some error codes  have
+        both  compiling functions. As PCRE has developed, some error codes have
         fallen out of use. To avoid confusion, they have not been re-used.
  no error
-Line 1447 
 COMPILATION ERROR CODES
+Line 1445 
 COMPILATION ERROR CODES
  [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  not
         found
  DEFINE group contains more than one branch
  repeating a DEFINE group is not allowed
-Line 1462 
 COMPILATION ERROR CODES
+Line 1460 
 COMPILATION ERROR CODES
  digit expected after (?+
  ] is an invalid data character in JavaScript compatibility mode
-        The numbers 32 and 10000 in errors 48 and 49  are  defaults;  different
+        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.
-Line 1471 
 STUDYING A PATTERN
+Line 1469 
 STUDYING A PATTERN
         pcre_extra *pcre_study(const pcre *code, int options
              const char **errptr);
-        If  a  compiled  pattern is going to be used several times, it is worth
+        If a compiled pattern is going to be used several times,  it  is  worth
         spending more time analyzing it in order to speed up the time taken for
-        matching.  The function pcre_study() takes a pointer to a compiled pat-
+        matching. The function pcre_study() takes a pointer to a compiled  pat-
         tern as its first argument. If studying the pattern produces additional
-        information  that  will  help speed up matching, pcre_study() returns a
+        information that will help speed up matching,  pcre_study()  returns  a
-        pointer to a pcre_extra block, in which the study_data field points  to
+        pointer  to a pcre_extra block, in which the study_data field points to
         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().  However,  a  pcre_extra  block also contains other fields
-        that  can  be  set  by the caller before the block is passed; these are
+        that can be set by the caller before the block  is  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 additional 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(), it must set up
         its own pcre_extra block.
-        The  second  argument of pcre_study() contains option bits. At present,
+        The second argument of pcre_study() contains option bits.  At  present,
         no options are defined, and this argument should always be zero.
-        The third argument for pcre_study() is a pointer for an error  message.
+        The  third argument for pcre_study() is a pointer for an error message.
-        If  studying  succeeds  (even  if no data is returned), the variable it
+        If studying succeeds (even if no data is  returned),  the  variable  it
-        points to is set to NULL. Otherwise it is set to  point  to  a  textual
+        points  to  is  set  to NULL. Otherwise it is set to point to a textual
         error message. This is a static string that is part of the library. You
-        must not try to free it. You should test the  error  pointer  for  NULL
+        must  not  try  to  free it. You should test the error pointer for NULL
         after calling pcre_study(), to be sure that it has run successfully.
         This is a typical call to pcre_study():
-Line 1508 
 STUDYING A PATTERN
+Line 1506 
 STUDYING A PATTERN
             &error);        /* set to NULL or points to a message */
         At present, studying a pattern is useful only for non-anchored patterns
-        that do not have a single fixed starting character. A bitmap of  possi-
+        that  do not have a single fixed starting character. A bitmap of possi-
         ble starting bytes is created.
  LOCALE SUPPORT
-        PCRE  handles  caseless matching, and determines whether characters are
+        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
+        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. Higher-valued codes never match
-        escapes  such  as  \w or \d, but can be tested with \p if PCRE is built
+        escapes such as \w or \d, but can be tested with \p if  PCRE  is  built
-        with Unicode character property support. The use of locales  with  Uni-
+        with  Unicode  character property support. The use of locales with Uni-
-        code  is discouraged. If you are handling characters with codes greater
+        code is discouraged. If you are handling characters with codes  greater
-        than 128, you should either use UTF-8 and Unicode, or use locales,  but
+        than  128, you should either use UTF-8 and Unicode, or use locales, but
         not try to mix the two.
-        PCRE  contains  an  internal set of tables that are used when the final
+        PCRE contains an internal set of tables that are used  when  the  final
-        argument of pcre_compile() is  NULL.  These  are  sufficient  for  many
+        argument  of  pcre_compile()  is  NULL.  These  are sufficient for many
         applications.  Normally, the internal tables recognize only ASCII char-
         acters. However, when PCRE is built, it is possible to cause the inter-
         nal tables to be rebuilt in the default "C" locale of the local system,
         which may cause them to be different.
-        The internal tables can always be overridden by tables supplied by  the
+        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-
+        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,
+        External tables are built by calling  the  pcre_maketables()  function,
-        which has no arguments, in the relevant locale. The result can then  be
+        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
+        passed to pcre_compile() or pcre_exec()  as  often  as  necessary.  For
-        example, to build and use tables that are appropriate  for  the  French
+        example,  to  build  and use tables that are appropriate for the French
-        locale  (where  accented  characters  with  values greater than 128 are
+        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;
+        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
+        When pcre_maketables() runs, the tables are built  in  memory  that  is
-        obtained via pcre_malloc. It is the caller's responsibility  to  ensure
+        obtained  via  pcre_malloc. It is the caller's responsibility to ensure
-        that  the memory containing the tables remains available for as long as
+        that the memory containing the tables remains available for as long  as
         it is needed.
         The pointer that is passed to pcre_compile() is saved with the compiled
-        pattern,  and the same tables are used via this pointer by pcre_study()
+        pattern, and the same tables are used via this pointer by  pcre_study()
         and normally also by pcre_exec(). Thus, by default, for any single pat-
         tern, compilation, studying and matching all happen in the same locale,
         but different patterns can be compiled in different locales.
-        It is possible to pass a table pointer or NULL (indicating the  use  of
+        It  is  possible to pass a table pointer or NULL (indicating the use of
-        the  internal  tables)  to  pcre_exec(). Although not intended for this
+        the internal tables) to pcre_exec(). Although  not  intended  for  this
-        purpose, this facility could be used to match a pattern in a  different
+        purpose,  this facility could be used to match a pattern in a different
         locale from the one in which it was compiled. Passing table pointers at
         run time is discussed below in the section on matching a pattern.
-Line 1573 
 INFORMATION ABOUT A PATTERN
+Line 1571 
 INFORMATION ABOUT A PATTERN
         int pcre_fullinfo(const pcre *code, const pcre_extra *extra,
              int what, void *where);
-        The pcre_fullinfo() function returns information about a compiled  pat-
+        The  pcre_fullinfo() function returns information about a compiled pat-
         tern. It replaces the obsolete pcre_info() function, which is neverthe-
         less retained for backwards compability (and is documented below).
-        The first argument for pcre_fullinfo() is a  pointer  to  the  compiled
+        The  first  argument  for  pcre_fullinfo() is a pointer to the compiled
-        pattern.  The second argument is the result of pcre_study(), or NULL if
+        pattern. The second argument is the result of pcre_study(), or NULL  if
-        the pattern was not studied. The third argument specifies  which  piece
+        the  pattern  was not studied. The third argument specifies which piece
-        of  information  is required, and the fourth argument is a pointer to a
+        of information is required, and the fourth argument is a pointer  to  a
-        variable to receive the data. The yield of the  function  is  zero  for
+        variable  to  receive  the  data. The yield of the function is zero for
         success, or one of the following negative numbers:
           PCRE_ERROR_NULL       the argument code was NULL
-Line 1589 
 INFORMATION ABOUT A PATTERN
+Line 1587 
 INFORMATION ABOUT A PATTERN
           PCRE_ERROR_BADMAGIC   the "magic number" was not found
           PCRE_ERROR_BADOPTION  the value of what was invalid
-        The  "magic  number" is placed at the start of each compiled pattern as
+        The "magic number" is placed at the start of each compiled  pattern  as
-        an simple check against passing an arbitrary memory pointer. Here is  a
+        an  simple check against passing an arbitrary memory pointer. Here is a
-        typical  call  of pcre_fullinfo(), to obtain the length of the compiled
+        typical call of pcre_fullinfo(), to obtain the length of  the  compiled
         pattern:
           int rc;
-Line 1602 
 INFORMATION ABOUT A PATTERN
+Line 1600 
 INFORMATION ABOUT A PATTERN
             PCRE_INFO_SIZE,   /* what is required */
             &length);         /* where to put the data */
-        The possible values for the third argument are defined in  pcre.h,  and
+        The  possible  values for the third argument are defined in pcre.h, and
         are as follows:
           PCRE_INFO_BACKREFMAX
-        Return  the  number  of  the highest back reference in the pattern. The
+        Return the number of the highest back reference  in  the  pattern.  The
-        fourth argument should point to an int variable. Zero  is  returned  if
+        fourth  argument  should  point to an int variable. Zero is returned if
         there are no back references.
           PCRE_INFO_CAPTURECOUNT
-        Return  the  number of capturing subpatterns in the pattern. The fourth
+        Return the number of capturing subpatterns in the pattern.  The  fourth
         argument should point to an int variable.
           PCRE_INFO_DEFAULT_TABLES
-        Return a pointer to the internal default character tables within  PCRE.
+        Return  a pointer to the internal default character tables within PCRE.
-        The  fourth  argument should point to an unsigned char * variable. This
+        The fourth argument should point to an unsigned char *  variable.  This
         information call is provided for internal use by the pcre_study() func-
-        tion.  External  callers  can  cause PCRE to use its internal tables by
+        tion. External callers can cause PCRE to use  its  internal  tables  by
         passing a NULL table pointer.
           PCRE_INFO_FIRSTBYTE
-        Return information about the first byte of any matched  string,  for  a
+        Return  information  about  the first byte of any matched string, for a
-        non-anchored  pattern. The fourth argument should point to an int vari-
+        non-anchored pattern. The fourth argument should point to an int  vari-
-        able. (This option used to be called PCRE_INFO_FIRSTCHAR; the old  name
+        able.  (This option used to be called PCRE_INFO_FIRSTCHAR; the old name
         is still recognized for backwards compatibility.)
-        If  there  is  a  fixed first byte, for example, from a pattern such as
+        If there is a fixed first byte, for example, from  a  pattern  such  as
         (cat|cow|coyote), its value is returned. Otherwise, if either
-        (a) the pattern was compiled with the PCRE_MULTILINE option, and  every
+        (a)  the pattern was compiled with the PCRE_MULTILINE option, and every
         branch starts with "^", or
         (b) every branch of the pattern starts with ".*" and PCRE_DOTALL is not
         set (if it were set, the pattern would be anchored),
-        -1 is returned, indicating that the pattern matches only at  the  start
+        -1  is  returned, indicating that the pattern matches only at the start
-        of  a  subject string or after any newline within the string. Otherwise
+        of a subject string or after any newline within the  string.  Otherwise
         -2 is returned. For anchored patterns, -2 is returned.
           PCRE_INFO_FIRSTTABLE
-        If the pattern was studied, and this resulted in the construction of  a
+        If  the pattern was studied, and this resulted in the construction of a
 -bit table indicating a fixed set of bytes for the first byte in any
-        matching string, a pointer to the table is returned. Otherwise NULL  is
+        matching  string, a pointer to the table is returned. Otherwise NULL is
-        returned.  The fourth argument should point to an unsigned char * vari-
+        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
+        Return  1  if  the  pattern  contains any explicit matches for CR or LF
-        characters,  otherwise  0.  The  fourth argument should point to an int
+        characters, otherwise 0. The fourth argument should  point  to  an  int
-        variable. An explicit match is either a literal CR or LF character,  or
+        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,
+        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)
+        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.
-Line 1679 
 INFORMATION ABOUT A PATTERN
+Line 1677 
 INFORMATION ABOUT A PATTERN
           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. The names are in alphabetical order.
         When PCRE_DUPNAMES is set, duplicate names are in order of their paren-
-        theses numbers. For example, consider  the  following  pattern  (assume
+        theses  numbers.  For  example,  consider the following pattern (assume
-        PCRE_EXTENDED  is  set,  so  white  space  -  including  newlines  - is
+        PCRE_EXTENDED is  set,  so  white  space  -  including  newlines  -  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 1715 
 INFORMATION ABOUT A PATTERN
+Line 1713 
 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, otherwise 0.
+        Return 1 if the pattern can be used for partial matching, otherwise  0.
-        The fourth argument should point to an int  variable.  The  pcrepartial
+        The fourth argument should point to an int variable. From release 8.00,
-        documentation  lists  the restrictions that apply to patterns when par-
+        this always returns 1, because the restrictions that previously applied
-        tial matching is used.
+        to  partial  matching  have  been lifted. The pcrepartial documentation
+        gives details of partial matching.
           PCRE_INFO_OPTIONS
-Line 1929 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
+Line 1928 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
         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,
         PCRE_NOTBOL,    PCRE_NOTEOL,   PCRE_NOTEMPTY,   PCRE_NO_START_OPTIMIZE,
-        PCRE_NO_UTF8_CHECK and PCRE_PARTIAL.
+        PCRE_NO_UTF8_CHECK, PCRE_PARTIAL_SOFT, and PCRE_PARTIAL_HARD.
           PCRE_ANCHORED
-Line 2021 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
+Line 2020 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
         again at the same offset with PCRE_NOTEMPTY and PCRE_ANCHORED, and then
         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
-        this in the pcredemo.c sample program.
+        this in the pcredemo sample program.
           PCRE_NO_START_OPTIMIZE
-Line 2056 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
+Line 2055 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
         value  of startoffset that does not point to the start of a UTF-8 char-
         acter, is undefined. Your program may crash.
-          PCRE_PARTIAL
+          PCRE_PARTIAL_HARD
+          PCRE_PARTIAL_SOFT
-        This option turns on the  partial  matching  feature.  If  the  subject
+        These options turn on the partial matching feature. For backwards  com-
-        string  fails to match the pattern, but at some point during the match-
+        patibility,  PCRE_PARTIAL is a synonym for PCRE_PARTIAL_SOFT. A partial
-        ing process the end of the subject was reached (that  is,  the  subject
+        match occurs if the end of the subject string is reached  successfully,
-        partially  matches  the  pattern and the failure to match occurred only
+        but  there  are not enough subject characters to complete the match. If
-        because there were not enough subject characters), pcre_exec()  returns
+        this happens when PCRE_PARTIAL_HARD  is  set,  pcre_exec()  immediately
-        PCRE_ERROR_PARTIAL  instead of PCRE_ERROR_NOMATCH. When PCRE_PARTIAL is
+        returns  PCRE_ERROR_PARTIAL.  Otherwise,  if  PCRE_PARTIAL_SOFT is set,
-        used, there are restrictions on what may appear in the  pattern.  These
+        matching continues by testing any other alternatives. Only if they  all
-        are discussed in the pcrepartial documentation.
+        fail  is  PCRE_ERROR_PARTIAL  returned (instead of PCRE_ERROR_NOMATCH).
+        The portion of the string that provided the partial match is set as the
+        first  matching  string.  There  is  a  more detailed discussion 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 bytes) in length, and a starting byte offset in startoffset.
         In UTF-8 mode, the byte offset must point to the start of a UTF-8 char-
-        acter. Unlike the pattern string, the subject may contain  binary  zero
+        acter.  Unlike  the pattern string, the subject may contain binary zero
-        bytes.  When the starting offset is zero, the search for a match starts
+        bytes. When the starting offset is zero, the search for a match  starts
-        at the beginning of the subject, and this is by  far  the  most  common
+        at  the  beginning  of  the subject, and this is by far the most common
         case.
-        A  non-zero  starting offset is useful when searching for another match
+        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-
+        in  the same subject by calling pcre_exec() again after a previous suc-
-        cess.   Setting  startoffset differs from just passing over a shortened
+        cess.  Setting startoffset differs from just passing over  a  shortened
-        string and setting PCRE_NOTBOL in the case of  a  pattern  that  begins
+        string  and  setting  PCRE_NOTBOL  in the case of a pattern that begins
         with any kind of lookbehind. For example, consider the pattern
           \Biss\B
-        which  finds  occurrences  of "iss" in the middle of words. (\B matches
+        which finds occurrences of "iss" in the middle of  words.  (\B  matches
-        only if the current position in the subject is not  a  word  boundary.)
+        only  if  the  current position in the subject is not a word boundary.)
-        When  applied  to the string "Mississipi" the first call to pcre_exec()
+        When applied to the string "Mississipi" the first call  to  pcre_exec()
-        finds the first occurrence. If pcre_exec() is called  again  with  just
+        finds  the  first  occurrence. If pcre_exec() is called again with just
-        the  remainder  of  the  subject,  namely  "issipi", it does not match,
+        the remainder of the subject,  namely  "issipi",  it  does  not  match,
         because \B is always false at the start of the subject, which is deemed
-        to  be  a  word  boundary. However, if pcre_exec() is passed the entire
+        to be a word boundary. However, if pcre_exec()  is  passed  the  entire
         string again, but with startoffset set to 4, it finds the second occur-
-        rence  of "iss" because it is able to look behind the starting point to
+        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,
+        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 integers
-        whose address is passed in ovector. The number of elements in the  vec-
+        whose  address is passed in ovector. The number of elements in the vec-
-        tor  is  passed in ovecsize, which must be a non-negative number. Note:
+        tor is passed in ovecsize, which must be a non-negative  number.  Note:
         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 number 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 each pair is set to the byte offset of the  first  character
+        element  of  each pair is set to the byte offset of the first character
-        in  a  substring, and the second is set to the byte offset of the first
+        in a substring, and the second is set to the byte offset of  the  first
-        character after the end of a substring. Note: these values  are  always
+        character  after  the end of a substring. Note: these values are always
         byte offsets, even in UTF-8 mode. They are not character counts.
-        The  first  pair  of  integers, ovector[0] and ovector[1], identify the
+        The first pair of integers, ovector[0]  and  ovector[1],  identify  the
-        portion of the subject string matched by the entire pattern.  The  next
+        portion  of  the subject string matched by the entire pattern. The next
-        pair  is  used for the first capturing subpattern, and so on. The value
+        pair is used for the first capturing subpattern, and so on.  The  value
         returned by pcre_exec() is one more than the highest numbered pair that
-        has  been  set.  For example, if two substrings have been captured, the
+        has been set.  For example, if two substrings have been  captured,  the
-        returned value is 3. If there are no capturing subpatterns, the  return
+        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,
+        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. If the substring offsets are not of
+        function returns a value of zero. If the substring offsets are  not  of
-        interest, pcre_exec() may be called with ovector  passed  as  NULL  and
+        interest,  pcre_exec()  may  be  called with ovector passed as NULL and
-        ovecsize  as zero. However, if the pattern contains back references and
+        ovecsize as zero. However, if the pattern contains back references  and
-        the ovector is not big enough to remember the related substrings,  PCRE
+        the  ovector is not big enough to remember the related substrings, PCRE
-        has  to  get additional memory for use during matching. Thus it is usu-
+        has to get additional memory for use during matching. Thus it  is  usu-
         ally advisable to supply an ovector.
-        The pcre_info() function can be used to find  out  how  many  capturing
+        The  pcre_info()  function  can  be used to find out how many capturing
-        subpatterns  there  are  in  a  compiled pattern. The smallest size for
+        subpatterns there are in a compiled  pattern.  The  smallest  size  for
-        ovector that will allow for n captured substrings, in addition  to  the
+        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.
-        It  is  possible for capturing subpattern number n+1 to match some part
+        It is possible for capturing subpattern number n+1 to match  some  part
         of the subject when subpattern n has not been used at all. For example,
-        if  the  string  "abc"  is  matched against the pattern (a|(z))(bc) the
+        if the string "abc" is matched  against  the  pattern  (a|(z))(bc)  the
         return from the function is 4, and subpatterns 1 and 3 are matched, but
- is  not.  When  this happens, both values in the offset pairs corre-
+is not. When this happens, both values in  the  offset  pairs  corre-
         sponding to unused subpatterns are set to -1.
-        Offset values that correspond to unused subpatterns at the end  of  the
+        Offset  values  that correspond to unused subpatterns at the end of the
-        expression  are  also  set  to  -1. For example, if the string "abc" is
+        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  against the pattern (abc)(x(yz)?)? subpatterns 2 and 3 are not
-        matched.  The  return  from the function is 2, because the highest used
+        matched. The return from the function is 2, because  the  highest  used
         capturing subpattern number is 1. However, you can refer to the offsets
-        for  the  second  and third capturing subpatterns if you wish (assuming
+        for the second and third capturing subpatterns if  you  wish  (assuming
         the vector is large enough, of course).
-        Some convenience functions are provided  for  extracting  the  captured
+        Some  convenience  functions  are  provided for extracting the captured
         substrings as separate strings. These are described below.
     Error return values from pcre_exec()
-        If  pcre_exec()  fails, it returns a negative number. The following are
+        If pcre_exec() fails, it returns a negative number. The  following  are
         defined in the header file:
           PCRE_ERROR_NOMATCH        (-1)
-Line 2186 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
+Line 2189 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
           PCRE_ERROR_NULL           (-2)
-        Either code or subject was passed as NULL,  or  ovector  was  NULL  and
+        Either  code  or  subject  was  passed as NULL, or ovector was NULL and
         ovecsize was not zero.
           PCRE_ERROR_BADOPTION      (-3)
-Line 2195 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
+Line 2198 
 MATCHING A PATTERN: THE TRADITIONAL FUNC
           PCRE_ERROR_BADMAGIC       (-4)
-        PCRE  stores a 4-byte "magic number" at the start of the compiled code,
+        PCRE stores a 4-byte "magic number" at the start of the compiled  code,
         to catch the case when it is passed a junk pointer and to detect when a
         pattern that was compiled in an environment of one endianness is run in
-        an environment with the other endianness. This is the error  that  PCRE
+        an  environment  with the other endianness. This is the error that PCRE
         gives when the magic number is not present.
           PCRE_ERROR_UNKNOWN_OPCODE (-5)
         While running the pattern match, an unknown item was encountered in the
-        compiled pattern. This error could be caused by a bug  in  PCRE  or  by
+        compiled  pattern.  This  error  could be caused by a bug in PCRE or by
         overwriting of the compiled pattern.
           PCRE_ERROR_NOMEMORY       (-6)
-        If  a  pattern contains back references, but the ovector that is passed
+        If a pattern contains back references, but the ovector that  is  passed
         to pcre_exec() is not big enough to remember the referenced substrings,
-        PCRE  gets  a  block of memory at the start of matching to use for this
+        PCRE gets a block of memory at the start of matching to  use  for  this
-        purpose. If the call via pcre_malloc() fails, this error is given.  The
+        purpose.  If the call via pcre_malloc() fails, this error is given. The
         memory is automatically freed at the end of matching.
           PCRE_ERROR_NOSUBSTRING    (-7)
-        This  error is used by the pcre_copy_substring(), pcre_get_substring(),
+        This error is used by the pcre_copy_substring(),  pcre_get_substring(),
         and  pcre_get_substring_list()  functions  (see  below).  It  is  never
         returned by pcre_exec().
           PCRE_ERROR_MATCHLIMIT     (-8)
-        The  backtracking  limit,  as  specified  by the match_limit field in a
+        The backtracking limit, as specified by  the  match_limit  field  in  a
-        pcre_extra structure (or defaulted) was reached.  See  the  description
+        pcre_extra  structure  (or  defaulted) was reached. See the description
         above.
           PCRE_ERROR_CALLOUT        (-9)
         This error is never generated by pcre_exec() itself. It is provided for
-        use by callout functions that want to yield a distinctive  error  code.
+        use  by  callout functions that want to yield a distinctive error code.
         See the pcrecallout documentation for details.
           PCRE_ERROR_BADUTF8        (-10)
-        A  string  that contains an invalid UTF-8 byte sequence was passed as a
+        A string that contains an invalid UTF-8 byte sequence was passed  as  a
         subject.
           PCRE_ERROR_BADUTF8_OFFSET (-11)
         The UTF-8 byte sequence that was passed as a subject was valid, but the
-        value  of startoffset did not point to the beginning of a UTF-8 charac-
+        value of startoffset did not point to the beginning of a UTF-8  charac-
         ter.
           PCRE_ERROR_PARTIAL        (-12)
-        The subject string did not match, but it did match partially.  See  the
+        The  subject  string did not match, but it did match partially. See the
         pcrepartial documentation for details of partial matching.
           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)
-Line 2517 
 MATCHING A PATTERN: THE ALTERNATIVE FUNC
+Line 2521 
 MATCHING A PATTERN: THE ALTERNATIVE FUNC
         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-
         LINE_xxx, PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY,  PCRE_NO_UTF8_CHECK,
-        PCRE_PARTIAL, PCRE_DFA_SHORTEST, and PCRE_DFA_RESTART. All but the last
+        PCRE_PARTIAL_HARD,     PCRE_PARTIAL_SOFT,     PCRE_DFA_SHORTEST,    and
-        three of these are the same as for pcre_exec(), so their description is
+        PCRE_DFA_RESTART. All but the last four of these are exactly  the  same
-        not repeated here.
+        as for pcre_exec(), so their description is not repeated here.
-          PCRE_PARTIAL
+          PCRE_PARTIAL_HARD
+          PCRE_PARTIAL_SOFT
-        This  has  the  same general effect as it does for pcre_exec(), but the
-        details  are  slightly  different.  When  PCRE_PARTIAL   is   set   for
+        These  have the same general effect as they do for pcre_exec(), but the
-        pcre_dfa_exec(),  the  return code PCRE_ERROR_NOMATCH is converted into
+        details are slightly  different.  When  PCRE_PARTIAL_HARD  is  set  for
-        PCRE_ERROR_PARTIAL if the end of the subject  is  reached,  there  have
+        pcre_dfa_exec(),  it  returns PCRE_ERROR_PARTIAL if the end of the sub-
-        been no complete matches, but there is still at least one matching pos-
+        ject is reached and there is still at least  one  matching  possibility
-        sibility. The portion of the string that provided the partial match  is
+        that requires additional characters. This happens even if some complete
-        set as the first matching string.
+        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 provided the longest partial match  is  set  as  the  first
+        matching string in both cases.
           PCRE_DFA_SHORTEST
-Line 2540 
 MATCHING A PATTERN: THE ALTERNATIVE FUNC
+Line 2549 
 MATCHING A PATTERN: THE ALTERNATIVE FUNC
           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()
-        When  pcre_dfa_exec()  succeeds, it may have matched more than one sub-
+        When pcre_dfa_exec() succeeds, it may have matched more than  one  sub-
         string in the subject. Note, however, that all the matches from one run
-        of  the  function  start  at the same point in the subject. The shorter
+        of the function start at the same point in  the  subject.  The  shorter
-        matches are all initial substrings of the longer matches. For  example,
+        matches  are all initial substrings of the longer matches. For example,
         if the pattern
           <.*>
-Line 2569 
 MATCHING A PATTERN: THE ALTERNATIVE FUNC
+Line 2577 
 MATCHING A PATTERN: THE ALTERNATIVE FUNC
           <something> <something else>
           <something> <something else> <something further>
-        On  success,  the  yield of the function is a number greater than zero,
+        On success, the yield of the function is a number  greater  than  zero,
-        which is the number of matched substrings.  The  substrings  themselves
+        which  is  the  number of matched substrings. The substrings themselves
-        are  returned  in  ovector. Each string uses two elements; the first is
+        are returned in ovector. Each string uses two elements;  the  first  is
-        the offset to the start, and the second is the offset to  the  end.  In
+        the  offset  to  the start, and the second is the offset to the end. In
-        fact,  all  the  strings  have the same start offset. (Space could have
+        fact, all the strings have the same start  offset.  (Space  could  have
-        been saved by giving this only once, but it was decided to retain  some
+        been  saved by giving this only once, but it was decided to retain some
-        compatibility  with  the  way pcre_exec() returns data, even though the
+        compatibility with the way pcre_exec() returns data,  even  though  the
         meaning of the strings is different.)
         The strings are returned in reverse order of length; that is, the long-
-        est  matching  string is given first. If there were too many matches to
+        est matching string is given first. If there were too many  matches  to
-        fit into ovector, the yield of the function is zero, and the vector  is
+        fit  into ovector, the yield of the function is zero, and the vector is
         filled with the longest matches.
     Error returns from pcre_dfa_exec()
-        The  pcre_dfa_exec()  function returns a negative number when it fails.
+        The pcre_dfa_exec() function returns a negative number when  it  fails.
-        Many of the errors are the same  as  for  pcre_exec(),  and  these  are
+        Many  of  the  errors  are  the  same as for pcre_exec(), and these are
-        described  above.   There are in addition the following errors that are
+        described above.  There are in addition the following errors  that  are
         specific to pcre_dfa_exec():
           PCRE_ERROR_DFA_UITEM      (-16)
-        This return is given if pcre_dfa_exec() encounters an item in the  pat-
+        This  return is given if pcre_dfa_exec() encounters an item in the pat-
-        tern  that  it  does not support, for instance, the use of \C or a back
+        tern that it does not support, for instance, the use of \C  or  a  back
         reference.
           PCRE_ERROR_DFA_UCOND      (-17)
-        This return is given if pcre_dfa_exec()  encounters  a  condition  item
+        This  return  is  given  if pcre_dfa_exec() encounters a condition item
-        that  uses  a back reference for the condition, or a test for recursion
+        that uses a back reference for the condition, or a test  for  recursion
         in a specific group. These are not supported.
           PCRE_ERROR_DFA_UMLIMIT    (-18)
-        This return is given if pcre_dfa_exec() is called with an  extra  block
+        This  return  is given if pcre_dfa_exec() is called with an extra block
         that contains a setting of the match_limit field. This is not supported
         (it is meaningless).
           PCRE_ERROR_DFA_WSSIZE     (-19)
-        This return is given if  pcre_dfa_exec()  runs  out  of  space  in  the
+        This  return  is  given  if  pcre_dfa_exec()  runs  out of space in the
         workspace vector.
           PCRE_ERROR_DFA_RECURSE    (-20)
-        When  a  recursive subpattern is processed, the matching function calls
+        When a recursive subpattern is processed, the matching  function  calls
-        itself recursively, using private vectors for  ovector  and  workspace.
+        itself  recursively,  using  private vectors for ovector and workspace.
-        This  error  is  given  if  the output vector is not large enough. This
+        This error is given if the output vector  is  not  large  enough.  This
         should be extremely rare, as a vector of size 1000 is used.
  SEE ALSO
-        pcrebuild(3), pcrecallout(3), pcrecpp(3)(3), pcrematching(3),  pcrepar-
+        pcrebuild(3),  pcrecallout(3), pcrecpp(3)(3), pcrematching(3), pcrepar-
         tial(3), pcreposix(3), pcreprecompile(3), pcresample(3), pcrestack(3).
-Line 2636 
 AUTHOR
+Line 2644 
 AUTHOR
  REVISION
-        Last updated: 11 April 2009
+        Last updated: 01 September 2009
         Copyright (c) 1997-2009 University of Cambridge.
  ------------------------------------------------------------------------------
  PCRECALLOUT(3)                                                  PCRECALLOUT(3)
-Line 2815 
 REVISION
+Line 2823 
 REVISION
         Last updated: 15 March 2009
         Copyright (c) 1997-2009 University of Cambridge.
  ------------------------------------------------------------------------------
  PCRECOMPAT(3)                                                    PCRECOMPAT(3)
-Line 2829 
 DIFFERENCES BETWEEN PCRE AND PERL
+Line 2837 
 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
         with  respect  to  Perl 5.8, though PCRE versions 7.0 and later contain
-        some features that are expected to be in the forthcoming Perl 5.10.
+        some features that are in Perl 5.10.
 . 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
-Line 2953 
 AUTHOR
+Line 2961 
 AUTHOR
  REVISION
-        Last updated: 11 September 2007
+        Last updated: 25 August 2009
-        Copyright (c) 1997-2007 University of Cambridge.
+        Copyright (c) 1997-2009 University of Cambridge.
  ------------------------------------------------------------------------------
  PCREPATTERN(3)                                                  PCREPATTERN(3)
-Line 5034 
 REVISION
+Line 5042 
 REVISION
         Last updated: 11 April 2009
         Copyright (c) 1997-2009 University of Cambridge.
  ------------------------------------------------------------------------------
  PCRESYNTAX(3)                                                    PCRESYNTAX(3)
-Line 5387 
 REVISION
+Line 5395 
 REVISION
         Last updated: 11 April 2009
         Copyright (c) 1997-2009 University of Cambridge.
  ------------------------------------------------------------------------------
  PCREPARTIAL(3)                                                  PCREPARTIAL(3)
-Line 5412 
 PARTIAL MATCHING IN PCRE
+Line 5420 
 PARTIAL MATCHING IN PCRE
         If the application sees the user's keystrokes one by one, and can check
         that what has been typed so far is potentially valid,  it  is  able  to
-        raise  an  error as soon as a mistake is made, possibly beeping and not
+        raise  an  error  as  soon  as  a  mistake  is made, by beeping and not
-        reflecting the character that has been typed. This  immediate  feedback
+        reflecting the character that has been typed, for example. This immedi-
-        is  likely  to  be a better user interface than a check that is delayed
+        ate  feedback is likely to be a better user interface than a check that
-        until the entire string has been entered.
+        is delayed until the entire string has been entered.  Partial  matching
+        can  also  sometimes be useful when the subject string is very long and
-        PCRE supports the concept of partial matching by means of the PCRE_PAR-
+        is not all available at once.
-        TIAL   option,   which   can   be   set  when  calling  pcre_exec()  or
-        pcre_dfa_exec(). When this flag is set for pcre_exec(), the return code
+        PCRE supports partial matching by means of  the  PCRE_PARTIAL_SOFT  and
-        PCRE_ERROR_NOMATCH  is converted into PCRE_ERROR_PARTIAL if at any time
+        PCRE_PARTIAL_HARD options, which can be set when calling pcre_exec() or
-        during the matching process the last part of the subject string matched
+        pcre_dfa_exec(). For backwards compatibility, PCRE_PARTIAL is a synonym
-        part  of  the  pattern. Unfortunately, for non-anchored matching, it is
+        for PCRE_PARTIAL_SOFT. The essential difference between the two options
-        not possible to obtain the position of the start of the partial  match.
+        is whether or not a partial match is preferred to an  alternative  com-
-        No captured data is set when PCRE_ERROR_PARTIAL is returned.
+        plete  match,  though the details differ between the two matching func-
+        tions. If both options are set, PCRE_PARTIAL_HARD takes precedence.
-        When   PCRE_PARTIAL   is  set  for  pcre_dfa_exec(),  the  return  code
-        PCRE_ERROR_NOMATCH is converted into PCRE_ERROR_PARTIAL if the  end  of
+        Setting a partial matching option disables one of PCRE's optimizations.
-        the  subject is reached, there have been no complete matches, but there
+        PCRE  remembers the last literal byte in a pattern, and abandons match-
-        is still at least one matching possibility. The portion of  the  string
+        ing immediately if such a byte is not present in  the  subject  string.
-        that provided the partial match is set as the first matching string.
+        This  optimization cannot be used for a subject string that might match
+        only partially.
-        Using PCRE_PARTIAL disables one of PCRE's optimizations. PCRE remembers
-        the last literal byte in a pattern, and abandons  matching  immediately
-        if  such a byte is not present in the subject string. This optimization
+ PARTIAL MATCHING USING pcre_exec()
-        cannot be used for a subject string that might match only partially.
+        A partial match occurs during a call to pcre_exec() whenever the end of
+        the  subject  string  is reached successfully, but matching cannot con-
- RESTRICTED PATTERNS FOR PCRE_PARTIAL
+        tinue because more characters are needed. However, at least one charac-
+        ter  must have been matched. (In other words, a partial match can never
-        Because of the way certain internal optimizations  are  implemented  in
+        be an empty string.)
-        the  pcre_exec()  function, the PCRE_PARTIAL option cannot be used with
-        all patterns. These restrictions do not apply when  pcre_dfa_exec()  is
+        If PCRE_PARTIAL_SOFT is set,  the  partial  match  is  remembered,  but
-        used.  For pcre_exec(), repeated single characters such as
+        matching continues as normal, and other alternatives in the pattern are
+        tried.  If  no  complete  match  can  be  found,  pcre_exec()   returns
-          a{2,4}
+        PCRE_ERROR_PARTIAL  instead  of PCRE_ERROR_NOMATCH, and if there are at
+        least two slots in the offsets vector, they are filled in with the off-
-        and repeated single metasequences such as
+        sets  of  the longest string that partially matched. Consider this pat-
+        tern:
-          \d+
+          /123\w+X|dogY/
-        are  not permitted if the maximum number of occurrences is greater than
-        one.  Optional items such as \d? (where the maximum is one) are permit-
+        If this is matched against the subject string "abc123dog", both  alter-
-        ted.   Quantifiers  with any values are permitted after parentheses, so
+        natives  fail  to  match,  but the end of the subject is reached during
-        the invalid examples above can be coded thus:
+        matching,   so    PCRE_ERROR_PARTIAL    is    returned    instead    of
+        PCRE_ERROR_NOMATCH.  The  offsets  are  set  to  3  and  9, identifying
-          (a){2,4}
+        "123dog" as the longest partial match that was found. (In this example,
-          (\d)+
+        there  are  two  partial  matches,  because  "dog" on its own partially
+        matches the second alternative.)
-        These constructions run more slowly, but for the kinds  of  application
-        that  are  envisaged  for this facility, this is not felt to be a major
+        If PCRE_PARTIAL_HARD is set for pcre_exec(), it returns PCRE_ERROR_PAR-
-        restriction.
+        TIAL  as soon as a partial match is found, without continuing to search
+        for possible complete matches. The difference between the  two  options
-        If PCRE_PARTIAL is set for a pattern  that  does  not  conform  to  the
+        can be illustrated by a pattern such as:
-        restrictions,  pcre_exec() returns the error code PCRE_ERROR_BADPARTIAL
-        (-13).  You can use the PCRE_INFO_OKPARTIAL call to pcre_fullinfo()  to
+          /dog(sbody)?/
-        find out if a compiled pattern can be used for partial matching.
+        This  matches either "dog" or "dogsbody", greedily (that is, it prefers
+        the longer string if possible). If it is  matched  against  the  string
+        "dog"  with  PCRE_PARTIAL_SOFT,  it  yields a complete match for "dog".
+        However, if PCRE_PARTIAL_HARD is set, the result is PCRE_ERROR_PARTIAL.
+        On  the  other hand, if the pattern is made ungreedy the result is dif-
+        ferent:
+          /dog(sbody)??/
+        In this case the result is always a complete match because  pcre_exec()
+        finds  that  first,  and  it  never continues after finding a match. It
+        might be easier to follow this explanation by thinking of the two  pat-
+        terns like this:
+          /dog(sbody)?/    is the same as  /dogsbody|dog/
+          /dog(sbody)??/   is the same as  /dog|dogsbody/
+        The  second  pattern  will  never  match "dogsbody" when pcre_exec() is
+        used, because it will always find the shorter match first.
+ PARTIAL MATCHING USING pcre_dfa_exec()
+        The pcre_dfa_exec() function moves along the subject  string  character
+        by  character, without backtracking, searching for all possible matches
+        simultaneously. If the end of the subject is reached before the end  of
+        the  pattern,  there  is the possibility of a partial match, again pro-
+        vided that at least one character has matched.
+        When PCRE_PARTIAL_SOFT is set, PCRE_ERROR_PARTIAL is returned  only  if
+        there  have  been  no complete matches. Otherwise, the complete matches
+        are returned.  However, if PCRE_PARTIAL_HARD is set,  a  partial  match
+        takes  precedence  over any complete matches. The portion of the string
+        that provided the longest partial match is set as  the  first  matching
+        string, provided there are at least two slots in the offsets vector.
+        Because  pcre_dfa_exec()  always searches for all possible matches, and
+        there is no difference between greedy and ungreedy repetition, its  be-
+        haviour is different from pcre_exec when PCRE_PARTIAL_HARD is set. Con-
+        sider the string "dog"  matched  against  the  ungreedy  pattern  shown
+        above:
+          /dog(sbody)??/
+        Whereas  pcre_exec()  stops  as soon as it finds the complete match for
+        "dog", pcre_dfa_exec() also finds the partial match for "dogsbody", and
+        so returns that when PCRE_PARTIAL_HARD is set.
+ PARTIAL MATCHING AND WORD BOUNDARIES
+        If  a  pattern ends with one of sequences \w or \W, which test for word
+        boundaries, partial matching with PCRE_PARTIAL_SOFT can  give  counter-
+        intuitive results. Consider this pattern:
+          /\bcat\b/
+        This matches "cat", provided there is a word boundary at either end. If
+        the subject string is "the cat", the comparison of the final "t" with a
+        following  character  cannot  take  place, so a partial match is found.
+        However, pcre_exec() carries on with normal matching, which matches  \b
+        at  the  end  of  the subject when the last character is a letter, thus
+        finding a complete match. The result, therefore, is not PCRE_ERROR_PAR-
+        TIAL.  The  same  thing  happens  with pcre_dfa_exec(), because it also
+        finds the complete match.
+        Using PCRE_PARTIAL_HARD in this  case  does  yield  PCRE_ERROR_PARTIAL,
+        because then the partial match takes precedence.
+ FORMERLY RESTRICTED PATTERNS
+        For releases of PCRE prior to 8.00, because of the way certain internal
+        optimizations  were  implemented  in  the  pcre_exec()  function,   the
+        PCRE_PARTIAL  option  (predecessor  of  PCRE_PARTIAL_SOFT) could not be
+        used with all patterns. From release 8.00 onwards, the restrictions  no
+        longer  apply,  and  partial matching with pcre_exec() can be requested
+        for any pattern.
+        Items that were formerly restricted were repeated single characters and
+        repeated  metasequences. If PCRE_PARTIAL was set for a pattern that did
+        not conform to the restrictions, pcre_exec() returned  the  error  code
+        PCRE_ERROR_BADPARTIAL  (-13).  This error code is no longer in use. The
+        PCRE_INFO_OKPARTIAL call to pcre_fullinfo() to find out if  a  compiled
+        pattern can be used for partial matching now always returns 1.
  EXAMPLE OF PARTIAL MATCHING USING PCRETEST
         If  the  escape  sequence  \P  is  present in a pcretest data line, the
-        PCRE_PARTIAL flag is used for the match. Here is a run of pcretest that
+        PCRE_PARTIAL_SOFT option is used for  the  match.  Here  is  a  run  of
-        uses the date example quoted above:
+        pcretest that uses the date example quoted above:
             re> /^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$/
           data> 25jun04\P
 : 25jun04
 : jun
           data> 25dec3\P
-          Partial match
+          Partial match: 23dec3
           data> 3ju\P
-          Partial match
+          Partial match: 3ju
           data> 3juj\P
           No match
           data> j\P
-Line 5490 
 EXAMPLE OF PARTIAL MATCHING USING PCRETE
+Line 5583 
 EXAMPLE OF PARTIAL MATCHING USING PCRETE
         The  first  data  string  is  matched completely, so pcretest shows the
         matched substrings. The remaining four strings do not  match  the  com-
-        plete  pattern,  but  the first two are partial matches. The same test,
+        plete pattern, but the first two are partial matches. Similar output is
-        using pcre_dfa_exec() matching (by means of the  \D  escape  sequence),
+        obtained when pcre_dfa_exec() is used.
-        produces the following output:
-            re> /^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$/
+        If the escape sequence \P is present more than once in a pcretest  data
-          data> 25jun04\P\D
+        line, the PCRE_PARTIAL_HARD option is set for the match.
-: 25jun04
-          data> 23dec3\P\D
-          Partial match: 23dec3
-          data> 3ju\P\D
-          Partial match: 3ju
-          data> 3juj\P\D
-          No match
-          data> j\P\D
-          No match
-        Notice  that in this case the portion of the string that was matched is
-        made available.
  MULTI-SEGMENT MATCHING WITH pcre_dfa_exec()
         When a partial match has been found using pcre_dfa_exec(), it is possi-
-        ble  to  continue  the  match  by providing additional subject data and
+        ble to continue the match by  providing  additional  subject  data  and
-        calling pcre_dfa_exec() again with the same  compiled  regular  expres-
+        calling  pcre_dfa_exec()  again  with the same compiled regular expres-
-        sion, this time setting the PCRE_DFA_RESTART option. You must also pass
+        sion, this time setting the PCRE_DFA_RESTART option. You must pass  the
-        the same working space as before, because this is where details of  the
+        same working space as before, because this is where details of the pre-
-        previous  partial  match are stored. Here is an example using pcretest,
+        vious partial match are stored. Here  is  an  example  using  pcretest,
-        using the \R escape sequence to set the PCRE_DFA_RESTART option (\P and
+        using  the  \R  escape  sequence to set the PCRE_DFA_RESTART option (\D
-        \D are as above):
+        specifies the use of pcre_dfa_exec()):
             re> /^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$/
           data> 23ja\P\D
-Line 5527 
 MULTI-SEGMENT MATCHING WITH pcre_dfa_exe
+Line 5607 
 MULTI-SEGMENT MATCHING WITH pcre_dfa_exe
           data> n05\R\D
 : n05
-        The  first  call has "23ja" as the subject, and requests partial match-
+        The first call has "23ja" as the subject, and requests  partial  match-
-        ing; the second call  has  "n05"  as  the  subject  for  the  continued
+        ing;  the  second  call  has  "n05"  as  the  subject for the continued
-        (restarted)  match.   Notice  that when the match is complete, only the
+        (restarted) match.  Notice that when the match is  complete,  only  the
-        last part is shown; PCRE does  not  retain  the  previously  partially-
+        last  part  is  shown;  PCRE  does not retain the previously partially-
-        matched  string. It is up to the calling program to do that if it needs
+        matched string. It is up to the calling program to do that if it  needs
         to.
-        You can set PCRE_PARTIAL  with  PCRE_DFA_RESTART  to  continue  partial
+        You  can  set  the  PCRE_PARTIAL_SOFT or PCRE_PARTIAL_HARD options with
-        matching over multiple segments. This facility can be used to pass very
+        PCRE_DFA_RESTART to continue partial matching over  multiple  segments.
-        long subject strings to pcre_dfa_exec(). However, some care  is  needed
+        This  facility  can  be  used  to  pass  very  long  subject strings to
-        for certain types of pattern.
+        pcre_dfa_exec().
-.  If  the  pattern contains tests for the beginning or end of a line,
-        you need to pass the PCRE_NOTBOL or PCRE_NOTEOL options,  as  appropri-
+ MULTI-SEGMENT MATCHING WITH pcre_exec()
-        ate,  when  the subject string for any call does not contain the begin-
+        From release 8.00, pcre_exec() can also be  used  to  do  multi-segment
+        matching.  Unlike  pcre_dfa_exec(),  it  is not possible to restart the
+        previous match with a new segment of data. Instead, new  data  must  be
+        added  to  the  previous  subject  string, and the entire match re-run,
+        starting from the point where the partial match occurred. Earlier  data
+        can be discarded.  Consider an unanchored pattern that matches dates:
+            re> /\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d/
+          data> The date is 23ja\P
+          Partial match: 23ja
+        The this stage, an application could discard the text preceding "23ja",
+        add on text from the next segment, and call pcre_exec()  again.  Unlike
+        pcre_dfa_exec(),  the  entire matching string must always be available,
+        and the complete matching process occurs for each call, so more  memory
+        and more processing time is needed.
+ ISSUES WITH MULTI-SEGMENT MATCHING
+        Certain types of pattern may give problems with multi-segment matching,
+        whichever matching function is used.
+. If the pattern contains tests for the beginning or end  of  a  line,
+        you  need  to pass the PCRE_NOTBOL or PCRE_NOTEOL options, as appropri-
+        ate, when the subject string for any call does not contain  the  begin-
         ning or end of a line.
-. If the pattern contains backward assertions (including  \b  or  \B),
+.  If  the  pattern contains backward assertions (including \b or \B),
-        you  need  to  arrange for some overlap in the subject strings to allow
+        you need to arrange for some overlap in the subject  strings  to  allow
-        for this. For example, you could pass the subject in  chunks  that  are
+        for  them  to  be  correctly tested at the start of each substring. For
- bytes long, but in a buffer of 700 bytes, with the starting offset
+        example, using pcre_dfa_exec(), you could pass the  subject  in  chunks
-        set to 200 and the previous 200 bytes at the start of the buffer.
+        that  are 500 bytes long, but in a buffer of 700 bytes, with the start-
+        ing offset set to 200 and the previous 200 bytes at the  start  of  the
-. Matching a subject string that is split into multiple segments  does
+        buffer.
-        not  always produce exactly the same result as matching over one single
-        long string.  The difference arises when there  are  multiple  matching
+.  Matching  a subject string that is split into multiple segments may
-        possibilities,  because a partial match result is given only when there
+        not always produce exactly the same result as matching over one  single
-        are no completed matches in a call to pcre_dfa_exec(). This means  that
+        long  string,  especially  when  PCRE_PARTIAL_SOFT is used. The section
-        as  soon  as  the  shortest match has been found, continuation to a new
+        "Partial Matching and Word Boundaries" above describes  an  issue  that
-        subject segment is no longer possible.  Consider this pcretest example:
+        arises  if  the  pattern ends with \b or \B. Another kind of difference
+        may occur when there are multiple  matching  possibilities,  because  a
+        partial match result is given only when there are no completed matches.
+        This means that as soon as the shortest match has been found, continua-
+        tion  to  a  new subject segment is no longer possible.  Consider again
+        this pcretest example:
             re> /dog(sbody)?/
+          data> dogsb\P
+: dog
           data> do\P\D
           Partial match: do
           data> gsb\R\P\D
-Line 5567 
 MULTI-SEGMENT MATCHING WITH pcre_dfa_exe
+Line 5680 
 MULTI-SEGMENT MATCHING WITH pcre_dfa_exe
 : dogsbody
 : dog
-        The pattern matches the words "dog" or "dogsbody". When the subject  is
+        The first data line passes the string "dogsb" to  pcre_exec(),  setting
-        presented  in  several  parts  ("do" and "gsb" being the first two) the
+        the  PCRE_PARTIAL_SOFT  option.  Although the string is a partial match
-        match stops when "dog" has been found, and it is not possible  to  con-
+        for "dogsbody", the  result  is  not  PCRE_ERROR_PARTIAL,  because  the
-        tinue.  On  the  other  hand,  if  "dogsbody"  is presented as a single
+        shorter  string  "dog" is a complete match. Similarly, when the subject
-        string, both matches are found.
+        is presented to pcre_dfa_exec() in several parts ("do" and "gsb"  being
+        the first two) the match stops when "dog" has been found, and it is not
+        possible to continue. On the other hand, if "dogsbody" is presented  as
+        a single string, pcre_dfa_exec() finds both matches.
+        Because of these problems, it is probably best to use PCRE_PARTIAL_HARD
+        when matching multi-segment data. The example above then  behaves  dif-
+        ferently:
+            re> /dog(sbody)?/
+          data> dogsb\P\P
+          Partial match: dogsb
+          data> do\P\D
+          Partial match: do
+          data> gsb\R\P\P\D
+          Partial match: gsb
-        Because of this phenomenon, it does not usually make  sense  to  end  a
-        pattern that is going to be matched in this way with a variable repeat.
 . Patterns that contain alternatives at the top level which do not all
-        start with the same pattern item may not work as expected. For example,
+        start with the  same  pattern  item  may  not  work  as  expected  when
-        consider this pattern:
+        pcre_dfa_exec() is used. For example, consider this pattern:
 |3789
-Line 5586 
 MULTI-SEGMENT MATCHING WITH pcre_dfa_exe
+Line 5712 
 MULTI-SEGMENT MATCHING WITH pcre_dfa_exe
         first alternative is found at offset 3. There is no partial  match  for
         the second alternative, because such a match does not start at the same
         point in the subject string. Attempting to  continue  with  the  string
-        "789" does not yield a match because only those alternatives that match
+        "7890"  does  not  yield  a  match because only those alternatives that
-        at one point in the subject are remembered. The problem arises  because
+        match at one point in the subject are remembered.  The  problem  arises
-        the  start  of the second alternative matches within the first alterna-
+        because  the  start  of the second alternative matches within the first
-        tive. There is no problem with anchored patterns or patterns such as:
+        alternative. There is no problem with  anchored  patterns  or  patterns
+        such as:
 |ABCD
-        where no string can be a partial match for both alternatives.
+        where  no  string can be a partial match for both alternatives. This is
+        not a problem if pcre_exec() is used, because the entire match  has  to
+        be rerun each time:
+            re> /1234|3789/
+          data> ABC123\P
+          Partial match: 123
+          data> 1237890
+: 3789
  AUTHOR
-Line 5605 
 AUTHOR
+Line 5740 
 AUTHOR
  REVISION
-        Last updated: 04 June 2007
+        Last updated: 31 August 2009
-        Copyright (c) 1997-2007 University of Cambridge.
+        Copyright (c) 1997-2009 University of Cambridge.
  ------------------------------------------------------------------------------
  PCREPRECOMPILE(3)                                            PCREPRECOMPILE(3)
-Line 5732 
 REVISION
+Line 5867 
 REVISION
         Last updated: 13 June 2007
         Copyright (c) 1997-2007 University of Cambridge.
  ------------------------------------------------------------------------------
  PCREPERFORM(3)                                                  PCREPERFORM(3)
-Line 5882 
 REVISION
+Line 6017 
 REVISION
         Last updated: 06 March 2007
         Copyright (c) 1997-2007 University of Cambridge.
  ------------------------------------------------------------------------------
  PCREPOSIX(3)                                                      PCREPOSIX(3)
-Line 6001 
 COMPILING A PATTERN
+Line 6136 
 COMPILING A PATTERN
         is  public: re_nsub contains the number of capturing subpatterns in the
         regular expression. Various error codes are defined in the header file.
+        NOTE: If the yield of regcomp() is non-zero, you must  not  attempt  to
+        use the contents of the preg structure. If, for example, you pass it to
+        regexec(), the result is undefined and your program is likely to crash.
  MATCHING NEWLINE CHARACTERS
-Line 6118 
 AUTHOR
+Line 6257 
 AUTHOR
  REVISION
-        Last updated: 11 March 2009
+        Last updated: 15 August 2009
         Copyright (c) 1997-2009 University of Cambridge.
  ------------------------------------------------------------------------------
  PCRECPP(3)                                                          PCRECPP(3)
-Line 6462 
 REVISION
+Line 6601 
 REVISION
         Last updated: 17 March 2009
  ------------------------------------------------------------------------------
  PCRESAMPLE(3)                                                    PCRESAMPLE(3)
-Line 6474 
 NAME
+Line 6613 
 NAME
  PCRE SAMPLE PROGRAM
         A simple, complete demonstration program, to get you started with using
-        PCRE, is supplied in the file pcredemo.c in the PCRE distribution.
+        PCRE, is supplied in the file pcredemo.c in the  PCRE  distribution.  A
+        listing  of this program is given in the pcredemo documentation. If you
+        do not have a copy of the PCRE distribution, you can save this  listing
+        to re-create pcredemo.c.
         The program compiles the regular expression that is its first argument,
-        and  matches  it  against the subject string in its second argument. No
+        and matches it against the subject string in its  second  argument.  No
-        PCRE options are set, and default character tables are used. If  match-
+        PCRE  options are set, and default character tables are used. If match-
-        ing  succeeds,  the  program  outputs  the  portion of the subject that
+        ing succeeds, the program outputs  the  portion  of  the  subject  that
         matched, together with the contents of any captured substrings.
         If the -g option is given on the command line, the program then goes on
         to check for further matches of the same regular expression in the same
-        subject string. The logic is a little bit tricky because of the  possi-
+        subject  string. The logic is a little bit tricky because of the possi-
-        bility  of  matching an empty string. Comments in the code explain what
+        bility of matching an empty string. Comments in the code  explain  what
         is going on.
-        If PCRE is installed in the standard include  and  library  directories
+        If  PCRE  is  installed in the standard include and library directories
-        for  your  system, you should be able to compile the demonstration pro-
+        for your system, you should be able to compile the  demonstration  pro-
         gram using this command:
           gcc -o pcredemo pcredemo.c -lpcre
-        If PCRE is installed elsewhere, you may need to add additional  options
+        If  PCRE is installed elsewhere, you may need to add additional options
-        to  the  command line. For example, on a Unix-like system that has PCRE
+        to the command line. For example, on a Unix-like system that  has  PCRE
-        installed in /usr/local, you  can  compile  the  demonstration  program
+        installed  in  /usr/local,  you  can  compile the demonstration program
         using a command like this:
           gcc -o pcredemo -I/usr/local/include pcredemo.c \
               -L/usr/local/lib -lpcre
-        Once  you  have  compiled the demonstration program, you can run simple
+        Once you have compiled the demonstration program, you  can  run  simple
         tests like this:
           ./pcredemo 'cat|dog' 'the cat sat on the mat'
           ./pcredemo -g 'cat|dog' 'the dog sat on the cat'
-        Note that there is a  much  more  comprehensive  test  program,  called
+        Note  that  there  is  a  much  more comprehensive test program, called
-        pcretest,  which  supports  many  more  facilities  for testing regular
+        pcretest, which supports  many  more  facilities  for  testing  regular
         expressions and the PCRE library. The pcredemo program is provided as a
         simple coding example.
-        On some operating systems (e.g. Solaris), when PCRE is not installed in
+        When you try to run pcredemo when PCRE is not installed in the standard
-        the standard library directory, you may get an error like this when you
+        library  directory,  you  may  get an error like this on some operating
-        try to run pcredemo:
+        systems (e.g. Solaris):
-          ld.so.1:  a.out:  fatal:  libpcre.so.0:  open failed: No such file or
+          ld.so.1: a.out: fatal: libpcre.so.0: open failed:  No  such  file  or
         directory
-        This is caused by the way shared library support works  on  those  sys-
+        This  is  caused  by the way shared library support works on those sys-
         tems. You need to add
           -R/usr/local/lib
-Line 6537 
 AUTHOR
+Line 6679 
 AUTHOR
  REVISION
-        Last updated: 23 January 2008
+        Last updated: 01 September 2009
-        Copyright (c) 1997-2008 University of Cambridge.
+        Copyright (c) 1997-2009 University of Cambridge.
  ------------------------------------------------------------------------------
  PCRESTACK(3)                                                      PCRESTACK(3)
-Line 6676 
 REVISION
+Line 6818 
 REVISION
         Last updated: 09 July 2008
         Copyright (c) 1997-2008 University of Cambridge.
  ------------------------------------------------------------------------------

 Legend:



Removed from v.416
 


changed lines


 
Added in v.429
 Legend:



Removed from v.416
 


changed lines


 
Added in v.429
-Removed from v.416
+Added in v.429

	ViewVC Help
Powered by ViewVC 1.1.5