/[pcre]/code/tags/pcre-5.0/doc/pcre.txt

Diff of /code/tags/pcre-5.0/doc/pcre.txt

Parent Directory | Revision Log | View Patch Patch

-revision 41 by nigel,
Sat Feb 24 21:39:17 2007 UTC
+revision 51 by nigel,
Sat Feb 24 21:39:37 2007 UTC
 Line 28 
 SYNOPSIS
       int pcre_get_substring_list(const char *subject,
            int *ovector, int stringcount, const char ***listptr);
+      void pcre_free_substring(const char *stringptr);
+      void pcre_free_substring_list(const char **stringptr);
       const unsigned char *pcre_maketables(void);
+      int pcre_fullinfo(const pcre *code, const pcre_extra *extra,
+           int what, void *where);
       int pcre_info(const pcre *code, int *optptr, *firstcharptr);
       char *pcre_version(void);
-Line 45 
 DESCRIPTION
+Line 52 
 DESCRIPTION
       The PCRE library is a set of functions that implement  regu-
       lar  expression  pattern  matching using the same syntax and
       semantics as Perl  5,  with  just  a  few  differences  (see
       below).  The  current  implementation  corresponds  to  Perl
-.005.
+.005, with some additional features  from  later  versions.
+      This  includes  some  experimental,  incomplete  support for
+      UTF-8 encoded strings. Details of exactly what is  and  what
+      is not supported are given below.
       PCRE has its own native API,  which  is  described  in  this
       document.  There  is  also  a  set of wrapper functions that
-      correspond to the POSIX API.  These  are  described  in  the
+      correspond to the POSIX regular expression API.   These  are
-      pcreposix documentation.
+      described in the pcreposix documentation.
       The native API function prototypes are defined in the header
       file  pcre.h,  and  on  Unix  systems  the library itself is
       called libpcre.a, so can be accessed by adding -lpcre to the
-      command for linking an application which calls it.
+      command  for  linking  an  application  which  calls it. The
+      header file defines the macros PCRE_MAJOR and PCRE_MINOR  to
+      contain the major and minor release numbers for the library.
+      Applications can use these to include support for  different
+      releases.
       The functions pcre_compile(), pcre_study(), and  pcre_exec()
-      are  used  for  compiling  and matching regular expressions,
+      are used for compiling and matching regular expressions.
-      while   pcre_copy_substring(),   pcre_get_substring(),   and
-      pcre_get_substring_list()   are  convenience  functions  for
+      The functions  pcre_copy_substring(),  pcre_get_substring(),
+      and  pcre_get_substring_list() are convenience functions for
       extracting  captured  substrings  from  a  matched   subject
-      string.  The function pcre_maketables() is used (optionally)
+      string; pcre_free_substring() and pcre_free_substring_list()
-      to build a set of character tables in the current locale for
+      are also provided, to free the  memory  used  for  extracted
-      passing to pcre_compile().
+      strings.
-      The function pcre_info() is used  to  find  out  information
+      The function pcre_maketables() is used (optionally) to build
-      about  a compiled pattern, while the function pcre_version()
+      a  set of character tables in the current locale for passing
-      returns a pointer to a string containing the version of PCRE
+      to pcre_compile().
-      and its date of release.
+      The function pcre_fullinfo() is used to find out information
+      about a compiled pattern; pcre_info() is an obsolete version
+      which returns only some of the available information, but is
+      retained   for   backwards   compatibility.    The  function
+      pcre_version() returns a pointer to a string containing  the
+      version of PCRE and its date of release.
       The global variables  pcre_malloc  and  pcre_free  initially
       contain the entry points of the standard malloc() and free()
-Line 81 
 DESCRIPTION
+Line 104 
 DESCRIPTION
  MULTI-THREADING
-      The PCRE functions can be used in  multi-threading  applica-
+      The  PCRE  functions  can   be   used   in   multi-threading
-      tions, with the proviso that the memory management functions
-      pointed to by pcre_malloc and pcre_free are  shared  by  all
-      threads.
+ SunOS 5.8                 Last change:                          2
+      applications,  with  the  proviso that the memory management
+      functions pointed to by pcre_malloc and pcre_free are shared
+      by all threads.
       The compiled form of a regular  expression  is  not  altered
       during  matching, so the same compiled pattern can safely be
-Line 187 
 COMPILING A PATTERN
+Line 219 
 COMPILING A PATTERN
         PCRE_EXTRA
-      This option turns on additional functionality of  PCRE  that
+      This option was invented in  order  to  turn  on  additional
-      is  incompatible  with Perl. Any backslash in a pattern that
+      functionality of PCRE that is incompatible with Perl, but it
-      is followed by a letter that has no special  meaning  causes
+      is currently of very little use. When set, any backslash  in
-      an  error,  thus  reserving  these  combinations  for future
+      a  pattern  that is followed by a letter that has no special
-      expansion. By default, as in Perl, a backslash followed by a
+      meaning causes an error, thus reserving  these  combinations
-      letter  with  no  special  meaning  is treated as a literal.
+      for  future  expansion.  By default, as in Perl, a backslash
-      There are at present no other features  controlled  by  this
+      followed by a letter with no special meaning is treated as a
-      option.
+      literal.  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_MULTILINE
-Line 207 
 COMPILING A PATTERN
+Line 241 
 COMPILING A PATTERN
       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"   constructs   match   immediately  following  or
+      of  line"  constructs match immediately following or immedi-
-      immediately  before  any  newline  in  the  subject  string,
+      ately before any newline  in  the  subject  string,  respec-
-      respectively,  as well as at the very start and end. This is
+      tively,  as  well  as  at  the  very  start and end. This is
       equivalent to Perl's /m option. If there are no "\n" charac-
       ters  in  a subject string, or no occurrences of ^ or $ in a
       pattern, setting PCRE_MULTILINE has no effect.
-Line 221 
 COMPILING A PATTERN
+Line 255 
 COMPILING A PATTERN
       followed by "?". It is 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 strings of UTF-8 characters instead of just byte
+      strings. However, it is available  only  if  PCRE  has  been
+      built  to  include  UTF-8  support.  If not, the use of this
+      option provokes an error. Support for UTF-8 is new,  experi-
+      mental,  and incomplete.  Details of exactly what it entails
+      are given below.
  STUDYING A PATTERN
       When a 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 pattern as its first argument, and
       returns a  pointer  to  a  pcre_extra  block  (another  void
       typedef)  containing  additional  information about the pat-
-Line 284 
 LOCALE SUPPORT
+Line 329 
 LOCALE SUPPORT
  INFORMATION ABOUT A PATTERN
-      The pcre_info() function returns information  about  a  com-
+      The pcre_fullinfo() function  returns  information  about  a
-      piled pattern.  Its yield is the number of capturing subpat-
+      compiled pattern. It replaces the obsolete pcre_info() func-
-      terns, or one of the following negative numbers:
+      tion, which is nevertheless retained for backwards compabil-
+      ity (and is documented below).
+      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 the pattern was  not  studied.  The
+      third  argument  specifies  which  piece  of  information is
+      required, while the fourth argument is a pointer to a  vari-
+      able  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
+                              the argument where was NULL
         PCRE_ERROR_BADMAGIC   the "magic number" was not found
+        PCRE_ERROR_BADOPTION  the value of what was invalid
-      If the optptr argument is not NULL, a copy  of  the  options
+      The possible values for the third argument  are  defined  in
-      with which the pattern was compiled is placed in the integer
+      pcre.h, and are as follows:
-      it points to. These option bits are those specified  in  the
+        PCRE_INFO_OPTIONS
+      Return a copy of the options with which the pattern was com-
+      piled.  The fourth argument should point to au unsigned long
+      int variable. These option bits are those specified  in  the
       call  to  pcre_compile(),  modified  by any top-level option
       settings  within  the   pattern   itself,   and   with   the
-      PCRE_ANCHORED  bit  set  if  the form of the pattern implies
+      PCRE_ANCHORED  bit  forcibly  set if the form of the pattern
-      that it can match only at the start of a subject string.
+      implies that it can match only at the  start  of  a  subject
+      string.
-      If the pattern is not anchored and the firstcharptr argument
+        PCRE_INFO_SIZE
-      is  not  NULL, it is used to pass back information about the
-      first character of any matched string. If there is  a  fixed
+      Return the size of the compiled pattern, that is, the  value
-      first    character,    e.g.   from   a   pattern   such   as
+      that  was  passed as the argument to pcre_malloc() when PCRE
-      (cat|cow|coyote), then it is returned in the integer pointed
+      was getting memory in which to place the compiled data.  The
-      to by firstcharptr. Otherwise, if either
+      fourth argument should point to a size_t variable.
+        PCRE_INFO_CAPTURECOUNT
+      Return the number of capturing subpatterns in  the  pattern.
+      The fourth argument should point to an int variable.
+        PCRE_INFO_BACKREFMAX
+      Return the number of  the  highest  back  reference  in  the
+      pattern.  The  fourth  argument should point to an int vari-
+      able. Zero is returned if there are no back references.
+        PCRE_INFO_FIRSTCHAR
+      Return information about the first character of any  matched
+      string,  for  a  non-anchored  pattern.  If there is a fixed
+      first   character,   e.g.   from   a   pattern    such    as
+      (cat|cow|coyote),  it  is returned in the integer pointed to
+      by where. Otherwise, if either
       (a) the pattern was compiled with the PCRE_MULTILINE option,
       and every branch starts with "^", or
-Line 312 
 INFORMATION ABOUT A PATTERN
+Line 393 
 INFORMATION ABOUT A PATTERN
       (b) every  branch  of  the  pattern  starts  with  ".*"  and
       PCRE_DOTALL is not set (if it were set, the pattern would be
       anchored),
-      then -1 is returned, indicating  that  the  pattern  matches
-      only  at  the  start  of  a subject string or after any "\n"
+      -1 is returned, indicating that the pattern matches only  at
-      within the string. Otherwise -2 is returned.
+      the  start  of a subject string or after any "\n" 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  con-
+      struction of a 256-bit table indicating a fixed set of char-
+      acters for the first character in  any  matching  string,  a
+      pointer   to  the  table  is  returned.  Otherwise  NULL  is
+      returned. The fourth argument should point  to  an  unsigned
+      char * variable.
+        PCRE_INFO_LASTLITERAL
+      For a non-anchored pattern, return the value of  the  right-
+      most  literal  character  which  must  exist  in any matched
+      string, other than at its start. The fourth argument  should
+      point  to an int variable. If there is no such character, or
+      if the pattern is anchored, -1 is returned. For example, for
+      the pattern /a\d+z\d+/ the returned value is 'z'.
+      The pcre_info() function is now obsolete because its  inter-
+      face  is  too  restrictive  to return all the available data
+      about  a  compiled  pattern.   New   programs   should   use
+      pcre_fullinfo()  instead.  The  yield  of pcre_info() is the
+      number of capturing subpatterns, or  one  of  the  following
+      negative numbers:
+        PCRE_ERROR_NULL       the argument code was NULL
+        PCRE_ERROR_BADMAGIC   the "magic number" was not found
+      If the optptr argument is not NULL, a copy  of  the  options
+      with which the pattern was compiled is placed in the integer
+      it points to (see PCRE_INFO_OPTIONS above).
+      If the pattern is not anchored and the firstcharptr argument
+      is  not  NULL, it is used to pass back information about the
+      first    character    of    any    matched    string    (see
+      PCRE_INFO_FIRSTCHAR above).
-Line 516 
 MATCHING A PATTERN
+Line 636 
 MATCHING A PATTERN
  EXTRACTING CAPTURED SUBSTRINGS
       Captured substrings can be accessed directly  by  using  the
+ SunOS 5.8                 Last change:                         12
       offsets returned by pcre_exec() in ovector. For convenience,
       the functions  pcre_copy_substring(),  pcre_get_substring(),
       and  pcre_get_substring_list()  are  provided for extracting
-Line 533 
 EXTRACTING CAPTURED SUBSTRINGS
+Line 662 
 EXTRACTING CAPTURED SUBSTRINGS
       entire regular expression. This is  the  value  returned  by
       pcre_exec  if  it  is  greater  than  zero.  If  pcre_exec()
       returned zero, indicating that it ran out of space in  ovec-
-      tor, then the value passed as stringcount should be the size
+      tor,  the  value passed as stringcount should be the size of
-      of the vector divided by three.
+      the vector divided by three.
       The functions pcre_copy_substring() and pcre_get_substring()
       extract a single substring, whose number is given as string-
-Line 542 
 EXTRACTING CAPTURED SUBSTRINGS
+Line 671 
 EXTRACTING CAPTURED SUBSTRINGS
       the entire pattern, while higher values extract the captured
       substrings. For pcre_copy_substring(), the string is  placed
       in  buffer,  whose  length is given by buffersize, while for
-      pcre_get_substring() a new block of store  is  obtained  via
+      pcre_get_substring() a new block of memory is  obtained  via
       pcre_malloc,  and its address is returned via stringptr. The
       yield of the function is  the  length  of  the  string,  not
       including the terminating zero, or one of
-Line 576 
 EXTRACTING CAPTURED SUBSTRINGS
+Line 705 
 EXTRACTING CAPTURED SUBSTRINGS
       inspecting the appropriate offset in ovector, which is nega-
       tive for unset substrings.
+      The  two  convenience  functions  pcre_free_substring()  and
+      pcre_free_substring_list()  can  be  used to free the memory
+      returned by  a  previous  call  of  pcre_get_substring()  or
+      pcre_get_substring_list(),  respectively.  They  do  nothing
+      more than call the function pointed to by  pcre_free,  which
+      of  course  could  be called directly from a C program. How-
+      ever, PCRE is used in some situations where it is linked via
+      a  special  interface  to another programming language which
+      cannot use pcre_free directly; it is for  these  cases  that
+      the functions are provided.
-Line 640 
 DIFFERENCES FROM PERL
+Line 779 
 DIFFERENCES FROM PERL
 . The Perl \G assertion is  not  supported  as  it  is  not
       relevant to single pattern matches.
-. Fairly obviously, PCRE does  not  support  the  (?{code})
+. Fairly obviously, PCRE does not support the (?{code}) and
-      construction.
+      (?p{code})  constructions. However, there is some experimen-
+      tal support for recursive patterns using the  non-Perl  item
+      (?R).
 . There are at the time of writing some  oddities  in  Perl
 .005_02  concerned  with  the  settings of captured strings
-Line 649 
 DIFFERENCES FROM PERL
+Line 790 
 DIFFERENCES FROM PERL
       "aba"  against the pattern /^(a(b)?)+$/ sets $2 to the value
       "b", but matching "aabbaa" against /^(aa(bb)?)+$/ leaves  $2
       unset.    However,    if   the   pattern   is   changed   to
-      /^(aa(b(b))?)+$/ then $2 (and $3) get set.
+      /^(aa(b(b))?)+$/ then $2 (and $3) are set.
       In Perl 5.004 $2 is set in both cases, and that is also true
       of PCRE. If in the future Perl changes to a consistent state
-Line 675 
 DIFFERENCES FROM PERL
+Line 816 
 DIFFERENCES FROM PERL
       (c) If PCRE_EXTRA is set, a backslash followed by  a  letter
       with no special meaning is faulted.
-      (d)  If  PCRE_UNGREEDY  is  set,  the  greediness   of   the
+      (d) If PCRE_UNGREEDY is set, the greediness of  the  repeti-
-      repetition quantifiers is inverted, that is, by default they
+      tion  quantifiers  is inverted, that is, by default they are
-      are not greedy, but if followed by a question mark they are.
+      not greedy, but if followed by a question mark they are.
       (e) PCRE_ANCHORED can be used to force a pattern to be tried
       only at the start of the subject.
-Line 685 
 DIFFERENCES FROM PERL
+Line 826 
 DIFFERENCES FROM PERL
       (f) The PCRE_NOTBOL, PCRE_NOTEOL, and PCRE_NOTEMPTY  options
       for pcre_exec() have no Perl equivalents.
+      (g) The (?R) construct allows for recursive pattern matching
+      (Perl  5.6 can do this using the (?p{code}) construct, which
+      PCRE cannot of course support.)
  REGULAR EXPRESSION DETAILS
-Line 693 
 REGULAR EXPRESSION DETAILS
+Line 838 
 REGULAR EXPRESSION DETAILS
       also described in the Perl documentation and in a number  of
       other  books,  some  of which have copious examples. Jeffrey
       Friedl's  "Mastering  Regular  Expressions",  published   by
-      O'Reilly  (ISBN 1-56592-257-3), covers them in great detail.
+      O'Reilly (ISBN 1-56592-257), covers them in great detail.
       The description here is intended as reference documentation.
+      The basic operation of PCRE is on strings of bytes. However,
+      there is the beginnings of some support for UTF-8  character
+      strings.  To  use  this  support  you must configure PCRE to
+      include it, and then call pcre_compile() with the  PCRE_UTF8
+      option.  How  this affects the pattern matching is described
+      in the final section of this document.
       A regular expression is a pattern that is matched against  a
       subject string from left to right. Most characters stand for
-Line 780 
 BACKSLASH
+Line 932 
 BACKSLASH
         \f     formfeed (hex 0C)
         \n     newline (hex 0A)
         \r     carriage return (hex 0D)
+        \t     tab (hex 09)
-             tab (hex 09)
         \xhh   character with hex code hh
         \ddd   character with octal code ddd, or backreference
-Line 833 
 BACKSLASH
+Line 984 
 BACKSLASH
       Note that octal values of 100 or greater must not be  intro-
       duced  by  a  leading zero, because no more than three octal
       digits are ever read.
       All the sequences that define a single  byte  value  can  be
       used both inside and outside character classes. In addition,
       inside a character class, the sequence "\b"  is  interpreted
-Line 885 
 BACKSLASH
+Line 1037 
 BACKSLASH
       These assertions may not appear in  character  classes  (but
       note that "\b" has a different meaning, namely the backspace
       character, inside a character class).
       A word boundary is a position in the  subject  string  where
       the current character and the previous character do not both
       match \w or \W (i.e. one matches \w and  the  other  matches
-Line 908 
 CIRCUMFLEX AND DOLLAR
+Line 1061 
 CIRCUMFLEX AND DOLLAR
       Outside a character class, in the default matching mode, the
       circumflex  character  is an assertion which is true only if
       the current matching point is at the start  of  the  subject
       string.  If  the startoffset argument of pcre_exec() is non-
       zero, circumflex can never match. Inside a character  class,
       circumflex has an entirely different meaning (see below).
-Line 960 
 FULL STOP (PERIOD, DOT)
+Line 1114 
 FULL STOP (PERIOD, DOT)
       Outside a character class, a dot in the pattern matches  any
       one character in the subject, including a non-printing char-
       acter, but not (by default)  newline.   If  the  PCRE_DOTALL
-      option  is  set,  then dots match newlines as well. The han-
-      dling of dot is entirely independent of the handling of cir-
+      option  is set, dots match newlines as well. The handling of
-      cumflex  and  dollar,  the only relationship being that they
+      dot is entirely independent of the  handling  of  circumflex
-      both involve newline characters.  Dot has no special meaning
+      and  dollar,  the  only  relationship  being  that they both
-      in a character class.
+      involve newline characters. Dot has no special meaning in  a
+      character class.
-Line 1046 
 SQUARE BRACKETS
+Line 1201 
 SQUARE BRACKETS
+ POSIX CHARACTER CLASSES
+      Perl 5.6 (not yet released at the time of writing) is  going
+      to  support  the POSIX notation for character classes, which
+      uses names enclosed by  [:  and  :]   within  the  enclosing
+      square brackets. PCRE supports this notation. For example,
+        [01[:alpha:]%]
+      matches "0", "1", any alphabetic character, or "%". The sup-
+      ported class names are
+        alnum    letters and digits
+        alpha    letters
+        ascii    character codes 0 - 127
+        cntrl    control characters
+        digit    decimal digits (same as \d)
+        graph    printing characters, excluding space
+        lower    lower case letters
+        print    printing characters, including space
+        punct    printing characters, excluding letters and digits
+        space    white space (same as \s)
+        upper    upper case letters
+        word     "word" characters (same as \w)
+        xdigit   hexadecimal digits
+      The names "ascii" and "word" are  Perl  extensions.  Another
+      Perl  extension is negation, which is indicated by a ^ char-
+      acter after the colon. For example,
+        [12[:^digit:]]
+      matches "1", "2", or any non-digit.  PCRE  (and  Perl)  also
+      recogize  the POSIX syntax [.ch.] and [=ch=] where "ch" is a
+      "collating element", but these are  not  supported,  and  an
+      error is given if they are encountered.
  VERTICAL BAR
       Vertical bar characters are  used  to  separate  alternative
       patterns. For example, the pattern
-Line 1197 
 REPETITION
+Line 1390 
 REPETITION
       Repetition is specified by quantifiers, which can follow any
       of the following items:
         a single character, possibly escaped
         the . metacharacter
         a character class
-Line 1270 
 REPETITION
+Line 1462 
 REPETITION
         /* first command */  not comment  /* second comment */
-      fails, because it matches  the  entire  string  due  to  the
+      fails, because it matches the entire  string  owing  to  the
       greediness of the .*  item.
-      However, if a quantifier is followed  by  a  question  mark,
+      However, if a quantifier is followed by a question mark,  it
-      then it ceases to be greedy, and instead matches the minimum
+      ceases  to be greedy, and instead matches the minimum number
-      number of times possible, so the pattern
+      of times possible, so the pattern
         /\*.*?\*/
-Line 1292 
 REPETITION
+Line 1484 
 REPETITION
       that is the only way the rest of the pattern matches.
       If the PCRE_UNGREEDY option is set (an option which  is  not
-      available  in  Perl)  then the quantifiers are not greedy by
+      available  in  Perl),  the  quantifiers  are  not  greedy by
       default, but individual ones can be made greedy by following
       them  with  a  question mark. In other words, it inverts the
       default behaviour.
-Line 1304 
 REPETITION
+Line 1496 
 REPETITION
       If a pattern starts with .* or  .{0,}  and  the  PCRE_DOTALL
       option (equivalent to Perl's /s) is set, thus allowing the .
-      to match newlines, then the pattern is implicitly  anchored,
+      to match  newlines,  the  pattern  is  implicitly  anchored,
       because whatever follows will be tried against every charac-
       ter position in the subject string, so there is no point  in
       retrying  the overall match at any position after the first.
-Line 1357 
 BACK REFERENCES
+Line 1549 
 BACK REFERENCES
       matches "sense and sensibility" and "response and  responsi-
       bility",  but  not  "sense  and  responsibility". If caseful
-      matching is in force at the time of the back reference, then
+      matching is in force at the time of the back reference,  the
-      the case of letters is relevant. For example,
+      case of letters is relevant. For example,
         ((?i)rah)\s+\1
-Line 1368 
 BACK REFERENCES
+Line 1560 
 BACK REFERENCES
       There may be more than one back reference to the  same  sub-
       pattern.  If  a  subpattern  has not actually been used in a
-      particular match, then any  back  references  to  it  always
+      particular match, any back references to it always fail. For
-      fail. For example, the pattern
+      example, the pattern
         (a|(bc))\2
-Line 1377 
 BACK REFERENCES
+Line 1569 
 BACK REFERENCES
       Because  there  may  be up to 99 back references, all digits
       following the backslash are taken as  part  of  a  potential
       back reference number. If the pattern continues with a digit
-      character, then some delimiter must be used to terminate the
+      character, some delimiter must be used to terminate the back
-      back reference. If the PCRE_EXTENDED option is set, this can
+      reference.   If the PCRE_EXTENDED option is set, this can be
-      be whitespace.  Otherwise an empty comment can be used.
+      whitespace. Otherwise an empty comment can be used.
       A back reference that occurs inside the parentheses to which
       it  refers  fails when the subpattern is first used, so, for
-Line 1389 
 BACK REFERENCES
+Line 1581 
 BACK REFERENCES
         (a|b\1)+
-      matches any number of "a"s and also "aba", "ababaa" etc.  At
+      matches any number of "a"s and also "aba", "ababbaa" etc. At
       each iteration of the subpattern, the back reference matches
-      the character string corresponding to  the  previous  itera-
+      the  character  string   corresponding   to   the   previous
-      tion.  In  order  for this to work, the pattern must be such
+      iteration.  In  order  for this to work, the pattern must be
-      that the first iteration does not need  to  match  the  back
+      such that the first iteration does not  need  to  match  the
-      reference.  This  can  be  done using alternation, as in the
+      back  reference.  This  can be done using alternation, as in
-      example above, or by a quantifier with a minimum of zero.
+      the example above, or by a  quantifier  with  a  minimum  of
+      zero.
-Line 1407 
 ASSERTIONS
+Line 1600 
 ASSERTIONS
       cated assertions are coded as  subpatterns.  There  are  two
       kinds:  those that look ahead of the current position in the
       subject string, and those that look behind it.
       An assertion subpattern is matched in the normal way, except
       that  it  does not cause the current matching position to be
       changed. Lookahead assertions start with  (?=  for  positive
-Line 1478 
 ASSERTIONS
+Line 1672 
 ASSERTIONS
       matches "foo" preceded by three digits that are  not  "999".
       Notice  that each of the assertions is applied independently
       at the same point in the subject string. First  there  is  a
-      check  that  the  previous  three characters are all digits,
+      check that the previous three characters are all digits, and
       then there is a check that the same three characters are not
       "999".   This  pattern  does not match "foo" preceded by six
       characters, the first of which are digits and the last three
-Line 1547 
 ONCE-ONLY SUBPATTERNS
+Line 1741 
 ONCE-ONLY SUBPATTERNS
       This kind of parenthesis "locks up" the  part of the pattern
       it  contains once it has matched, and a failure further into
-      the pattern is prevented from backtracking  into  it.  Back-
+      the  pattern  is  prevented  from  backtracking   into   it.
-      tracking  past  it to previous items, however, works as nor-
+      Backtracking  past  it  to previous items, however, works as
-      mal.
+      normal.
       An alternative description is that a subpattern of this type
       matches  the  string  of  characters that an identical stan-
-Line 1572 
 ONCE-ONLY SUBPATTERNS
+Line 1766 
 ONCE-ONLY SUBPATTERNS
         abcd$
-      when applied to a long  string  which  does  not  match  it.
+      when applied to a long string which does not match.  Because
-      Because matching proceeds from left to right, PCRE will look
+      matching  proceeds  from  left  to right, PCRE will look for
-      for each "a" in the subject and then  see  if  what  follows
+      each "a" in the subject and then see if what follows matches
-      matches the rest of the pattern. If the pattern is specified
+      the rest of the pattern. If the pattern is specified as
-      as
         ^.*abcd$
-      then the initial .* matches the entire string at first,  but
+      the initial .* matches the entire string at first, but  when
-      when  this  fails,  it  backtracks to match all but the last
+      this  fails  (because  there  is no following "a"), it back-
-      character, then all but the last two characters, and so  on.
+      tracks to match all but the last character, then all but the
-      Once again the search for "a" covers the entire string, from
+      last  two  characters,  and so on. Once again the search for
-      right to left, so we are no better off. However, if the pat-
+      "a" covers the entire string, from right to left, so we  are
-      tern is written as
+      no better off. However, if the pattern is written as
         ^(?>.*)(?<=abcd)
-      then there can be no backtracking for the .*  item;  it  can
+      there can be no backtracking for the .* item; it  can  match
-      match  only  the  entire  string.  The subsequent lookbehind
+      only  the entire string. The subsequent lookbehind assertion
-      assertion does a single test on the last four characters. If
+      does a single test on the last four characters. If it fails,
-      it  fails,  the  match  fails immediately. For long strings,
+      the match fails immediately. For long strings, this approach
-      this approach makes a significant difference to the process-
+      makes a significant difference to the processing time.
-      ing time.
+      When a pattern contains an unlimited repeat inside a subpat-
+      tern  that  can  itself  be  repeated an unlimited number of
+      times, the use of a once-only subpattern is the only way  to
+      avoid  some  failing matches taking a very long time indeed.
+      The pattern
+        (\D+|<\d+>)*[!?]
+      matches an unlimited number of substrings that  either  con-
+      sist  of  non-digits,  or digits enclosed in <>, followed by
+      either ! or ?. When it matches, it runs quickly. However, if
+      it is applied to
+        aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+      it takes a long  time  before  reporting  failure.  This  is
+      because the string can be divided between the two repeats in
+      a large number of ways, and all have to be tried. (The exam-
+      ple  used  [!?]  rather  than a single character at the end,
+      because both PCRE and Perl have an optimization that  allows
+      for  fast  failure  when  a  single  character is used. They
+      remember the last single character that is  required  for  a
+      match,  and  fail early if it is not present in the string.)
+      If the pattern is changed to
+        ((?>\D+)|<\d+>)*[!?]
+      sequences of non-digits cannot be broken, and  failure  hap-
+      pens quickly.
-Line 1614 
 CONDITIONAL SUBPATTERNS
+Line 1836 
 CONDITIONAL SUBPATTERNS
       error occurs.
       There are two kinds of condition. If the  text  between  the
-      parentheses  consists  of  a  sequence  of  digits, then the
+      parentheses  consists of a sequence of digits, the condition
-      condition is satisfied if the capturing subpattern  of  that
+      is satisfied if the capturing subpattern of that number  has
-      number  has  previously matched. Consider the following pat-
+      previously  matched.  The  number must be greater than zero.
-      tern, which contains non-significant white space to make  it
+      Consider  the  following  pattern,   which   contains   non-
-      more  readable  (assume  the  PCRE_EXTENDED  option)  and to
+      significant white space to make it more readable (assume the
-      divide it into three parts for ease of discussion:
+      PCRE_EXTENDED option) and to divide it into three parts  for
+      ease of discussion:
         ( \( )?    [^()]+    (?(1) \) )
-Line 1668 
 COMMENTS
+Line 1891 
 COMMENTS
+ RECURSIVE PATTERNS
+      Consider the problem of matching a  string  in  parentheses,
+      allowing  for  unlimited nested parentheses. Without the use
+      of recursion, the best that can be done is to use a  pattern
+      that  matches  up  to some fixed depth of nesting. It is not
+      possible to handle an arbitrary nesting depth. Perl 5.6  has
+      provided   an  experimental  facility  that  allows  regular
+      expressions to recurse (amongst other things). It does  this
+      by  interpolating  Perl  code in the expression at run time,
+      and the code can refer to the expression itself. A Perl pat-
+      tern  to  solve  the parentheses problem can be created like
+      this:
+        $re = qr{\( (?: (?>[^()]+) | (?p{$re}) )* \)}x;
+      The (?p{...}) item interpolates Perl code at run  time,  and
+      in  this  case refers recursively to the pattern in which it
+      appears. Obviously, PCRE cannot support the interpolation of
+      Perl  code.  Instead,  the special item (?R) is provided for
+      the specific case of recursion. This PCRE pattern solves the
+      parentheses  problem (assume the PCRE_EXTENDED option is set
+      so that white space is ignored):
+        \( ( (?>[^()]+) | (?R) )* \)
+      First it matches an opening parenthesis. Then it matches any
+      number  of substrings which can either be a sequence of non-
+      parentheses, or a recursive  match  of  the  pattern  itself
+      (i.e. a correctly parenthesized substring). Finally there is
+      a closing parenthesis.
+      This particular example pattern  contains  nested  unlimited
+      repeats, and so the use of a once-only subpattern for match-
+      ing strings of non-parentheses is  important  when  applying
+      the  pattern to strings that do not match. For example, when
+      it is applied to
+        (aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa()
+      it yields "no match" quickly. However, if a  once-only  sub-
+      pattern  is  not  used,  the match runs for a very long time
+      indeed because there are so many different ways the + and  *
+      repeats  can carve up the subject, and all have to be tested
+      before failure can be reported.
+      The values set for any capturing subpatterns are those  from
+      the outermost level of the recursion at which the subpattern
+      value is set. If the pattern above is matched against
+        (ab(cd)ef)
+      the value for the capturing parentheses is  "ef",  which  is
+      the  last  value  taken  on  at the top level. If additional
+      parentheses are added, giving
+        \( ( ( (?>[^()]+) | (?R) )* ) \)
+           ^                        ^
+           ^                        ^ the string they  capture  is
+      "ab(cd)ef",  the  contents  of the top level parentheses. If
+      there are more than 15 capturing parentheses in  a  pattern,
+      PCRE  has  to  obtain  extra  memory  to store data during a
+      recursion, which it does by using  pcre_malloc,  freeing  it
+      via  pcre_free  afterwards. If no memory can be obtained, it
+      saves data for the first 15 capturing parentheses  only,  as
+      there is no way to give an out-of-memory error from within a
+      recursion.
  PERFORMANCE
       Certain items that may appear in patterns are more efficient
       than  others.  It is more efficient to use a character class
-Line 1735 
 PERFORMANCE
+Line 2027 
 PERFORMANCE
+ UTF-8 SUPPORT
+      Starting at release 3.3, PCRE has some support for character
+      strings encoded in the UTF-8 format. This is incomplete, and
+      is regarded as experimental. In order to use  it,  you  must
+      configure PCRE to include UTF-8 support in the code, and, in
+      addition, you must call pcre_compile()  with  the  PCRE_UTF8
+      option flag. When you do this, both the pattern and any sub-
+      ject strings that are matched  against  it  are  treated  as
+      UTF-8  strings instead of just strings of bytes, but only in
+      the cases that are mentioned below.
+      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 addi-
+      tional run time overhead is limited to testing the PCRE_UTF8
+      flag in several places, so should not be very large.
+      PCRE assumes that the strings  it  is  given  contain  valid
+      UTF-8  codes. It does not diagnose invalid UTF-8 strings. If
+      you pass invalid UTF-8 strings  to  PCRE,  the  results  are
+      undefined.
+      Running with PCRE_UTF8 set causes these changes in  the  way
+      PCRE works:
+. In a pattern, the escape sequence \x{...}, where the con-
+      tents  of  the  braces is a string of hexadecimal digits, is
+      interpreted as a UTF-8 character whose code  number  is  the
+      given   hexadecimal  number,  for  example:  \x{1234}.  This
+      inserts from one to six  literal  bytes  into  the  pattern,
+      using the UTF-8 encoding. If a non-hexadecimal digit appears
+      between the braces, the item is not recognized.
+. The original hexadecimal escape sequence, \xhh, generates
+      a two-byte UTF-8 character if its value is greater than 127.
+. Repeat quantifiers are NOT correctly handled if they fol-
+      low  a  multibyte character. For example, \x{100}* and \xc3+
+      do not work. If you want to repeat such characters, you must
+      enclose  them  in  non-capturing  parentheses,  for  example
+      (?:\x{100}), at present.
+. The dot metacharacter matches one UTF-8 character instead
+      of a single byte.
+. Unlike literal UTF-8 characters,  the  dot  metacharacter
+      followed  by  a  repeat quantifier does operate correctly on
+      UTF-8 characters instead of single bytes.
+. Although the \x{...} escape is permitted in  a  character
+      class,  characters  whose values are greater than 255 cannot
+      be included in a class.
+. A class is matched against a UTF-8 character  instead  of
+      just  a  single byte, but it can match only characters whose
+      values are less than 256.  Characters  with  greater  values
+      always fail to match a class.
+. Repeated classes work correctly on multiple characters.
+. Classes containing just a single character whose value is
+      greater than 127 (but less than 256), for example, [\x80] or
+      [^\x{93}], do not work because these are optimized into sin-
+      gle  byte  matches.  In the first case, of course, the class
+      brackets are just redundant.
+. Lookbehind assertions move backwards in the subject by  a
+      fixed  number  of  characters  instead  of a fixed number of
+      bytes. Simple cases have been tested to work correctly,  but
+      there may be hidden gotchas herein.
+. The character types  such  as  \d  and  \w  do  not  work
+      correctly  with  UTF-8  characters.  They continue to test a
+      single byte.
+. Anything not explicitly mentioned here continues to work
+      in bytes rather than in characters.
+      The following UTF-8 features of  Perl  5.6  are  not  imple-
+      mented:
+. The escape sequence \C to match a single byte.
+. The use of Unicode tables and properties and escapes  \p,
+      \P, and \X.
  AUTHOR
       Philip Hazel <ph10@cam.ac.uk>
       University Computing Service,
-Line 1742 
 AUTHOR
+Line 2120 
 AUTHOR
       Cambridge CB2 3QG, England.
       Phone: +44 1223 334714
-      Last updated: 29 July 1999
+      Last updated: 28 August 2000,
-      Copyright (c) 1997-1999 University of Cambridge.
+        the 250th anniversary of the death of J.S. Bach.
+      Copyright (c) 1997-2000 University of Cambridge.

 Legend:



Removed from v.41
 


changed lines


 
Added in v.51
 Legend:



Removed from v.41
 


changed lines


 
Added in v.51
-Removed from v.41
+Added in v.51

	ViewVC Help
Powered by ViewVC 1.1.5