1PCRECALLOUT(3) Library Functions Manual PCRECALLOUT(3)
2
6 PCRE - Perl-compatible regular expressions
7
9 #include <pcre.h>
11 int (*pcre_callout)(pcre_callout_block *);
13 int (*pcre16_callout)(pcre16_callout_block *);
15 int (*pcre32_callout)(pcre32_callout_block *);
17
19 PCRE provides a feature called "callout", which is a means of temporar‐
21 ily passing control to the caller of PCRE in the middle of pattern
22 matching. The caller of PCRE provides an external function by putting
23 its entry point in the global variable pcre_callout (pcre16_callout for
24 the 16-bit library, pcre32_callout for the 32-bit library). By default,
25 this variable contains NULL, which disables all calling out.
26 Within a regular expression, (?C) indicates the points at which the
28 external function is to be called. Different callout points can be
29 identified by putting a number less than 256 after the letter C. The
30 default value is zero. For example, this pattern has two callout
31 points:
32 (?C1)abc(?C2)def
34 If the PCRE_AUTO_CALLOUT option bit is set when a pattern is compiled,
36 PCRE automatically inserts callouts, all with number 255, before each
37 item in the pattern. For example, if PCRE_AUTO_CALLOUT is used with the
38 pattern
39 A(\d{2}|--)
41 it is processed as if it were
43 (?C255)A(?C255)((?C255)\d{2}(?C255)|(?C255)-(?C255)-(?C255))(?C255)
45 Notice that there is a callout before and after each parenthesis and
47 alternation bar. If the pattern contains a conditional group whose con‐
48 dition is an assertion, an automatic callout is inserted immediately
49 before the condition. Such a callout may also be inserted explicitly,
50 for example:
51 (?(?C9)(?=a)ab|de)
53 This applies only to assertion conditions (because they are themselves
55 independent groups).
56 Automatic callouts can be used for tracking the progress of pattern
58 matching. The pcretest program has a pattern qualifier (/C) that sets
59 automatic callouts; when it is used, the output indicates how the pat‐
60 tern is being matched. This is useful information when you are trying
61 to optimize the performance of a particular pattern.
62
64 You should be aware that, because of optimizations in the way PCRE com‐
66 piles and matches patterns, callouts sometimes do not happen exactly as
67 you might expect.
68 At compile time, PCRE "auto-possessifies" repeated items when it knows
70 that what follows cannot be part of the repeat. For example, a+[bc] is
71 compiled as if it were a++[bc]. The pcretest output when this pattern
72 is anchored and then applied with automatic callouts to the string
73 "aaaa" is:
74 --->aaaa
76 +0 ^ ^
77 +1 ^ a+
78 +3 ^ ^ [bc]
79 No match
80 This indicates that when matching [bc] fails, there is no backtracking
82 into a+ and therefore the callouts that would be taken for the back‐
83 tracks do not occur. You can disable the auto-possessify feature by
84 passing PCRE_NO_AUTO_POSSESS to pcre_compile(), or starting the pattern
85 with (*NO_AUTO_POSSESS). If this is done in pcretest (using the /O
86 qualifier), the output changes to this:
87 --->aaaa
89 +0 ^ ^
90 +1 ^ a+
91 +3 ^ ^ [bc]
92 +3 ^ ^ [bc]
93 +3 ^ ^ [bc]
94 +3 ^^ [bc]
95 No match
96 This time, when matching [bc] fails, the matcher backtracks into a+ and
98 tries again, repeatedly, until a+ itself fails.
99 Other optimizations that provide fast "no match" results also affect
101 callouts. For example, if the pattern is
102 ab(?C4)cd
104 PCRE knows that any matching string must contain the letter "d". If the
106 subject string is "abyz", the lack of "d" means that matching doesn't
107 ever start, and the callout is never reached. However, with "abyd",
108 though the result is still no match, the callout is obeyed.
109 If the pattern is studied, PCRE knows the minimum length of a matching
111 string, and will immediately give a "no match" return without actually
112 running a match if the subject is not long enough, or, for unanchored
113 patterns, if it has been scanned far enough.
114 You can disable these optimizations by passing the PCRE_NO_START_OPTI‐
116 MIZE option to the matching function, or by starting the pattern with
117 (*NO_START_OPT). This slows down the matching process, but does ensure
118 that callouts such as the example above are obeyed.
119
121 During matching, when PCRE reaches a callout point, the external func‐
123 tion defined by pcre_callout or pcre[16|32]_callout is called (if it is
124 set). This applies to both normal and DFA matching. The only argument
125 to the callout function is a pointer to a pcre_callout or
126 pcre[16|32]_callout block. These structures contains the following
127 fields:
128 int version;
130 int callout_number;
131 int *offset_vector;
132 const char *subject; (8-bit version)
133 PCRE_SPTR16 subject; (16-bit version)
134 PCRE_SPTR32 subject; (32-bit version)
135 int subject_length;
136 int start_match;
137 int current_position;
138 int capture_top;
139 int capture_last;
140 void *callout_data;
141 int pattern_position;
142 int next_item_length;
143 const unsigned char *mark; (8-bit version)
144 const PCRE_UCHAR16 *mark; (16-bit version)
145 const PCRE_UCHAR32 *mark; (32-bit version)
146 The version field is an integer containing the version number of the
148 block format. The initial version was 0; the current version is 2. The
149 version number will change again in future if additional fields are
150 added, but the intention is never to remove any of the existing fields.
151 The callout_number field contains the number of the callout, as com‐
153 piled into the pattern (that is, the number after ?C for manual call‐
154 outs, and 255 for automatically generated callouts).
155 The offset_vector field is a pointer to the vector of offsets that was
157 passed by the caller to the matching function. When pcre_exec() or
158 pcre[16|32]_exec() is used, the contents can be inspected, in order to
159 extract substrings that have been matched so far, in the same way as
160 for extracting substrings after a match has completed. For the DFA
161 matching functions, this field is not useful.
162 The subject and subject_length fields contain copies of the values that
164 were passed to the matching function.
165 The start_match field normally contains the offset within the subject
167 at which the current match attempt started. However, if the escape
168 sequence \K has been encountered, this value is changed to reflect the
169 modified starting point. If the pattern is not anchored, the callout
170 function may be called several times from the same point in the pattern
171 for different starting points in the subject.
172 The current_position field contains the offset within the subject of
174 the current match pointer.
175 When the pcre_exec() or pcre[16|32]_exec() is used, the capture_top
177 field contains one more than the number of the highest numbered cap‐
178 tured substring so far. If no substrings have been captured, the value
179 of capture_top is one. This is always the case when the DFA functions
180 are used, because they do not support captured substrings.
181 The capture_last field contains the number of the most recently cap‐
183 tured substring. However, when a recursion exits, the value reverts to
184 what it was outside the recursion, as do the values of all captured
185 substrings. If no substrings have been captured, the value of cap‐
186 ture_last is -1. This is always the case for the DFA matching func‐
187 tions.
188 The callout_data field contains a value that is passed to a matching
190 function specifically so that it can be passed back in callouts. It is
191 passed in the callout_data field of a pcre_extra or pcre[16|32]_extra
192 data structure. If no such data was passed, the value of callout_data
193 in a callout block is NULL. There is a description of the pcre_extra
194 structure in the pcreapi documentation.
195 The pattern_position field is present from version 1 of the callout
197 structure. It contains the offset to the next item to be matched in the
198 pattern string.
199 The next_item_length field is present from version 1 of the callout
201 structure. It contains the length of the next item to be matched in the
202 pattern string. When the callout immediately precedes an alternation
203 bar, a closing parenthesis, or the end of the pattern, the length is
204 zero. When the callout precedes an opening parenthesis, the length is
205 that of the entire subpattern.
206 The pattern_position and next_item_length fields are intended to help
208 in distinguishing between different automatic callouts, which all have
209 the same callout number. However, they are set for all callouts.
210 The mark field is present from version 2 of the callout structure. In
212 callouts from pcre_exec() or pcre[16|32]_exec() it contains a pointer
213 to the zero-terminated name of the most recently passed (*MARK),
214 (*PRUNE), or (*THEN) item in the match, or NULL if no such items have
215 been passed. Instances of (*PRUNE) or (*THEN) without a name do not
216 obliterate a previous (*MARK). In callouts from the DFA matching func‐
217 tions this field always contains NULL.
218
220 The external callout function returns an integer to PCRE. If the value
222 is zero, matching proceeds as normal. If the value is greater than
223 zero, matching fails at the current point, but the testing of other
224 matching possibilities goes ahead, just as if a lookahead assertion had
225 failed. If the value is less than zero, the match is abandoned, the
226 matching function returns the negative value.
227 Negative values should normally be chosen from the set of
229 PCRE_ERROR_xxx values. In particular, PCRE_ERROR_NOMATCH forces a stan‐
230 dard "no match" failure. The error number PCRE_ERROR_CALLOUT is
231 reserved for use by callout functions; it will never be used by PCRE
232 itself.
233
235 Philip Hazel
237 University Computing Service
238 Cambridge CB2 3QH, England.
239
241 Last updated: 12 November 2013
243 Copyright (c) 1997-2013 University of Cambridge.
244PCRE 8.34 12 November 2013 PCRECALLOUT(3)