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

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

Parent Directory | Revision Log | View Patch Patch

-revision 491 by ph10,
Mon Mar  1 17:45:08 2010 UTC
+revision 513 by ph10,
Mon May  3 11:13:37 2010 UTC
 Line 295 
 zero, because no more than three octal d
  .P
  All the sequences that define a single character value can be used both inside
  and outside character classes. In addition, inside a character class, the
- sequence \eb is interpreted as the backspace character (hex 08), and the
+ sequence \eb is interpreted as the backspace character (hex 08). The sequences
- sequences \eR and \eX are interpreted as the characters "R" and "X",
+ \eB, \eR, and \eX are not special inside a character class. Like any other
- respectively. Outside a character class, these sequences have different
+ unrecognized escape sequences, they are treated as the literal characters "B",
- meanings
+ "R", and "X" by default, but cause an error if the PCRE_EXTRA option is set.
+ Outside a character class, these sequences have different meanings
  .\" HTML <a href="#uniextseq">
  .\" </a>
  (see below).
-Line 478 
 convention, for example, a pattern can s
+Line 479 
 convention, for example, a pattern can s
  .sp
    (*ANY)(*BSR_ANYCRLF)
  .sp
- Inside a character class, \eR matches the letter "R".
+ Inside a character class, \eR is treated as an unrecognized escape sequence,
+ and so matches the letter "R" by default, but causes an error if PCRE_EXTRA is
+ set.
  .
  .
  .\" HTML <a name="uniextseq"></a>
-Line 737 
 For example, when the pattern
+Line 740 
 For example, when the pattern
    (foo)\eKbar
  .sp
  matches "foobar", the first substring is still set to "foo".
+ .P
+ Perl documents that the use of \eK within assertions is "not well defined". In
+ PCRE, \eK is acted upon when it occurs inside positive assertions, but is
+ ignored in negative assertions.
  .
  .
  .\" HTML <a name="smallassertions"></a>
-Line 761 
 The backslashed assertions are:
+Line 768 
 The backslashed assertions are:
    \ez     matches only at the end of the subject
    \eG     matches at the first matching position in the subject
  .sp
- These assertions may not appear in character classes (but note that \eb has a
+ Inside a character class, \eb has a different meaning; it matches the backspace
- different meaning, namely the backspace character, inside a character class).
+ character. If any other of these assertions appears in a character class, by
+ default it matches the corresponding literal character (for example, \eB
+ matches the letter B). However, if the PCRE_EXTRA option is set, an "invalid
+ escape sequence" error is generated instead.
  .P
  A word boundary is a position in the subject string where the current character
  and the previous character do not both match \ew or \eW (i.e. one matches
-Line 2314 
 description of the interface to the call
+Line 2324 
 description of the interface to the call
  documentation.
  .
  .
+ .\" HTML <a name="backtrackcontrol"></a>
  .SH "BACKTRACKING CONTROL"
  .rs
  .sp
-Line 2335 
 it does not extend to the surrounding pa
+Line 2346 
 it does not extend to the surrounding pa
  processed as anchored at the point where they are tested.
  .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
+ 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:
+ The following verbs act as soon as they are encountered. They may not be
+ followed by a name.
  .sp
     (*ACCEPT)
  .sp
-Line 2370 
 callout feature, as for example in this
+Line 2393 
 callout feature, as for example in this
  A match with the string "aaaa" always fails, but the callout is taken before
  each backtrack happens (in this example, 10 times).
  .
+ .
+ .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)
+ .sp
+ 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
+ When a match succeeds, the name of the last-encountered (*MARK) is passed back
+ to the caller via the \fIpcre_extra\fP data structure, as described in the
+ .\" HTML <a href="pcreapi.html#extradata">
+ .\" </a>
+ section on \fIpcre_extra\fP
+ .\"
+ in the
+ .\" HREF
+ \fBpcreapi\fP
+ .\"
+ documentation. No data is returned for a partial match. Here is an example of
+ \fBpcretest\fP output, where the /K modifier requests the retrieval and
+ outputting of (*MARK) data:
+ .sp
+   /X(*MARK:A)Y|X(*MARK:B)Z/K
+   XY
+: XY
+   MK: A
+   XZ
+: 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
+ 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:
+ .sp
+   /X(*MARK:A)Y|X(*MARK:B)Z/K
+   XP
+   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.
+ .
+ .
  .SS "Verbs that act after backtracking"
  .rs
  .sp
  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
+ These verbs differ in exactly what kind of failure occurs when backtracking
+ reaches them.
  .sp
    (*COMMIT)
  .sp
- 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, \fBpcre_exec()\fP is committed to finding a match at the current
+ take place. Once (*COMMIT) has been passed, \fBpcre_exec()\fP 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:
  .sp
    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."
+ dynamic anchor, or "I've started, so I must finish." The name of the most
- .sp
+ recently passed (*MARK) in the path is passed back when (*COMMIT) forces a
-   (*PRUNE)
+ match failure.
- .sp
+ .P
- This verb causes the match to fail at the current position if the rest of the
+ Note that (*COMMIT) at the start of a pattern is not the same as an anchor,
- pattern does not match. If the pattern is unanchored, the normal "bumpalong"
+ unless PCRE's start-of-match optimizations are turned off, as shown in this
- advance to the next starting character then happens. Backtracking can occur as
+ \fBpcretest\fP example:
- usual to the left of (*PRUNE), or when matching to the right of (*PRUNE), but
+ .sp
- if there is no match to the right, backtracking cannot cross (*PRUNE).
+   /(*COMMIT)abc/
- In simple cases, the use of (*PRUNE) is just an alternative to an atomic
+   xyzabc
- group or possessive quantifier, but there are some uses of (*PRUNE) that cannot
+: abc
- be expressed in any other way.
+   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
+ 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).
  .sp
    (*SKIP)
  .sp
- 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:
  .sp
    a+(*SKIP)b
  .sp
-Line 2417 
 effect as this example; although it woul
+Line 2538 
 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".
  .sp
-   (*THEN)
+   (*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)
  .sp
  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 2428 
 for a pattern-based if-then-else block:
+Line 2559 
 for a pattern-based if-then-else block:
  .sp
  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).
  .
  .
  .SH "SEE ALSO"
-Line 2453 
 Cambridge CB2 3QH, England.
+Line 2586 
 Cambridge CB2 3QH, England.
  .rs
  .sp
  .nf
- Last updated: 01 March 2010
+ Last updated: 03 May 2010
  Copyright (c) 1997-2010 University of Cambridge.
  .fi

 Legend:



Removed from v.491
 


changed lines


 
Added in v.513
 Legend:



Removed from v.491
 


changed lines


 
Added in v.513
-Removed from v.491
+Added in v.513

webmaster@exim.org	ViewVC Help
Powered by ViewVC 1.1.12