/[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 53 by nigel,
Sat Feb 24 21:39:42 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. A
-      while   pcre_copy_substring(),   pcre_get_substring(),   and
+      sample program that demonstrates the simplest way  of  using
-      pcre_get_substring_list()   are  convenience  functions  for
+      them  is  given  in the file pcredemo.c. The last section of
+      this man page describes how to run it.
+      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 98 
 COMPILING A PATTERN
+Line 124 
 COMPILING A PATTERN
       by a binary zero, and is passed in the argument  pattern.  A
       pointer  to  a  single  block of memory that is obtained via
       pcre_malloc is returned. This contains the compiled code and
-      related data. The pcre type is defined for this for conveni-
+      related  data.  The  pcre  type  is defined for the returned
-      ence, but in fact pcre is just a typedef for void, since the
+      block; this is a typedef for a structure whose contents  are
-      contents  of  the block are not externally defined. It is up
+      not  externally  defined. It is up to the caller to free the
-      to the caller to free  the  memory  when  it  is  no  longer
+      memory when it is no longer required.
-      required.
+      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  con-
+      tains  a  copy of the tableptr argument, which is an address
+      (see below).
       The size of a compiled pattern is  roughly  proportional  to
       the length of the pattern string, except that each character
-Line 137 
 COMPILING A PATTERN
+Line 168 
 COMPILING A PATTERN
       must  be  the result of a call to pcre_maketables(). See the
       section on locale support below.
+      This code fragment shows a typical straightforward  call  to
+      pcre_compile():
+        pcre *re;
+        const char *error;
+        int erroffset;
+        re = pcre_compile(
+          "^A.*Z",          /* the pattern */
+,                /* default options */
+          &error,           /* for error message */
+          &erroffset,       /* for error offset */
+          NULL);            /* use default character tables */
       The following option bits are defined in the header file:
         PCRE_ANCHORED
-Line 187 
 COMPILING A PATTERN
+Line 231 
 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 253 
 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 267 
 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
-Line 228 
 STUDYING A PATTERN
+Line 284 
 STUDYING A PATTERN
       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
+      returns a pointer to a pcre_extra block (another typedef for
-      typedef)  containing  additional  information about the pat-
+      a  structure  with  hidden  contents)  containing additional
-      tern; this can be passed to pcre_exec().  If  no  additional
+      information  about  the  pattern;  this  can  be  passed  to
-      information is available, NULL is returned.
+      pcre_exec(). If no additional information is available, NULL
+      is returned.
       The second argument contains option  bits.  At  present,  no
       options  are  defined  for  pcre_study(),  and this argument
-Line 242 
 STUDYING A PATTERN
+Line 299 
 STUDYING A PATTERN
       the variable it points to  is  set  to  NULL.  Otherwise  it
       points to a textual error message.
+      This is a typical call to pcre_study():
+        pcre_extra *pe;
+        pe = pcre_study(
+          re,             /* result of pcre_compile() */
+,              /* no options exist */
+          &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  possible  starting  characters  is
-Line 284 
 LOCALE SUPPORT
+Line 349 
 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
+      Here is a typical call of  pcre_fullinfo(),  to  obtain  the
-      with which the pattern was compiled is placed in the integer
+      length of the compiled pattern:
-      it points to. These option bits are those specified  in  the
+        int rc;
+        unsigned long int length;
+        rc = pcre_fullinfo(
+          re,               /* result of pcre_compile() */
+          pe,               /* result of pcre_study(), or NULL */
+          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 are as follows:
+        PCRE_INFO_OPTIONS
+      Return a copy of the options with which the pattern was com-
+      piled.  The fourth argument should point to an unsigned long
+      int variable. These option bits are those specified  in  the
       call  to  pcre_compile(),  modified  by any top-level option
       settings  within  the   pattern   itself,   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  pat-
+      tern.  The  fourth argument should point to an int variable.
+      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 424 
 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).
  MATCHING A PATTERN
       The function pcre_exec() is called to match a subject string
+ SunOS 5.8                 Last change:                          9
       against  a pre-compiled pattern, which is passed in the code
       argument. If the pattern has been studied, the result of the
       study should be passed in the extra argument. Otherwise this
       must be NULL.
+      Here is an example of a simple call to pcre_exec():
+        int rc;
+        int ovector[30];
+        rc = pcre_exec(
+          re,             /* result of pcre_compile() */
+          NULL,           /* we didn't study the pattern */
+          "some string",  /* the subject string */
+,             /* the length of the subject string */
+,              /* start at offset 0 in the subject */
+,              /* default options */
+          ovector,        /* vector for substring information */
+);            /* number of elements in the vector */
       The PCRE_ANCHORED option can be passed in the options  argu-
       ment,  whose unused bits must be zero. However, if a pattern
       was  compiled  with  PCRE_ANCHORED,  or  turned  out  to  be
-Line 375 
 MATCHING A PATTERN
+Line 549 
 MATCHING A PATTERN
       The subject string is passed as  a  pointer  in  subject,  a
       length  in  length,  and  a  starting offset in startoffset.
-      Unlike the pattern string, it may contain binary zero  char-
+      Unlike the pattern string, the subject  may  contain  binary
-      acters.  When  the starting offset is zero, the search for a
+      zero  characters.  When  the  starting  offset  is zero, the
-      match starts at the beginning of the subject, and this is by
+      search for a match starts at the beginning of  the  subject,
-      far the most common case.
+      and this is by far the most common case.
       A non-zero starting offset  is  useful  when  searching  for
       another  match  in  the  same subject by calling pcre_exec()
-Line 514 
 MATCHING A PATTERN
+Line 688 
 MATCHING A PATTERN
  EXTRACTING CAPTURED SUBSTRINGS
       Captured substrings can be accessed directly  by  using  the
       offsets returned by pcre_exec() in ovector. For convenience,
-Line 533 
 EXTRACTING CAPTURED SUBSTRINGS
+Line 708 
 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 717 
 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 751 
 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 583 
 LIMITATIONS
+Line 768 
 LIMITATIONS
       There are some size limitations in PCRE but it is hoped that
       they will never in practice be relevant.  The maximum length
       of a compiled pattern is 65539 (sic) bytes.  All  values  in
-      repeating  quantifiers must be less than 65536.  The maximum
+      repeating  quantifiers  must be less than 65536.  There max-
-      number of capturing subpatterns is 99.  The  maximum  number
+      imum number of capturing subpatterns is 65535.  There is  no
-      of  all  parenthesized subpatterns, including capturing sub-
+      limit  to  the  number of non-capturing subpatterns, but the
-      patterns, assertions, and other types of subpattern, is 200.
+      maximum depth of nesting of all kinds of parenthesized  sub-
+      pattern,  including  capturing  subpatterns, assertions, and
+      other types of subpattern, is 200.
       The maximum length of a subject string is the largest  posi-
       tive number that an integer variable can hold. However, PCRE
-Line 640 
 DIFFERENCES FROM PERL
+Line 827 
 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 838 
 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 864 
 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 874 
 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 886 
 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 749 
 BACKSLASH
+Line 949 
 BACKSLASH
       The backslash character has several uses. Firstly, if it  is
       followed  by  a  non-alphameric character, it takes away any
       special  meaning  that  character  may  have.  This  use  of
       backslash  as  an  escape  character applies both inside and
       outside character classes.
-Line 780 
 BACKSLASH
+Line 981 
 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 1033 
 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 1086 
 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 951 
 CIRCUMFLEX AND DOLLAR
+Line 1153 
 CIRCUMFLEX AND DOLLAR
       Note that the sequences \A, \Z, and \z can be used to  match
       the  start  and end of the subject in both modes, and if all
-      branches of a pattern start with \A is it  always  anchored,
+      branches of a pattern start with \A it is  always  anchored,
       whether PCRE_MULTILINE is set or not.
-Line 960 
 FULL STOP (PERIOD, DOT)
+Line 1162 
 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-
+      option  is set, dots match newlines as well. The handling of
-      dling of dot is entirely independent of the handling of cir-
+      dot is entirely independent of the  handling  of  circumflex
-      cumflex  and  dollar,  the only relationship being that they
+      and  dollar,  the  only  relationship  being  that they both
-      both involve newline characters.  Dot has no special meaning
+      involve newline characters. Dot has no special meaning in  a
-      in a character class.
+      character class.
-Line 1046 
 SQUARE BRACKETS
+Line 1248 
 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
+      recognize the POSIX syntax [.ch.] and [=ch=] where "ch" is a
+      "collating element", but these are  not  supported,  and  an
+      error is given if they are encountered.
  VERTICAL BAR
       Vertical bar characters are  used  to  separate  alternative
       patterns. For example, the pattern
-Line 1159 
 SUBPATTERNS
+Line 1399 
 SUBPATTERNS
         the ((red|white) (king|queen))
       the captured substrings are "red king", "red",  and  "king",
-      and are numbered 1, 2, and 3.
+      and are numbered 1, 2, and 3, respectively.
       The fact that plain parentheses fulfil two functions is  not
       always  helpful.  There are often times when a grouping sub-
-Line 1197 
 REPETITION
+Line 1437 
 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 1231 
 REPETITION
+Line 1470 
 REPETITION
       one that does not match the syntax of a quantifier, is taken
       as  a literal character. For example, {,6} is not a quantif-
       ier, but a literal string of four characters.
       The quantifier {0} is permitted, causing the  expression  to
       behave  as  if the previous item and the quantifier were not
       present.
-Line 1270 
 REPETITION
+Line 1508 
 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 1530 
 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 1542 
 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 1336 
 REPETITION
+Line 1574 
 REPETITION
  BACK REFERENCES
       Outside a character class, a backslash followed by  a  digit
       greater  than  0  (and  possibly  further  digits) is a back
+ SunOS 5.8                 Last change:                         30
       reference to a capturing subpattern  earlier  (i.e.  to  its
       left)  in  the  pattern,  provided there have been that many
       previous capturing left parentheses.
-Line 1357 
 BACK REFERENCES
+Line 1603 
 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 1614 
 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 1623 
 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 1635 
 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-
       tion.  In  order  for this to work, the pattern must be such
-Line 1407 
 ASSERTIONS
+Line 1653 
 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 1725 
 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 1572 
 ONCE-ONLY SUBPATTERNS
+Line 1819 
 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 1889 
 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 1944 
 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 2080 
 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
+      contents 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.
+ SAMPLE PROGRAM
+      The code below is a simple, complete demonstration  program,
+      to  get  you started with using PCRE. This code is also sup-
+      plied in the file pcredemo.c in the PCRE distribution.
+      The program compiles the  regular  expression  that  is  its
+      first argument, and matches it against the subject string in
+      its second argument. No options are set, and default charac-
+      ter  tables are used. If matching succeeds, the program out-
+      puts the portion of the subject that matched, together  with
+      the contents of any captured substrings.
+      On a Unix system that has PCRE installed in /usr/local,  you
+      can  compile  the demonstration program using a command like
+      this:
+        gcc   -o    pcredemo    pcredemo.c    -I/usr/local/include
+      -L/usr/local/lib -lpcre
+      Then you can run simple tests like this:
+        ./pcredemo 'cat|dog' 'the cat sat on the mat'
+      Note that there is a much more comprehensive  test  program,
+      called  pcretest,  which  supports  many more facilities for
+      testing regular expressions. The pcredemo  program  is  pro-
+      vided as a simple coding example.
+      On some operating systems (e.g.  Solaris)  you  may  get  an
+      error like this when you try to run pcredemo:
+        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 systems. You need to add
+        -R/usr/local/lib
+      to the compile command to get round this problem. Here's the
+      code:
+        #include <stdio.h>
+        #include <string.h>
+        #include <pcre.h>
+        #define OVECCOUNT 30    /* should be a multiple of 3 */
+        int main(int argc, char **argv)
+        {
+        pcre *re;
+        const char *error;
+        int erroffset;
+        int ovector[OVECCOUNT];
+        int rc, i;
+        if (argc != 3)
+          {
+          printf("Two arguments required: a regex and a "
+            "subject string\n");
+          return 1;
+          }
+        /* Compile the regular expression in the first argument */
+        re = pcre_compile(
+          argv[1],     /* the pattern */
+,           /* default options */
+          &error,      /* for error message */
+          &erroffset,  /* for error offset */
+          NULL);       /* use default character tables */
+        /* Compilation failed: print the error message and exit */
+        if (re == NULL)
+          {
+          printf("PCRE compilation failed at offset %d: %s\n",
+            erroffset, error);
+          return 1;
+          }
+        /* Compilation succeeded: match the subject in the second
+           argument */
+        rc = pcre_exec(
+          re,          /* the compiled pattern */
+          NULL,        /* we didn't study the pattern */
+          argv[2],     /* the subject string */
+          (int)strlen(argv[2]), /* the length of the subject */
+,           /* start at offset 0 in the subject */
+,           /* default options */
+          ovector,     /* vector for substring information */
+          OVECCOUNT);  /* number of elements in the vector */
+        /* Matching failed: handle error cases */
+        if (rc < 0)
+          {
+          switch(rc)
+            {
+            case PCRE_ERROR_NOMATCH: printf("No match\n"); break;
+            /*
+            Handle other special cases if you like
+            */
+            default: printf("Matching error %d\n", rc); break;
+            }
+          return 1;
+          }
+        /* Match succeded */
+        printf("Match succeeded\n");
+        /* The output vector wasn't big enough */
+        if (rc == 0)
+          {
+          rc = OVECCOUNT/3;
+          printf("ovector only has room for %d captured "
+            substrings\n", rc - 1);
+          }
+        /* Show substrings stored in the output vector */
+        for (i = 0; i < rc; i++)
+          {
+          char *substring_start = argv[2] + ovector[2*i];
+          int substring_length = ovector[2*i+1] - ovector[2*i];
+          printf("%2d: %.*s\n", i, substring_length,
+            substring_start);
+          }
+        return 0;
+        }
  AUTHOR
       Philip Hazel <ph10@cam.ac.uk>
       University Computing Service,
-Line 1742 
 AUTHOR
+Line 2311 
 AUTHOR
       Cambridge CB2 3QG, England.
       Phone: +44 1223 334714
-      Last updated: 29 July 1999
+      Last updated: 15 August 2001
-      Copyright (c) 1997-1999 University of Cambridge.
+      Copyright (c) 1997-2001 University of Cambridge.

 Legend:



Removed from v.41
 


changed lines


 
Added in v.53
 Legend:



Removed from v.41
 


changed lines


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

	ViewVC Help
Powered by ViewVC 1.1.5