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

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

Parent Directory | Revision Log | View Patch Patch

-revision 507 by ph10,
Wed Mar 10 16:08:01 2010 UTC
+revision 512 by ph10,
Tue Mar 30 11:11:52 2010 UTC
 Line 2289 
 may cause matching to proceed, to backtr
  description of the interface to the callout function is given in the
  <a href="pcrecallout.html"><b>pcrecallout</b></a>
  documentation.
- </P>
+ <a name="backtrackcontrol"></a></P>
  <br><a name="SEC25" href="#TOC1">BACKTRACKING CONTROL</a><br>
  <P>
  Perl 5.10 introduced a number of "Special Backtracking Control Verbs", which
 Line 2313 
 processed as anchored at the point where
  </P>
  <P>
  The new verbs make use of what was previously invalid syntax: an opening
- parenthesis followed by an asterisk. In Perl, they are generally of the form
+ parenthesis followed by an asterisk. They are generally of the form
- (*VERB:ARG) but PCRE does not support the use of arguments, so its general
+ (*VERB) or (*VERB:NAME). Some may take either form, with differing behaviour,
- form is just (*VERB). Any number of these verbs may occur in a pattern. There
+ depending on whether or not an argument is present. An name is a sequence of
- are two kinds:
+ 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>
+ <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 <b>pcre_exec()</b>.
  </P>
  <br><b>
  Verbs that act immediately
  </b><br>
  <P>
- The following verbs act as soon as they are encountered:
+ The following verbs act as soon as they are encountered. They may not be
+ followed by a name.
  <pre>
     (*ACCEPT)
  </pre>
-Line 2350 
 A match with the string "aaaa" always fa
+Line 2362 
 A match with the string "aaaa" always fa
  each backtrack happens (in this example, 10 times).
  </P>
  <br><b>
+ Recording which path was taken
+ </b><br>
+ <P>
+ 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).
+ <pre>
+   (*MARK:NAME) or (*:NAME)
+ </pre>
+ A name is always required with this verb. There may be as many instances of
+ (*MARK) as you like in a pattern, and their names do not have to be unique.
+ </P>
+ <P>
+ When a match succeeds, the name of the last-encountered (*MARK) is passed back
+ to the caller via the <i>pcre_extra</i> data structure, as described in the
+ <a href="pcreapi.html#extradata">section on <i>pcre_extra</i></a>
+ in the
+ <a href="pcreapi.html"><b>pcreapi</b></a>
+ documentation. No data is returned for a partial match. Here is an example of
+ <b>pcretest</b> output, where the /K modifier requests the retrieval and
+ outputting of (*MARK) data:
+ <pre>
+   /X(*MARK:A)Y|X(*MARK:B)Z/K
+   XY
+: XY
+   MK: A
+   XZ
+: XZ
+   MK: B
+ </pre>
+ 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>
+ <P>
+ A name may also be returned after a failed match if the final path through the
+ pattern involves (*MARK). However, unless (*MARK) used in conjunction with
+ (*COMMIT), this is unlikely to happen for an unanchored pattern because, as the
+ starting point for matching is advanced, the final check is often with an empty
+ string, causing a failure before (*MARK) is reached. For example:
+ <pre>
+   /X(*MARK:A)Y|X(*MARK:B)Z/K
+   XP
+   No match
+ </pre>
+ 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:
+ <pre>
+   /^X(*MARK:A)Y|^X(*MARK:B)Z/K
+   XP
+   No match, mark = B
+ </pre>
+ PCRE's start-of-match optimizations can also interfere with this. For example,
+ if, as a result of a call to <b>pcre_study()</b>, it knows the minimum
+ subject length for a match, a shorter subject will not be scanned at all.
+ </P>
+ <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.
+ </P>
+ <br><b>
  Verbs that act after backtracking
  </b><br>
  <P>
  The following verbs do nothing when they are encountered. Matching continues
- with what follows, but if there is no subsequent match, a failure is forced.
+ with what follows, but if there is no subsequent match, causing a backtrack to
- The verbs differ in exactly what kind of failure occurs.
+ the verb, a failure is forced. That is, backtracking cannot pass to the left of
+ 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>
+ <P>
+ These verbs differ in exactly what kind of failure occurs when backtracking
+ reaches them.
  <pre>
    (*COMMIT)
  </pre>
- This verb causes the whole match to fail outright if the rest of the pattern
+ This verb, which may not be followed by a name, causes the whole match to fail
- does not match. Even if the pattern is unanchored, no further attempts to find
+ outright if the rest of the pattern does not match. Even if the pattern is
- a match by advancing the starting point take place. Once (*COMMIT) has been
+ unanchored, no further attempts to find a match by advancing the starting point
- passed, <b>pcre_exec()</b> is committed to finding a match at the current
+ take place. Once (*COMMIT) has been passed, <b>pcre_exec()</b> is committed to
- starting point, or not at all. For example:
+ finding a match at the current starting point, or not at all. For example:
  <pre>
    a+(*COMMIT)b
  </pre>
  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."
+ dynamic anchor, or "I've started, so I must finish." The name of the most
- <pre>
+ recently passed (*MARK) in the path is passed back when (*COMMIT) forces a
-   (*PRUNE)
+ match failure.
- </pre>
+ </P>
- This verb causes the match to fail at the current position if the rest of the
+ <P>
- pattern does not match. If the pattern is unanchored, the normal "bumpalong"
+ Note that (*COMMIT) at the start of a pattern is not the same as an anchor,
- advance to the next starting character then happens. Backtracking can occur as
+ unless PCRE's start-of-match optimizations are turned off, as shown in this
- usual to the left of (*PRUNE), or when matching to the right of (*PRUNE), but
+ <b>pcretest</b> example:
- if there is no match to the right, backtracking cannot cross (*PRUNE).
+ <pre>
- In simple cases, the use of (*PRUNE) is just an alternative to an atomic
+   /(*COMMIT)abc/
- group or possessive quantifier, but there are some uses of (*PRUNE) that cannot
+   xyzabc
- be expressed in any other way.
+: abc
+   xyzabc\Y
+   No match
+ </pre>
+ 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 \Y escape in the second subject, the match
+ starts at "x" and so the (*COMMIT) causes it to fail without trying any other
+ starting points.
+ <pre>
+   (*PRUNE) or (*PRUNE:NAME)
+ </pre>
+ 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
+ reached, or when matching to the right of (*PRUNE), but if there is no match to
+ the right, backtracking cannot cross (*PRUNE). In simple cases, the use of
+ (*PRUNE) is just an alternative to an atomic group or possessive quantifier,
+ but there are some uses of (*PRUNE) that cannot be expressed in any other way.
+ The behaviour of (*PRUNE:NAME) is the same as (*MARK:NAME)(*PRUNE) when the
+ match fails completely; the name is passed back if this is the final attempt.
+ (*PRUNE:NAME) does not pass back a name if the match succeeds. In an anchored
+ pattern (*PRUNE) has the same effect as (*COMMIT).
  <pre>
    (*SKIP)
  </pre>
- This verb is like (*PRUNE), except that if the pattern is unanchored, the
+ This verb, when given without a name, is like (*PRUNE), except that if the
- "bumpalong" advance is not to the next character, but to the position in the
+ pattern is unanchored, the "bumpalong" advance is not to the next character,
- subject where (*SKIP) was encountered. (*SKIP) signifies that whatever text
+ but to the position in the subject where (*SKIP) was encountered. (*SKIP)
- was matched leading up to it cannot be part of a successful match. Consider:
+ signifies that whatever text was matched leading up to it cannot be part of a
+ successful match. Consider:
  <pre>
    a+(*SKIP)b
  </pre>
-Line 2397 
 effect as this example; although it woul
+Line 2506 
 effect as this example; although it woul
  first match attempt, the second attempt would start at the second character
  instead of skipping on to "c".
  <pre>
-   (*THEN)
+   (*SKIP:NAME)
+ </pre>
+ 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).
+ <pre>
+   (*THEN) or (*THEN:NAME)
  </pre>
  This verb causes a skip to the next alternation if the rest of the pattern does
  not match. That is, it cancels pending backtracking, but only within the
-Line 2408 
 for a pattern-based if-then-else block:
+Line 2527 
 for a pattern-based if-then-else block:
  </pre>
  If the COND1 pattern matches, FOO is tried (and possibly further items after
  the end of the group if FOO succeeds); on failure the matcher skips to the
- second alternative and tries COND2, without backtracking into COND1. If (*THEN)
+ second alternative and tries COND2, without backtracking into COND1. The
- is used outside of any alternation, it acts exactly like (*PRUNE).
+ behaviour of (*THEN:NAME) is exactly the same as (*MARK:NAME)(*THEN) if the
+ overall match fails. If (*THEN) is not directly inside an alternation, it acts
+ like (*PRUNE).
  </P>
  <br><a name="SEC26" href="#TOC1">SEE ALSO</a><br>
  <P>
-Line 2427 
 Cambridge CB2 3QH, England.
+Line 2548 
 Cambridge CB2 3QH, England.
  </P>
  <br><a name="SEC28" href="#TOC1">REVISION</a><br>
  <P>
- Last updated: 06 March 2010
+ Last updated: 27 March 2010
  <br>
  Copyright &copy; 1997-2010 University of Cambridge.
  <br>

 Legend:



Removed from v.507
 


changed lines


 
Added in v.512
 Legend:



Removed from v.507
 


changed lines


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

webmaster@exim.org	ViewVC Help
Powered by ViewVC 1.1.12