|
1 <html> |
|
2 <head> |
|
3 <title>pcrecallout specification</title> |
|
4 </head> |
|
5 <body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB"> |
|
6 <h1>pcrecallout man page</h1> |
|
7 <p> |
|
8 Return to the <a href="index.html">PCRE index page</a>. |
|
9 </p> |
|
10 <p> |
|
11 This page is part of the PCRE HTML documentation. It was generated automatically |
|
12 from the original man page. If there is any nonsense in it, please consult the |
|
13 man page, in case the conversion went wrong. |
|
14 <br> |
|
15 <ul> |
|
16 <li><a name="TOC1" href="#SEC1">PCRE CALLOUTS</a> |
|
17 <li><a name="TOC2" href="#SEC2">MISSING CALLOUTS</a> |
|
18 <li><a name="TOC3" href="#SEC3">THE CALLOUT INTERFACE</a> |
|
19 <li><a name="TOC4" href="#SEC4">RETURN VALUES</a> |
|
20 <li><a name="TOC5" href="#SEC5">AUTHOR</a> |
|
21 <li><a name="TOC6" href="#SEC6">REVISION</a> |
|
22 </ul> |
|
23 <br><a name="SEC1" href="#TOC1">PCRE CALLOUTS</a><br> |
|
24 <P> |
|
25 <b>int (*pcre_callout)(pcre_callout_block *);</b> |
|
26 </P> |
|
27 <P> |
|
28 PCRE provides a feature called "callout", which is a means of temporarily |
|
29 passing control to the caller of PCRE in the middle of pattern matching. The |
|
30 caller of PCRE provides an external function by putting its entry point in the |
|
31 global variable <i>pcre_callout</i>. By default, this variable contains NULL, |
|
32 which disables all calling out. |
|
33 </P> |
|
34 <P> |
|
35 Within a regular expression, (?C) indicates the points at which the external |
|
36 function is to be called. Different callout points can be identified by putting |
|
37 a number less than 256 after the letter C. The default value is zero. |
|
38 For example, this pattern has two callout points: |
|
39 <pre> |
|
40 (?C1)abc(?C2)def |
|
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 |
|
45 <pre> |
|
46 A(\d{2}|--) |
|
47 </pre> |
|
48 it is processed as if it were |
|
49 <br> |
|
50 <br> |
|
51 (?C255)A(?C255)((?C255)\d{2}(?C255)|(?C255)-(?C255)-(?C255))(?C255) |
|
52 <br> |
|
53 <br> |
|
54 Notice that there is a callout before and after each parenthesis and |
|
55 alternation bar. Automatic callouts can be used for tracking the progress of |
|
56 pattern matching. The |
|
57 <a href="pcretest.html"><b>pcretest</b></a> |
|
58 command has an option that sets automatic callouts; when it is used, the output |
|
59 indicates how the pattern is matched. This is useful information when you are |
|
60 trying to optimize the performance of a particular pattern. |
|
61 </P> |
|
62 <br><a name="SEC2" href="#TOC1">MISSING CALLOUTS</a><br> |
|
63 <P> |
|
64 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 <pre> |
|
67 ab(?C4)cd |
|
68 </pre> |
|
69 PCRE knows that any matching string must contain the letter "d". If the subject |
|
70 string is "abyz", the lack of "d" means that matching doesn't ever start, and |
|
71 the callout is never reached. However, with "abyd", though the result is still |
|
72 no match, the callout is obeyed. |
|
73 </P> |
|
74 <br><a name="SEC3" href="#TOC1">THE CALLOUT INTERFACE</a><br> |
|
75 <P> |
|
76 During matching, when PCRE reaches a callout point, the external function |
|
77 defined by <i>pcre_callout</i> is called (if it is set). This applies to both |
|
78 the <b>pcre_exec()</b> and the <b>pcre_dfa_exec()</b> matching functions. The |
|
79 only argument to the callout function is a pointer to a <b>pcre_callout</b> |
|
80 block. This structure contains the following fields: |
|
81 <pre> |
|
82 int <i>version</i>; |
|
83 int <i>callout_number</i>; |
|
84 int *<i>offset_vector</i>; |
|
85 const char *<i>subject</i>; |
|
86 int <i>subject_length</i>; |
|
87 int <i>start_match</i>; |
|
88 int <i>current_position</i>; |
|
89 int <i>capture_top</i>; |
|
90 int <i>capture_last</i>; |
|
91 void *<i>callout_data</i>; |
|
92 int <i>pattern_position</i>; |
|
93 int <i>next_item_length</i>; |
|
94 </pre> |
|
95 The <i>version</i> field is an integer containing the version number of the |
|
96 block format. The initial version was 0; the current version is 1. The version |
|
97 number will change again in future if additional fields are added, but the |
|
98 intention is never to remove any of the existing fields. |
|
99 </P> |
|
100 <P> |
|
101 The <i>callout_number</i> field contains the number of the callout, as compiled |
|
102 into the pattern (that is, the number after ?C for manual callouts, and 255 for |
|
103 automatically generated callouts). |
|
104 </P> |
|
105 <P> |
|
106 The <i>offset_vector</i> field is a pointer to the vector of offsets that was |
|
107 passed by the caller to <b>pcre_exec()</b> or <b>pcre_dfa_exec()</b>. When |
|
108 <b>pcre_exec()</b> is used, the contents can be inspected in order to extract |
|
109 substrings that have been matched so far, in the same way as for extracting |
|
110 substrings after a match has completed. For <b>pcre_dfa_exec()</b> this field is |
|
111 not useful. |
|
112 </P> |
|
113 <P> |
|
114 The <i>subject</i> and <i>subject_length</i> fields contain copies of the values |
|
115 that were passed to <b>pcre_exec()</b>. |
|
116 </P> |
|
117 <P> |
|
118 The <i>start_match</i> field normally contains the offset within the subject at |
|
119 which the current match attempt started. However, if the escape sequence \K |
|
120 has been encountered, this value is changed to reflect the modified starting |
|
121 point. If the pattern is not anchored, the callout function may be called |
|
122 several times from the same point in the pattern for different starting points |
|
123 in the subject. |
|
124 </P> |
|
125 <P> |
|
126 The <i>current_position</i> field contains the offset within the subject of the |
|
127 current match pointer. |
|
128 </P> |
|
129 <P> |
|
130 When the <b>pcre_exec()</b> function is used, the <i>capture_top</i> field |
|
131 contains one more than the number of the highest numbered captured substring so |
|
132 far. If no substrings have been captured, the value of <i>capture_top</i> is |
|
133 one. This is always the case when <b>pcre_dfa_exec()</b> is used, because it |
|
134 does not support captured substrings. |
|
135 </P> |
|
136 <P> |
|
137 The <i>capture_last</i> field contains the number of the most recently captured |
|
138 substring. If no substrings have been captured, its value is -1. This is always |
|
139 the case when <b>pcre_dfa_exec()</b> is used. |
|
140 </P> |
|
141 <P> |
|
142 The <i>callout_data</i> field contains a value that is passed to |
|
143 <b>pcre_exec()</b> or <b>pcre_dfa_exec()</b> specifically so that it can be |
|
144 passed back in callouts. It is passed in the <i>pcre_callout</i> field of the |
|
145 <b>pcre_extra</b> data structure. If no such data was passed, the value of |
|
146 <i>callout_data</i> in a <b>pcre_callout</b> block is NULL. There is a |
|
147 description of the <b>pcre_extra</b> structure in the |
|
148 <a href="pcreapi.html"><b>pcreapi</b></a> |
|
149 documentation. |
|
150 </P> |
|
151 <P> |
|
152 The <i>pattern_position</i> field is present from version 1 of the |
|
153 <i>pcre_callout</i> structure. It contains the offset to the next item to be |
|
154 matched in the pattern string. |
|
155 </P> |
|
156 <P> |
|
157 The <i>next_item_length</i> field is present from version 1 of the |
|
158 <i>pcre_callout</i> structure. It contains the length of the next item to be |
|
159 matched in the pattern string. When the callout immediately precedes an |
|
160 alternation bar, a closing parenthesis, or the end of the pattern, the length |
|
161 is zero. When the callout precedes an opening parenthesis, the length is that |
|
162 of the entire subpattern. |
|
163 </P> |
|
164 <P> |
|
165 The <i>pattern_position</i> and <i>next_item_length</i> fields are intended to |
|
166 help in distinguishing between different automatic callouts, which all have the |
|
167 same callout number. However, they are set for all callouts. |
|
168 </P> |
|
169 <br><a name="SEC4" href="#TOC1">RETURN VALUES</a><br> |
|
170 <P> |
|
171 The external callout function returns an integer to PCRE. If the value is zero, |
|
172 matching proceeds as normal. If the value is greater than zero, matching fails |
|
173 at the current point, but the testing of other matching possibilities goes |
|
174 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>) |
|
176 returns the negative value. |
|
177 </P> |
|
178 <P> |
|
179 Negative values should normally be chosen from the set of PCRE_ERROR_xxx |
|
180 values. In particular, PCRE_ERROR_NOMATCH forces a standard "no match" failure. |
|
181 The error number PCRE_ERROR_CALLOUT is reserved for use by callout functions; |
|
182 it will never be used by PCRE itself. |
|
183 </P> |
|
184 <br><a name="SEC5" href="#TOC1">AUTHOR</a><br> |
|
185 <P> |
|
186 Philip Hazel |
|
187 <br> |
|
188 University Computing Service |
|
189 <br> |
|
190 Cambridge CB2 3QH, England. |
|
191 <br> |
|
192 </P> |
|
193 <br><a name="SEC6" href="#TOC1">REVISION</a><br> |
|
194 <P> |
|
195 Last updated: 29 May 2007 |
|
196 <br> |
|
197 Copyright © 1997-2007 University of Cambridge. |
|
198 <br> |
|
199 <p> |
|
200 Return to the <a href="index.html">PCRE index page</a>. |
|
201 </p> |