/[pcre]/code/trunk/doc/pcrepattern.3

Diff of /code/trunk/doc/pcrepattern.3

Parent Directory | Revision Log | View Patch Patch

-revision 96 by nigel,
Fri Mar  2 13:10:43 2007 UTC
+revision 182 by ph10,
Wed Jun 13 15:09:54 2007 UTC
 Line 30 
 The remainder of this document discusses
  PCRE when its main matching function, \fBpcre_exec()\fP, is used.
  From release 6.0, PCRE offers a second matching function,
  \fBpcre_dfa_exec()\fP, which matches using a different algorithm that is not
- Perl-compatible. The advantages and disadvantages of the alternative function,
+ Perl-compatible. Some of the features discussed below are not available when
- and how it differs from the normal function, are discussed in the
+ \fBpcre_dfa_exec()\fP is used. The advantages and disadvantages of the
+ alternative function, and how it differs from the normal function, are
+ discussed in the
  .\" HREF
  \fBpcrematching\fP
  .\"
-Line 239 
 meanings
+Line 241 
 meanings
  .rs
  .sp
  The sequence \eg followed by a positive or negative number, optionally enclosed
- in braces, is an absolute or relative back reference. Back references are
+ in braces, is an absolute or relative back reference. A named back reference
- discussed
+ can be coded as \eg{name}. Back references are discussed
  .\" HTML <a href="#backreferences">
  .\" </a>
  later,
-Line 260 
 following are always recognized:
+Line 262 
 following are always recognized:
  .sp
    \ed     any decimal digit
    \eD     any character that is not a decimal digit
+   \eh     any horizontal whitespace character
+   \eH     any character that is not a horizontal whitespace character
    \es     any whitespace character
    \eS     any character that is not a whitespace character
+   \ev     any vertical whitespace character
+   \eV     any character that is not a vertical whitespace character
    \ew     any "word" character
    \eW     any "non-word" character
  .sp
-Line 275 
 there is no character to match.
+Line 281 
 there is no character to match.
  .P
  For compatibility with Perl, \es does not match the VT character (code 11).
  This makes it different from the the POSIX "space" class. The \es characters
- are HT (9), LF (10), FF (12), CR (13), and space (32). (If "use locale;" is
+ are HT (9), LF (10), FF (12), CR (13), and space (32). If "use locale;" is
  included in a Perl script, \es may match the VT character. In PCRE, it never
- does.)
+ does.
+ .P
+ In UTF-8 mode, characters with values greater than 128 never match \ed, \es, or
+ \ew, and always match \eD, \eS, and \eW. This is true even when Unicode
+ character property support is available. These sequences retain their original
+ meanings from before UTF-8 support was available, mainly for efficiency
+ reasons.
+ .P
+ The sequences \eh, \eH, \ev, and \eV are Perl 5.10 features. In contrast to the
+ other sequences, these do match certain high-valued codepoints in UTF-8 mode.
+ The horizontal space characters are:
+ .sp
+   U+0009     Horizontal tab
+   U+0020     Space
+   U+00A0     Non-break space
+   U+1680     Ogham space mark
+   U+180E     Mongolian vowel separator
+   U+2000     En quad
+   U+2001     Em quad
+   U+2002     En space
+   U+2003     Em space
+   U+2004     Three-per-em space
+   U+2005     Four-per-em space
+   U+2006     Six-per-em space
+   U+2007     Figure space
+   U+2008     Punctuation space
+   U+2009     Thin space
+   U+200A     Hair space
+   U+202F     Narrow no-break space
+   U+205F     Medium mathematical space
+   U+3000     Ideographic space
+ .sp
+ The vertical space characters are:
+ .sp
+   U+000A     Linefeed
+   U+000B     Vertical tab
+   U+000C     Formfeed
+   U+000D     Carriage return
+   U+0085     Next line
+   U+2028     Line separator
+   U+2029     Paragraph separator
  .P
  A "word" character is an underscore or any character less than 256 that is a
  letter or digit. The definition of letters and digits is controlled by PCRE's
-Line 291 
 in the
+Line 337 
 in the
  .\" HREF
  \fBpcreapi\fP
  .\"
- page). For example, in the "fr_FR" (French) locale, some character codes
+ page). For example, in a French locale such as "fr_FR" in Unix-like systems,
- greater than 128 are used for accented letters, and these are matched by \ew.
+ or "french" in Windows, some character codes greater than 128 are used for
- .P
+ accented letters, and these are matched by \ew. The use of locales with Unicode
- In UTF-8 mode, characters with values greater than 128 never match \ed, \es, or
+ is discouraged.
- \ew, and always match \eD, \eS, and \eW. This is true even when Unicode
- character property support is available. The use of locales with Unicode is
- discouraged.
  .
  .
  .SS "Newline sequences"
  .rs
  .sp
  Outside a character class, the escape sequence \eR matches any Unicode newline
- sequence. This is an extension to Perl. In non-UTF-8 mode \eR is equivalent to
+ sequence. This is a Perl 5.10 feature. In non-UTF-8 mode \eR is equivalent to
  the following:
  .sp
    (?>\er\en|\en|\ex0b|\ef|\er|\ex85)
-Line 518 
 why the traditional escape sequences suc
+Line 561 
 why the traditional escape sequences suc
  properties in PCRE.
  .
  .
+ .\" HTML <a name="resetmatchstart"></a>
+ .SS "Resetting the match start"
+ .rs
+ .sp
+ The escape sequence \eK, which is a Perl 5.10 feature, causes any previously
+ matched characters not to be included in the final matched sequence. For
+ example, the pattern:
+ .sp
+   foo\eKbar
+ .sp
+ matches "foobar", but reports that it has matched "bar". This feature is
+ similar to a lookbehind assertion
+ .\" HTML <a href="#lookbehind">
+ .\" </a>
+ (described below).
+ .\"
+ However, in this case, the part of the subject before the real match does not
+ have to be of fixed length, as lookbehind assertions do. The use of \eK does
+ not interfere with the setting of
+ .\" HTML <a href="#subpattern">
+ .\" </a>
+ captured substrings.
+ .\"
+ For example, when the pattern
+ .sp
+   (foo)\eKbar
+ .sp
+ matches "foobar", the first substring is still set to "foo".
+ .
+ .
  .\" HTML <a name="smallassertions"></a>
  .SS "Simple assertions"
  .rs
-Line 740 
 example [\ex{100}-\ex{2ff}].
+Line 813 
 example [\ex{100}-\ex{2ff}].
  If a range that includes letters is used when caseless matching is set, it
  matches the letters in either case. For example, [W-c] is equivalent to
  [][\e\e^_`wxyzabc], matched caselessly, and in non-UTF-8 mode, if character
- tables for the "fr_FR" locale are in use, [\exc8-\excb] matches accented E
+ tables for a French locale are in use, [\exc8-\excb] matches accented E
  characters in both cases. In UTF-8 mode, PCRE supports the concept of case for
  characters with values greater than 128 only when it is compiled with Unicode
  property support.
-Line 925 
 is reached, an option setting in one bra
+Line 998 
 is reached, an option setting in one bra
  the above patterns match "SUNDAY" as well as "Saturday".
  .
  .
+ .SH "DUPLICATE SUBPATTERN NUMBERS"
+ .rs
+ .sp
+ Perl 5.10 introduced a feature whereby each alternative in a subpattern uses
+ the same numbers for its capturing parentheses. Such a subpattern starts with
+ (?| and is itself a non-capturing subpattern. For example, consider this
+ pattern:
+ .sp
+   (?|(Sat)ur|(Sun))day
+ .sp
+ Because the two alternatives are inside a (?| group, both sets of capturing
+ parentheses are numbered one. Thus, when the pattern matches, you can look
+ at captured substring number one, whichever alternative matched. This construct
+ is useful when you want to capture part, but not all, of one of a number of
+ alternatives. Inside a (?| group, parentheses are numbered as usual, but the
+ number is reset at the start of each branch. The numbers of any capturing
+ buffers that follow the subpattern start after the highest number used in any
+ branch. The following example is taken from the Perl documentation.
+ The numbers underneath show in which buffer the captured content will be
+ stored.
+ .sp
+   # before  ---------------branch-reset----------- after
+   / ( a )  (?| x ( y ) z | (p (q) r) | (t) u (v) ) ( z ) /x
+   # 1            2         2  3        2     3     4
+ .sp
+ A backreference or a recursive call to a numbered subpattern always refers to
+ the first one in the pattern with the given number.
+ .P
+ An alternative approach to using this "branch reset" feature is to use
+ duplicate named subpatterns, as described in the next section.
+ .
+ .
  .SH "NAMED SUBPATTERNS"
  .rs
  .sp
-Line 974 
 abbreviation. This pattern (ignoring the
+Line 1079 
 abbreviation. This pattern (ignoring the
    (?<DN>Sat)(?:urday)?
  .sp
  There are five capturing substrings, but only one is ever set after a match.
+ (An alternative way of solving this problem is to use a "branch reset"
+ subpattern, as described in the previous section.)
+ .P
  The convenience function for extracting the data by name returns the substring
  for the first (and in this example, the only) subpattern of that name that
  matched. This saves searching to find which numbered subpattern it was. If you
-Line 1292 
 back reference, the case of letters is r
+Line 1400 
 back reference, the case of letters is r
  matches "rah rah" and "RAH RAH", but not "RAH rah", even though the original
  capturing subpattern is matched caselessly.
  .P
- Back references to named subpatterns use the Perl syntax \ek<name> or \ek'name'
+ There are several different ways of writing back references to named
- or the Python syntax (?P=name). We could rewrite the above example in either of
+ subpatterns. The .NET syntax \ek{name} and the Perl syntax \ek<name> or
+ \ek'name' are supported, as is the Python syntax (?P=name). Perl 5.10's unified
+ back reference syntax, in which \eg can be used for both numeric and named
+ references, is also supported. We could rewrite the above example in any of
  the following ways:
  .sp
    (?<p1>(?i)rah)\es+\ek<p1>
+   (?'p1'(?i)rah)\es+\ek{p1}
    (?P<p1>(?i)rah)\es+(?P=p1)
+   (?<p1>(?i)rah)\es+\eg{p1}
  .sp
  A subpattern that is referenced by name may appear in the pattern before or
  after the reference.
-Line 1420 
 lengths, but it is acceptable if rewritt
+Line 1533 
 lengths, but it is acceptable if rewritt
  .sp
    (?<=abc|abde)
  .sp
+ In some cases, the Perl 5.10 escape sequence \eK
+ .\" HTML <a href="#resetmatchstart">
+ .\" </a>
+ (see above)
+ .\"
+ can be used instead of a lookbehind assertion; this is not restricted to a
+ fixed-length.
+ .P
  The implementation of lookbehind assertions is, for each alternative, to
  temporarily move the current position back by the fixed length and then try to
  match. If there are insufficient characters before the current position, the
-Line 1514 
 recursion, a pseudo-condition called DEF
+Line 1635 
 recursion, a pseudo-condition called DEF
  .sp
  If the text between the parentheses consists of a sequence of digits, the
  condition is true if the capturing subpattern of that number has previously
- matched.
+ matched. An alternative notation is to precede the digits with a plus or minus
+ sign. In this case, the subpattern number is relative rather than absolute.
+ The most recently opened parentheses can be referenced by (?(-1), the next most
+ recent by (?(-2), and so on. In looping constructs it can also make sense to
+ refer to subsequent groups with constructs such as (?(+2).
  .P
  Consider the following pattern, which contains non-significant white space to
  make it more readable (assume the PCRE_EXTENDED option) and to divide it into
-Line 1531 
 the condition is true, and so the yes-pa
+Line 1656 
 the condition is true, and so the yes-pa
  parenthesis is required. Otherwise, since no-pattern is not present, the
  subpattern matches nothing. In other words, this pattern matches a sequence of
  non-parentheses, optionally enclosed in parentheses.
+ .P
+ If you were embedding this pattern in a larger one, you could use a relative
+ reference:
+ .sp
+   ...other stuff... ( \e( )?    [^()]+    (?(-1) \e) ) ...
+ .sp
+ This makes the fragment independent of the parentheses in the larger pattern.
  .
  .SS "Checking for a used subpattern by name"
  .rs
-Line 1673 
 pattern, so instead you could use this:
+Line 1805 
 pattern, so instead you could use this:
    ( \e( ( (?>[^()]+) | (?1) )* \e) )
  .sp
  We have put the pattern into parentheses, and caused the recursion to refer to
- them instead of the whole pattern. In a larger pattern, keeping track of
+ them instead of the whole pattern.
- parenthesis numbers can be tricky. It may be more convenient to use named
+ .P
- parentheses instead. The Perl syntax for this is (?&name); PCRE's earlier
+ In a larger pattern, keeping track of parenthesis numbers can be tricky. This
- syntax (?P>name) is also supported. We could rewrite the above example as
+ is made easier by the use of relative references. (A Perl 5.10 feature.)
- follows:
+ Instead of (?1) in the pattern above you can write (?-2) to refer to the second
+ most recently opened parentheses preceding the recursion. In other words, a
+ negative number counts capturing parentheses leftwards from the point at which
+ it is encountered.
+ .P
+ It is also possible to refer to subsequently opened parentheses, by writing
+ references such as (?+2). However, these cannot be recursive because the
+ reference is not inside the parentheses that are referenced. They are always
+ "subroutine" calls, as described in the next section.
+ .P
+ An alternative approach is to use named parentheses instead. The Perl syntax
+ for this is (?&name); PCRE's earlier syntax (?P>name) is also supported. We
+ could rewrite the above example as follows:
  .sp
    (?<pn> \e( ( (?>[^()]+) | (?&pn) )* \e) )
  .sp
  If there is more than one subpattern with the same name, the earliest one is
- used. This particular example pattern contains nested unlimited repeats, and so
+ used.
- the use of atomic grouping for matching strings of non-parentheses is important
+ .P
- when applying the pattern to strings that do not match. For example, when this
+ This particular example pattern that we have been looking at contains nested
- pattern is applied to
+ unlimited repeats, and so the use of atomic grouping for matching strings of
+ non-parentheses is important when applying the pattern to strings that do not
+ match. For example, when this pattern is applied to
  .sp
    (aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa()
  .sp
-Line 1737 
 is the actual recursive call.
+Line 1883 
 is the actual recursive call.
  If the syntax for a recursive subpattern reference (either by number or by
  name) is used outside the parentheses to which it refers, it operates like a
  subroutine in a programming language. The "called" subpattern may be defined
- before or after the reference. An earlier example pointed out that the pattern
+ before or after the reference. A numbered reference can be absolute or
+ relative, as in these examples:
+ .sp
+   (...(absolute)...)...(?2)...
+   (...(relative)...)...(?-1)...
+   (...(?+1)...(relative)...
+ .sp
+ An earlier example pointed out that the pattern
  .sp
    (sens|respons)e and \e1ibility
  .sp
-Line 1758 
 When a subpattern is used as a subroutin
+Line 1911 
 When a subpattern is used as a subroutin
  case-independence are fixed when the subpattern is defined. They cannot be
  changed for different calls. For example, consider this pattern:
  .sp
-   (abc)(?i:(?1))
+   (abc)(?i:(?-1))
  .sp
  It matches "abcabc". It does not match "abcABC" because the change of
  processing option does not affect the called subpattern.
-Line 1782 
 function is to be called. If you want to
+Line 1935 
 function is to be called. If you want to
  can put a number less than 256 after the letter C. The default value is zero.
  For example, this pattern has two callout points:
  .sp
-   (?C1)\dabc(?C2)def
+   (?C1)abc(?C2)def
  .sp
  If the PCRE_AUTO_CALLOUT flag is passed to \fBpcre_compile()\fP, callouts are
  automatically installed before each item in the pattern. They are all numbered
-Line 1804 
 documentation.
+Line 1957 
 documentation.
  .rs
  .sp
  \fBpcreapi\fP(3), \fBpcrecallout\fP(3), \fBpcrematching\fP(3), \fBpcre\fP(3).
- .P
+ .
- .in 0
+ .
- Last updated: 06 December 2006
+ .SH AUTHOR
- .br
+ .rs
- Copyright (c) 1997-2006 University of Cambridge.
+ .sp
+ .nf
+ Philip Hazel
+ University Computing Service
+ Cambridge CB2 3QH, England.
+ .fi
+ .
+ .
+ .SH REVISION
+ .rs
+ .sp
+ .nf
+ Last updated: 13 June 2007
+ Copyright (c) 1997-2007 University of Cambridge.
+ .fi

 Legend:



Removed from v.96
 


changed lines


 
Added in v.182
 Legend:



Removed from v.96
 


changed lines


 
Added in v.182
-Removed from v.96
+Added in v.182

	ViewVC Help
Powered by ViewVC 1.1.5