← Back to branch summary

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

« back to all changes in this revision

Viewing changes to doc/html/pcrecallout.html

  • 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/html/pcrecallout.html
39
39
<pre>
40
40
  (?C1)abc(?C2)def
41
41
</pre>
42
 
If the PCRE_AUTO_CALLOUT option bit is set when <b>pcre_compile()</b> is called,
43
 
PCRE automatically inserts callouts, all with number 255, before each item in
44
 
the pattern. For example, if PCRE_AUTO_CALLOUT is used with the pattern
 
42
If the PCRE_AUTO_CALLOUT option bit is set when <b>pcre_compile()</b> or
 
43
<b>pcre_compile2()</b> is called, PCRE automatically inserts callouts, all with
 
44
number 255, before each item in the pattern. For example, if PCRE_AUTO_CALLOUT
 
45
is used with the pattern
45
46
<pre>
46
47
  A(\d{2}|--)
47
48
</pre>
62
63
<br><a name="SEC2" href="#TOC1">MISSING CALLOUTS</a><br>
63
64
<P>
64
65
You should be aware that, because of optimizations in the way PCRE matches
65
 
patterns, callouts sometimes do not happen. For example, if the pattern is
 
66
patterns by default, callouts sometimes do not happen. For example, if the
 
67
pattern is
66
68
<pre>
67
69
  ab(?C4)cd
68
70
</pre>
71
73
the callout is never reached. However, with "abyd", though the result is still
72
74
no match, the callout is obeyed.
73
75
</P>
 
76
<P>
 
77
If the pattern is studied, PCRE knows the minimum length of a matching string,
 
78
and will immediately give a "no match" return without actually running a match
 
79
if the subject is not long enough, or, for unanchored patterns, if it has
 
80
been scanned far enough.
 
81
</P>
 
82
<P>
 
83
You can disable these optimizations by passing the PCRE_NO_START_OPTIMIZE
 
84
option to <b>pcre_exec()</b> or <b>pcre_dfa_exec()</b>. This slows down the
 
85
matching process, but does ensure that callouts such as the example above are
 
86
obeyed.
 
87
</P>
74
88
<br><a name="SEC3" href="#TOC1">THE CALLOUT INTERFACE</a><br>
75
89
<P>
76
90
During matching, when PCRE reaches a callout point, the external function
172
186
matching proceeds as normal. If the value is greater than zero, matching fails
173
187
at the current point, but the testing of other matching possibilities goes
174
188
ahead, just as if a lookahead assertion had failed. If the value is less than
175
 
zero, the match is abandoned, and <b>pcre_exec()</b> (or <b>pcre_dfa_exec()</b>)
 
189
zero, the match is abandoned, and <b>pcre_exec()</b> or <b>pcre_dfa_exec()</b>
176
190
returns the negative value.
177
191
</P>
178
192
<P>
192
206
</P>
193
207
<br><a name="SEC6" href="#TOC1">REVISION</a><br>
194
208
<P>
195
 
Last updated: 29 May 2007
 
209
Last updated: 29 September 2009
196
210
<br>
197
 
Copyright &copy; 1997-2007 University of Cambridge.
 
211
Copyright &copy; 1997-2009 University of Cambridge.
198
212
<br>
199
213
<p>
200
214
Return to the <a href="index.html">PCRE index page</a>.