| 1966 |
documentation. |
documentation. |
| 1967 |
. |
. |
| 1968 |
. |
. |
| 1969 |
|
.SH "BACTRACKING CONTROL" |
| 1970 |
|
.rs |
| 1971 |
|
.sp |
| 1972 |
|
Perl 5.10 introduced a number of "Special Backtracking Control Verbs", which |
| 1973 |
|
are described in the Perl documentation as "experimental and subject to change |
| 1974 |
|
or removal in a future version of Perl". It goes on to say: "Their usage in |
| 1975 |
|
production code should be noted to avoid problems during upgrades." The same |
| 1976 |
|
remarks apply to the PCRE features described in this section. |
| 1977 |
|
.P |
| 1978 |
|
Since these verbs are specifically related to backtracking, they can be used |
| 1979 |
|
only when the pattern is to be matched using \fBpcre_exec()\fP, which uses a |
| 1980 |
|
backtracking algorithm. They cause an error if encountered by |
| 1981 |
|
\fBpcre_dfa_exec()\fP. |
| 1982 |
|
.P |
| 1983 |
|
The new verbs make use of what was previously invalid syntax: an opening |
| 1984 |
|
parenthesis followed by an asterisk. In Perl, they are generally of the form |
| 1985 |
|
(*VERB:ARG) but PCRE does not support the use of arguments, so its general |
| 1986 |
|
form is just (*VERB). Any number of these verbs may occur in a pattern. There |
| 1987 |
|
are two kinds: |
| 1988 |
|
. |
| 1989 |
|
.SS "Verbs that act immediately" |
| 1990 |
|
.rs |
| 1991 |
|
.sp |
| 1992 |
|
The following verbs act as soon as they are encountered: |
| 1993 |
|
.sp |
| 1994 |
|
(*ACCEPT) |
| 1995 |
|
.sp |
| 1996 |
|
This verb causes the match to end successfully, skipping the remainder of the |
| 1997 |
|
pattern. When inside a recursion, only the innermost pattern is ended |
| 1998 |
|
immediately. PCRE differs from Perl in what happens if the (*ACCEPT) is inside |
| 1999 |
|
capturing parentheses. In Perl, the data so far is captured: in PCRE no data is |
| 2000 |
|
captured. For example: |
| 2001 |
|
.sp |
| 2002 |
|
A(A|B(*ACCEPT)|C)D |
| 2003 |
|
.sp |
| 2004 |
|
This matches "AB", "AAD", or "ACD", but when it matches "AB", no data is |
| 2005 |
|
captured. |
| 2006 |
|
.sp |
| 2007 |
|
(*FAIL) or (*F) |
| 2008 |
|
.sp |
| 2009 |
|
This verb causes the match to fail, forcing backtracking to occur. It is |
| 2010 |
|
equivalent to (?!) but easier to read. The Perl documentation notes that it is |
| 2011 |
|
probably useful only when combined with (?{}) or (??{}). Those are, of course, |
| 2012 |
|
Perl features that are not present in PCRE. The nearest equivalent is the |
| 2013 |
|
callout feature, as for example in this pattern: |
| 2014 |
|
.sp |
| 2015 |
|
a+(?C)(*FAIL) |
| 2016 |
|
.sp |
| 2017 |
|
A match with the string "aaaa" always fails, but the callout is taken before |
| 2018 |
|
each backtrack happens (in this example, 10 times). |
| 2019 |
|
. |
| 2020 |
|
.SS "Verbs that act after backtracking" |
| 2021 |
|
.rs |
| 2022 |
|
.sp |
| 2023 |
|
The following verbs do nothing when they are encountered. Matching continues |
| 2024 |
|
with what follows, but if there is no subsequent match, a failure is forced. |
| 2025 |
|
The verbs differ in exactly what kind of failure occurs. |
| 2026 |
|
.sp |
| 2027 |
|
(*COMMIT) |
| 2028 |
|
.sp |
| 2029 |
|
This verb causes the whole match to fail outright if the rest of the pattern |
| 2030 |
|
does not match. Even if the pattern is unanchored, no further attempts to find |
| 2031 |
|
a match by advancing the start point take place. Once (*COMMIT) has been |
| 2032 |
|
passed, \fBpcre_exec()\fP is committed to finding a match at the current |
| 2033 |
|
starting point, or not at all. For example: |
| 2034 |
|
.sp |
| 2035 |
|
a+(*COMMIT)b |
| 2036 |
|
.sp |
| 2037 |
|
This matches "xxaab" but not "aacaab". It can be thought of as a kind of |
| 2038 |
|
dynamic anchor, or "I've started, so I must finish." |
| 2039 |
|
.sp |
| 2040 |
|
(*PRUNE) |
| 2041 |
|
.sp |
| 2042 |
|
This verb causes the match to fail at the current position if the rest of the |
| 2043 |
|
pattern does not match. If the pattern is unanchored, the normal "bumpalong" |
| 2044 |
|
advance to the next starting character then happens. Backtracking can occur as |
| 2045 |
|
usual to the left of (*PRUNE), or when matching to the right of (*PRUNE), but |
| 2046 |
|
if there is no match to the right, backtracking cannot cross (*PRUNE). |
| 2047 |
|
In simple cases, the use of (*PRUNE) is just an alternative to an atomic |
| 2048 |
|
group or possessive quantifier, but there are some uses of (*PRUNE) that cannot |
| 2049 |
|
be expressed in any other way. |
| 2050 |
|
.sp |
| 2051 |
|
(*SKIP) |
| 2052 |
|
.sp |
| 2053 |
|
This verb is like (*PRUNE), except that if the pattern is unanchored, the |
| 2054 |
|
"bumpalong" advance is not to the next character, but to the position in the |
| 2055 |
|
subject where (*SKIP) was encountered. (*SKIP) signifies that whatever text |
| 2056 |
|
was matched leading up to it cannot be part of a successful match. Consider: |
| 2057 |
|
.sp |
| 2058 |
|
a+(*SKIP)b |
| 2059 |
|
.sp |
| 2060 |
|
If the subject is "aaaac...", after the first match attempt fails (starting at |
| 2061 |
|
the first character in the string), the starting point skips on to start the |
| 2062 |
|
next attempt at "c". Note that a possessive quantifer does not have the same |
| 2063 |
|
effect in this example; although it would suppress backtracking during the |
| 2064 |
|
first match attempt, the second attempt would start at the second character |
| 2065 |
|
instead of skipping on to "c". |
| 2066 |
|
.sp |
| 2067 |
|
(*THEN) |
| 2068 |
|
.sp |
| 2069 |
|
This verb causes a skip to the next alternation if the rest of the pattern does |
| 2070 |
|
not match. That is, it cancels pending backtracking, but only within the |
| 2071 |
|
current alternation. Its name comes from the observation that it can be used |
| 2072 |
|
for a pattern-based if-then-else block: |
| 2073 |
|
.sp |
| 2074 |
|
( COND1 (*THEN) FOO | COND2 (*THEN) BAR | COND3 (*THEN) BAZ ) ... |
| 2075 |
|
.sp |
| 2076 |
|
If the COND1 pattern matches, FOO is tried (and possibly further items after |
| 2077 |
|
the end of the group if FOO succeeds); on failure the matcher skips to the |
| 2078 |
|
second alternative and tries COND2, without backtracking into COND1. If (*THEN) |
| 2079 |
|
is used outside of any alternation, it acts exactly like (*PRUNE). |
| 2080 |
|
. |
| 2081 |
|
. |
| 2082 |
.SH "SEE ALSO" |
.SH "SEE ALSO" |
| 2083 |
.rs |
.rs |
| 2084 |
.sp |
.sp |
| 2099 |
.rs |
.rs |
| 2100 |
.sp |
.sp |
| 2101 |
.nf |
.nf |
| 2102 |
Last updated: 06 August 2007 |
Last updated: 08 August 2007 |
| 2103 |
Copyright (c) 1997-2007 University of Cambridge. |
Copyright (c) 1997-2007 University of Cambridge. |
| 2104 |
.fi |
.fi |
Parent Directory
| 
Revision Log
| 
Patch