pcre.inc

来自「emboss的linux版本的源代码」· INC 代码 · 共 825 行 · 第 1/2 页

EMBOSS uses the publicly available PCRE code library to do regular
expressions. 

<p>

The full documentation of the PCRE system can be seen at 
<a href="http://www.pcre.org/pcre.txt">http://www.pcre.org/pcre.txt</a>  

<p>

A condensed description of the syntax of PCRE follows, without features
that are thought not to be required for searching for patterns in
sequences (e.g.  matching non-printing characters, atomic grouping,
back-references, assertion, conditional sub-patterns, recursive
patterns, subpatterns as subroutines, callouts).  If you do neot see a
required function described below, please see the full description on
the <a href="http://www.pcre.org/pcre.txt">PCRE web site</a>. 

<p>

<H3>PCRE REGULAR EXPRESSION DETAILS</H3>

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

<p>


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

<p>


       The quick brown fox
<p>

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

<p>

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

<p>

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

</pre>

<p>

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

<p>

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

<p>

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


<h4>BACKSLASH</H4>

     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.

<p>

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

<p>

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

<p>

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

<p>

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

<p>

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

<p>

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

<p>

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

<p>

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

<p>

     These assertions may not appear in  character  classes  (but
     note  that  \b has a different meaning, namely the backspace
     character, inside a character class).

<p>

     A word boundary is a position in the  subject  string  where
     the current character and the previous character do not both
     match \w or \W (i.e. one matches \w and  the  other  matches
     \W),  or the start or end of the string if the first or last
     character matches \w, respectively.
     The \A, \Z, and \z assertions differ  from  the  traditional
     circumflex  and  dollar  (described below) in that they only
     ever match at the very start and end of the subject  string,
     whatever options are set. Thus, they are independent of multiline mode.


<H4>CIRCUMFLEX AND DOLLAR</H4>

     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. Inside a character class, circumflex has an
     entirely different meaning (see below).

<p>

     Circumflex need not be the first character of the pattern if
     a  number of alternatives are involved, but it should be the
     first thing in each alternative in which it appears  if  the
     pattern is ever to match that branch. If all possible alternatives start with a circumflex, that is, if the pattern  is
     constrained to match only at the start of the subject, it is
     said to be an "anchored" pattern. (There are also other constructs that can cause a pattern to be anchored.)

<p>

     A dollar character is an assertion which is true only if the
     current  matching point is at the end of the subject string,
     or immediately before a newline character that is  the  last
     character in the string (by default). Dollar need not be the
     last character of the pattern if a  number  of  alternatives
     are  involved,  but it should be the last item in any branch
     in which it appears.  Dollar has no  special  meaning  in  a
     character class.


<H4>FULL STOP (PERIOD, DOT)</H4>

     Outside a character class, a dot in the pattern matches  any
     one character in the subject, including a non-printing character,
but not (by default) newline.  The
     handling of dot is entirely independent of the  handling  of
     circumflex and dollar, the only relationship being that they
     both involve newline characters. Dot has no special  meaning
     in a character class.



<H4>SQUARE BRACKETS</H4>

     An opening square bracket introduces a character class, terminated
by a closing square bracket.  A closing square
     bracket on its own is not special.  If a closing square
     bracket is required as a member of the class, it should be
     the first data character in the class (after an initial circumflex,
if present) or escaped with a backslash. 

<p>

     A character class matches a single character in the subject.
     A matched character must be in the set of characters defined
     by the class, unless the first character in the class definition is
a circumflex, in which case the subject character
     must not be in the set defined by the class. If a circumflex
     is actually required as a member of the class, ensure it  is
     not the first character, or escape it with a backslash.

<p>

     For example, the character class [aeiou] matches  any  lower
     case vowel, while [^aeiou] matches any character that is not
     a lower case vowel.  Note that a circumflex is just a convenient
notation for specifying the characters which are in
     the class by enumerating those that are not. It  is  not  an
     assertion:  it  still  consumes a character from the subject
     string, and fails if the current pointer is at  the  end  of
     the string.

<p>

     When caseless matching  is  set,  any  letters  in  a  class
     represent  both their upper case and lower case versions, so
     for example, a caseless [aeiou] matches "A" as well as  "a",
     and  a caseless [^aeiou] does not match "A", whereas a caseful version would. PCRE does not support the concept of case
     for characters with values greater than 255.
     A  class  such  as  [^a]  will
     always match a newline.

<p>

     The minus (hyphen) character can be used to specify a  range
     of  characters  in  a  character  class.  For example, [d-m]
     matches any letter between d and m, inclusive.  If  a  minus
     character  is required in a class, it must be escaped with a
     backslash or appear in a position where it cannot be  interpreted as indicating a range, typically as the first or last
     character in the class.

<p>

     It is not possible to have the literal character "]" as  the
     end  character  of  a  range.  A  pattern such as [W-]46] is
     interpreted as a class of two characters ("W" and "-")  followed by a literal string "46]", so it would match "W46]" or
     "-46]". However, if the "]" is escaped with a  backslash  it
     is  interpreted  as  the end of range, so [W-\]46] is interpreted as a single class containing a range followed by  two
     separate characters. The octal or hexadecimal representation
     of "]" can also be used to end a range.

<p>

     The character types \d, \D, \s, \S,  \w,  and  \W  may  also
     appear  in  a  character  class, and add the characters that
     they match to the class. For example, [\dABCDEF] matches any
     hexadecimal  digit.  A  circumflex  can conveniently be used
     with the upper case character types to specify a  more  restricted set of characters than the matching lower case type.
     For example, the class [^\W_] matches any letter  or  digit,
     but not underscore.

<p>

     All non-alphameric characters other than \,  -,  ^  (at  the
     start)  and  the  terminating ] are non-special in character
     classes, but it does no harm if they are escaped.


<H4>VERTICAL BAR</H4>

     Vertical bar characters are  used  to  separate  alternative
     patterns. For example, the pattern

<p>

       gilbert|sullivan

<p>

     matches either "gilbert" or "sullivan". Any number of alternatives  may  appear,  and an empty alternative is permitted
     (matching the empty string).   The  matching  process  tries
     each  alternative in turn, from left to right, and the first
     one that succeeds is used. If the alternatives are within  a
     subpattern  (defined  below),  "succeeds" means matching the
     rest of the main pattern as well as the alternative  in  the
     subpattern.


<H4>INTERNAL OPTION SETTING</H4>

     The   settings   of   the   PCRE_CASELESS,   PCRE_MULTILINE,
     PCRE_DOTALL,  and  PCRE_EXTENDED options can be changed from
     within the pattern by a  sequence  of  Perl  option  letters
     enclosed between "(?" and ")". The option letters are

<p>
<pre>
       i  for PCRE_CASELESS
       m  for PCRE_MULTILINE
       s  for PCRE_DOTALL
       x  for PCRE_EXTENDED
</pre>

<p>

     For example, (?im) sets caseless, multiline matching. It  is
     also possible to unset these options by preceding the letter
     with a hyphen, and a combined setting and unsetting such  as
     (?im-sx),  which sets PCRE_CASELESS and PCRE_MULTILINE while
     unsetting PCRE_DOTALL and PCRE_EXTENDED, is also  permitted.
     If  a  letter  appears both before and after the hyphen, the
     option is unset.

<p>

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

<p>

     An option change within a subpattern affects only that  part
     of the current pattern that follows it, so

<p>

       (a(?i)b)c

<p>

     matches  abc  and  aBc  and  no  other   strings   (assuming
     PCRE_CASELESS  is  not used).  By this means, options can be
     made to have different settings in different  parts  of  the
     pattern.  Any  changes  made  in one alternative do carry on
     into subsequent branches within  the  same  subpattern.  For
     example,

<p>

       (a(?i)b|c)

<p>

     matches "ab", "aB", "c", and "C", even though when  matching
     "C" the first branch is abandoned before the option setting.
     This is because the effects of  option  settings  happen  at
     compile  time. There would be some very weird behaviour otherwise.

<p>

     The PCRE-specific options PCRE_UNGREEDY and  PCRE_EXTRA  can
     be changed in the same way as the Perl-compatible options by
     using the characters U and X  respectively.  The  (?X)  flag
     setting  is  special in that it must always occur earlier in
     the pattern than any of the additional features it turns on,
     even when it is at top level. It is best put at the start.


<H4>SUBPATTERNS</H4>

     Subpatterns are delimited by parentheses  (round  brackets),
     which can be nested.  Marking part of a pattern as a subpattern
does two things:

<p>

     1. It localizes a set of alternatives. For example, the pattern

<p>