/[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 175 by ph10,
Mon Jun 11 13:38:38 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 291 
 in the
+Line 293 
 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
+ accented letters, and these are matched by \ew.
  .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
-Line 518 
 why the traditional escape sequences suc
+Line 521 
 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 773 
 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 958 
 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 1039 
 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 1360 
 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 1493 
 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 1595 
 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 1616 
 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 1765 
 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 1843 
 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 1871 
 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 1895 
 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 1917 
 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: 11 June 2007
+ Copyright (c) 1997-2007 University of Cambridge.
+ .fi

 Legend:



Removed from v.96
 


changed lines


 
Added in v.175
 Legend:



Removed from v.96
 


changed lines


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

	ViewVC Help
Powered by ViewVC 1.1.5