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

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

Parent Directory | Revision Log | View Patch Patch

-revision 511 by ph10,
Sat Mar 27 17:45:29 2010 UTC
+revision 512 by ph10,
Tue Mar 30 11:11:52 2010 UTC
 Line 2341 
 processed as anchored at the point where
  .P
  The new verbs make use of what was previously invalid syntax: an opening
  parenthesis followed by an asterisk. They are generally of the form
  (*VERB) or (*VERB:NAME). Some may take either form, with differing behaviour,
  depending on whether or not an argument is present. An name is a sequence of
  letters, digits, and underscores. If the name is empty, that is, if the closing
  parenthesis immediately follows the colon, the effect is as if the colon were
  not there. Any number of these verbs may occur in a pattern.
  .P
  PCRE contains some optimizations that are used to speed up matching by running
  some checks at the start of each match attempt. For example, it may know the
  minimum length of matching subject, or that a particular character must be
  present. When one of these optimizations suppresses the running of a match, any
  included backtracking verbs will not, of course, be processed. You can suppress
  the start-of-match optimizations by setting the PCRE_NO_START_OPTIMIZE option
  when calling \fBpcre_exec()\fP.
  .
  .
  .SS "Verbs that act immediately"
  .rs
  .sp
  The following verbs act as soon as they are encountered. They may not be
  followed by a name.
  .sp
     (*ACCEPT)
 Line 2391 
 each backtrack happens (in this example,
  .SS "Recording which path was taken"
  .rs
  .sp
  There is one verb whose main purpose is to track how a match was arrived at,
  though it also has a secondary use in conjunction with advancing the match
  starting point (see (*SKIP) below).
  .sp
    (*MARK:NAME) or (*:NAME)
 Line 2406 
 to the caller via the \fIpcre_extra\fP d
  .\" </a>
  section on \fIpcre_extra\fP
  .\"
  in the
  .\" HREF
  \fBpcreapi\fP
  .\"
 Line 2422 
 outputting of (*MARK) data:
 : XZ
    MK: B
  .sp
  The (*MARK) name is tagged with "MK:" in this output, and in this example it
  indicates which of the two alternatives matched. This is a more efficient way
  of obtaining this information than putting each alternative in its own
  capturing parentheses.
  .P
 Line 2438 
 string, causing a failure before (*MARK)
    No match
  .sp
  There are three potential starting points for this match (starting with X,
  starting with P, and with an empty string). If the pattern is anchored, the
  result is different:
  .sp
    /^X(*MARK:A)Y|^X(*MARK:B)Z/K
    XP
    No match, mark = B
  .sp
  PCRE's start-of-match optimizations can also interfere with this. For example,
  if, as a result of a call to \fBpcre_study()\fP, it knows the minimum
  subject length for a match, a shorter subject will not be scanned at all.
  .P
  Note that similar anomalies (though different in detail) exist in Perl, no
  doubt for the same reasons. The use of (*MARK) data after a failed match of an
  unanchored pattern is not recommended, unless (*COMMIT) is involved.
  .
  .
 Line 2463 
 the verb, a failure is forced. That is,
  the verb. However, when one of these verbs appears inside an atomic group, its
  effect is confined to that group, because once the group has been matched,
  there is never any backtracking into it. In this situation, backtracking can
  "jump back" to the left of the entire atomic group. (Remember also, as stated
  above, that this localization also applies in subroutine calls and assertions.)
  .P
  These verbs differ in exactly what kind of failure occurs when backtracking
 Line 2480 
 finding a match at the current starting
    a+(*COMMIT)b
  .sp
  This matches "xxaab" but not "aacaab". It can be thought of as a kind of
  dynamic anchor, or "I've started, so I must finish." The name of the most
  recently passed (*MARK) in the path is passed back when (*COMMIT) forces a
  match failure.
  .P
  Note that (*COMMIT) at the start of a pattern is not the same as an anchor,
  unless PCRE's start-of-match optimizations are turned off, as shown in this
  \fBpcretest\fP example:
  .sp
    /(*COMMIT)abc/
 Line 2494 
 unless PCRE's start-of-match optimizatio
    xyzabc\eY
    No match
  .sp
  PCRE knows that any match must start with "a", so the optimization skips along
  the subject to "a" before running the first match attempt, which succeeds. When
  the optimization is disabled by the \eY escape in the second subject, the match
  starts at "x" and so the (*COMMIT) causes it to fail without trying any other
  starting points.
  .sp
    (*PRUNE) or (*PRUNE:NAME)
  .sp
  This verb causes the match to fail at the current starting position in the
  subject if the rest of the pattern does not match. If the pattern is
  unanchored, the normal "bumpalong" advance to the next starting character then
  happens. Backtracking can occur as usual to the left of (*PRUNE), before it is
 Line 2534 
 instead of skipping on to "c".
  .sp
    (*SKIP:NAME)
  .sp
  When (*SKIP) has an associated name, its behaviour is modified. If the
  following pattern fails to match, the previous path through the pattern is
  searched for the most recent (*MARK) that has the same name. If one is found,
  the "bumpalong" advance is to the subject position that corresponds to that
  (*MARK) instead of to where (*SKIP) was encountered. If no (*MARK) with a
  matching name is found, normal "bumpalong" of one character happens (the
  (*SKIP) is ignored).
  .sp
    (*THEN) or (*THEN:NAME)

 Legend:



Removed from v.511
 


changed lines


 
Added in v.512
 Legend:



Removed from v.511
 


changed lines


 
Added in v.512
-Removed from v.511
+Added in v.512

webmaster@exim.org	ViewVC Help
Powered by ViewVC 1.1.12