← Back to branch summary

~ubuntu-branches/ubuntu/utopic/pcre3/utopic-proposed

« back to all changes in this revision

Viewing changes to doc/pcrecallout.3

  • Committer: Bazaar Package Importer
  • Author(s): Mark Baker
  • Date: 2010-05-07 21:18:05 UTC
  • mfrom: (1.1.9 upstream)
  • Revision ID: james.westby@ubuntu.com-20100507211805-hgyyr2003bmbu54m
Tags: 8.02-1
New upstream release

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/pcrecallout.3
19
19
.sp
20
20
  (?C1)abc(?C2)def
21
21
.sp
22
 
If the PCRE_AUTO_CALLOUT option bit is set when \fBpcre_compile()\fP is called,
23
 
PCRE automatically inserts callouts, all with number 255, before each item in
24
 
the pattern. For example, if PCRE_AUTO_CALLOUT is used with the pattern
 
22
If the PCRE_AUTO_CALLOUT option bit is set when \fBpcre_compile()\fP or
 
23
\fBpcre_compile2()\fP is called, PCRE automatically inserts callouts, all with
 
24
number 255, before each item in the pattern. For example, if PCRE_AUTO_CALLOUT
 
25
is used with the pattern
25
26
.sp
26
27
  A(\ed{2}|--)
27
28
.sp
44
45
.rs
45
46
.sp
46
47
You should be aware that, because of optimizations in the way PCRE matches
47
 
patterns, callouts sometimes do not happen. For example, if the pattern is
 
48
patterns by default, callouts sometimes do not happen. For example, if the
 
49
pattern is
48
50
.sp
49
51
  ab(?C4)cd
50
52
.sp
52
54
string is "abyz", the lack of "d" means that matching doesn't ever start, and
53
55
the callout is never reached. However, with "abyd", though the result is still
54
56
no match, the callout is obeyed.
 
57
.P
 
58
If the pattern is studied, PCRE knows the minimum length of a matching string,
 
59
and will immediately give a "no match" return without actually running a match
 
60
if the subject is not long enough, or, for unanchored patterns, if it has
 
61
been scanned far enough.
 
62
.P
 
63
You can disable these optimizations by passing the PCRE_NO_START_OPTIMIZE
 
64
option to \fBpcre_exec()\fP or \fBpcre_dfa_exec()\fP. This slows down the
 
65
matching process, but does ensure that callouts such as the example above are
 
66
obeyed.
55
67
.
56
68
.
57
69
.SH "THE CALLOUT INTERFACE"
149
161
matching proceeds as normal. If the value is greater than zero, matching fails
150
162
at the current point, but the testing of other matching possibilities goes
151
163
ahead, just as if a lookahead assertion had failed. If the value is less than
152
 
zero, the match is abandoned, and \fBpcre_exec()\fP (or \fBpcre_dfa_exec()\fP)
 
164
zero, the match is abandoned, and \fBpcre_exec()\fP or \fBpcre_dfa_exec()\fP
153
165
returns the negative value.
154
166
.P
155
167
Negative values should normally be chosen from the set of PCRE_ERROR_xxx
172
184
.rs
173
185
.sp
174
186
.nf
175
 
Last updated: 29 May 2007
176
 
Copyright (c) 1997-2007 University of Cambridge.
 
187
Last updated: 29 September 2009
 
188
Copyright (c) 1997-2009 University of Cambridge.
177
189
.fi