/[pcre]/code/trunk/doc/html/pcrecallout.html
ViewVC logotype

Diff of /code/trunk/doc/html/pcrecallout.html

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 903 by ph10, Sat Jan 21 16:37:17 2012 UTC revision 1298 by ph10, Fri Mar 22 16:13:13 2013 UTC
# Line 13  from the original man page. If there is Line 13  from the original man page. If there is
13  man page, in case the conversion went wrong.  man page, in case the conversion went wrong.
14  <br>  <br>
15  <ul>  <ul>
16  <li><a name="TOC1" href="#SEC1">PCRE CALLOUTS</a>  <li><a name="TOC1" href="#SEC1">SYNOPSIS</a>
17  <li><a name="TOC2" href="#SEC2">MISSING CALLOUTS</a>  <li><a name="TOC2" href="#SEC2">DESCRIPTION</a>
18  <li><a name="TOC3" href="#SEC3">THE CALLOUT INTERFACE</a>  <li><a name="TOC3" href="#SEC3">MISSING CALLOUTS</a>
19  <li><a name="TOC4" href="#SEC4">RETURN VALUES</a>  <li><a name="TOC4" href="#SEC4">THE CALLOUT INTERFACE</a>
20  <li><a name="TOC5" href="#SEC5">AUTHOR</a>  <li><a name="TOC5" href="#SEC5">RETURN VALUES</a>
21  <li><a name="TOC6" href="#SEC6">REVISION</a>  <li><a name="TOC6" href="#SEC6">AUTHOR</a>
22    <li><a name="TOC7" href="#SEC7">REVISION</a>
23  </ul>  </ul>
24  <br><a name="SEC1" href="#TOC1">PCRE CALLOUTS</a><br>  <br><a name="SEC1" href="#TOC1">SYNOPSIS</a><br>
25    <P>
26    <b>#include &#60;pcre.h&#62;</b>
27    </P>
28  <P>  <P>
29  <b>int (*pcre_callout)(pcre_callout_block *);</b>  <b>int (*pcre_callout)(pcre_callout_block *);</b>
30  </P>  </P>
# Line 28  man page, in case the conversion went wr Line 32  man page, in case the conversion went wr
32  <b>int (*pcre16_callout)(pcre16_callout_block *);</b>  <b>int (*pcre16_callout)(pcre16_callout_block *);</b>
33  </P>  </P>
34  <P>  <P>
35    <b>int (*pcre32_callout)(pcre32_callout_block *);</b>
36    </P>
37    <br><a name="SEC2" href="#TOC1">DESCRIPTION</a><br>
38    <P>
39  PCRE provides a feature called "callout", which is a means of temporarily  PCRE provides a feature called "callout", which is a means of temporarily
40  passing control to the caller of PCRE in the middle of pattern matching. The  passing control to the caller of PCRE in the middle of pattern matching. The
41  caller of PCRE provides an external function by putting its entry point in the  caller of PCRE provides an external function by putting its entry point in the
42  global variable <i>pcre_callout</i> (<i>pcre16_callout</i> for the 16-bit  global variable <i>pcre_callout</i> (<i>pcre16_callout</i> for the 16-bit
43  library). By default, this variable contains NULL, which disables all calling  library, <i>pcre32_callout</i> for the 32-bit library). By default, this
44  out.  variable contains NULL, which disables all calling out.
45  </P>  </P>
46  <P>  <P>
47  Within a regular expression, (?C) indicates the points at which the external  Within a regular expression, (?C) indicates the points at which the external
# Line 56  it is processed as if it were Line 64  it is processed as if it were
64  <br>  <br>
65  <br>  <br>
66  Notice that there is a callout before and after each parenthesis and  Notice that there is a callout before and after each parenthesis and
67  alternation bar. Automatic callouts can be used for tracking the progress of  alternation bar. If the pattern contains a conditional group whose condition is
68  pattern matching. The  an assertion, an automatic callout is inserted immediately before the
69    condition. Such a callout may also be inserted explicitly, for example:
70    <pre>
71      (?(?C9)(?=a)ab|de)
72    </pre>
73    This applies only to assertion conditions (because they are themselves
74    independent groups).
75    </P>
76    <P>
77    Automatic callouts can be used for tracking the progress of pattern matching.
78    The
79  <a href="pcretest.html"><b>pcretest</b></a>  <a href="pcretest.html"><b>pcretest</b></a>
80  command has an option that sets automatic callouts; when it is used, the output  command has an option that sets automatic callouts; when it is used, the output
81  indicates how the pattern is matched. This is useful information when you are  indicates how the pattern is matched. This is useful information when you are
82  trying to optimize the performance of a particular pattern.  trying to optimize the performance of a particular pattern.
83  </P>  </P>
84  <P>  <br><a name="SEC3" href="#TOC1">MISSING CALLOUTS</a><br>
 The use of callouts in a pattern makes it ineligible for optimization by the  
 just-in-time compiler. Studying such a pattern with the PCRE_STUDY_JIT_COMPILE  
 option always fails.  
 </P>  
 <br><a name="SEC2" href="#TOC1">MISSING CALLOUTS</a><br>  
85  <P>  <P>
86  You should be aware that, because of optimizations in the way PCRE matches  You should be aware that, because of optimizations in the way PCRE matches
87  patterns by default, callouts sometimes do not happen. For example, if the  patterns by default, callouts sometimes do not happen. For example, if the
# Line 93  option to the matching function, or by s Line 106  option to the matching function, or by s
106  (*NO_START_OPT). This slows down the matching process, but does ensure that  (*NO_START_OPT). This slows down the matching process, but does ensure that
107  callouts such as the example above are obeyed.  callouts such as the example above are obeyed.
108  </P>  </P>
109  <br><a name="SEC3" href="#TOC1">THE CALLOUT INTERFACE</a><br>  <br><a name="SEC4" href="#TOC1">THE CALLOUT INTERFACE</a><br>
110  <P>  <P>
111  During matching, when PCRE reaches a callout point, the external function  During matching, when PCRE reaches a callout point, the external function
112  defined by <i>pcre_callout</i> or <i>pcre16_callout</i> is called (if it is set).  defined by <i>pcre_callout</i> or <i>pcre[16|32]_callout</i> is called
113  This applies to both normal and DFA matching. The only argument to the callout  (if it is set). This applies to both normal and DFA matching. The only
114  function is a pointer to a <b>pcre_callout</b> or <b>pcre16_callout</b> block.  argument to the callout function is a pointer to a <b>pcre_callout</b>
115    or <b>pcre[16|32]_callout</b> block.
116  These structures contains the following fields:  These structures contains the following fields:
117  <pre>  <pre>
118    int           <i>version</i>;    int           <i>version</i>;
# Line 106  These structures contains the following Line 120  These structures contains the following
120    int          *<i>offset_vector</i>;    int          *<i>offset_vector</i>;
121    const char   *<i>subject</i>;           (8-bit version)    const char   *<i>subject</i>;           (8-bit version)
122    PCRE_SPTR16   <i>subject</i>;           (16-bit version)    PCRE_SPTR16   <i>subject</i>;           (16-bit version)
123      PCRE_SPTR32   <i>subject</i>;           (32-bit version)
124    int           <i>subject_length</i>;    int           <i>subject_length</i>;
125    int           <i>start_match</i>;    int           <i>start_match</i>;
126    int           <i>current_position</i>;    int           <i>current_position</i>;
# Line 116  These structures contains the following Line 131  These structures contains the following
131    int           <i>next_item_length</i>;    int           <i>next_item_length</i>;
132    const unsigned char *<i>mark</i>;       (8-bit version)    const unsigned char *<i>mark</i>;       (8-bit version)
133    const PCRE_UCHAR16  *<i>mark</i>;       (16-bit version)    const PCRE_UCHAR16  *<i>mark</i>;       (16-bit version)
134      const PCRE_UCHAR32  *<i>mark</i>;       (32-bit version)
135  </pre>  </pre>
136  The <i>version</i> field is an integer containing the version number of the  The <i>version</i> field is an integer containing the version number of the
137  block format. The initial version was 0; the current version is 2. The version  block format. The initial version was 0; the current version is 2. The version
# Line 130  automatically generated callouts). Line 146  automatically generated callouts).
146  <P>  <P>
147  The <i>offset_vector</i> field is a pointer to the vector of offsets that was  The <i>offset_vector</i> field is a pointer to the vector of offsets that was
148  passed by the caller to the matching function. When <b>pcre_exec()</b> or  passed by the caller to the matching function. When <b>pcre_exec()</b> or
149  <b>pcre16_exec()</b> is used, the contents can be inspected, in order to extract  <b>pcre[16|32]_exec()</b> is used, the contents can be inspected, in order to
150  substrings that have been matched so far, in the same way as for extracting  extract substrings that have been matched so far, in the same way as for
151  substrings after a match has completed. For the DFA matching functions, this  extracting substrings after a match has completed. For the DFA matching
152  field is not useful.  functions, this field is not useful.
153  </P>  </P>
154  <P>  <P>
155  The <i>subject</i> and <i>subject_length</i> fields contain copies of the values  The <i>subject</i> and <i>subject_length</i> fields contain copies of the values
# Line 152  The <i>current_position</i> field contai Line 168  The <i>current_position</i> field contai
168  current match pointer.  current match pointer.
169  </P>  </P>
170  <P>  <P>
171  When the <b>pcre_exec()</b> or <b>pcre16_exec()</b> is used, the  When the <b>pcre_exec()</b> or <b>pcre[16|32]_exec()</b> is used, the
172  <i>capture_top</i> field contains one more than the number of the highest  <i>capture_top</i> field contains one more than the number of the highest
173  numbered captured substring so far. If no substrings have been captured, the  numbered captured substring so far. If no substrings have been captured, the
174  value of <i>capture_top</i> is one. This is always the case when the DFA  value of <i>capture_top</i> is one. This is always the case when the DFA
# Line 160  functions are used, because they do not Line 176  functions are used, because they do not
176  </P>  </P>
177  <P>  <P>
178  The <i>capture_last</i> field contains the number of the most recently captured  The <i>capture_last</i> field contains the number of the most recently captured
179  substring. If no substrings have been captured, its value is -1. This is always  substring. However, when a recursion exits, the value reverts to what it was
180  the case for the DFA matching functions.  outside the recursion, as do the values of all captured substrings. If no
181    substrings have been captured, the value of <i>capture_last</i> is -1. This is
182    always the case for the DFA matching functions.
183  </P>  </P>
184  <P>  <P>
185  The <i>callout_data</i> field contains a value that is passed to a matching  The <i>callout_data</i> field contains a value that is passed to a matching
186  function specifically so that it can be passed back in callouts. It is passed  function specifically so that it can be passed back in callouts. It is passed
187  in the <i>callout_data</i> field of a <b>pcre_extra</b> or <b>pcre16_extra</b>  in the <i>callout_data</i> field of a <b>pcre_extra</b> or <b>pcre[16|32]_extra</b>
188  data structure. If no such data was passed, the value of <i>callout_data</i> in  data structure. If no such data was passed, the value of <i>callout_data</i> in
189  a callout block is NULL. There is a description of the <b>pcre_extra</b>  a callout block is NULL. There is a description of the <b>pcre_extra</b>
190  structure in the  structure in the
# Line 192  same callout number. However, they are s Line 210  same callout number. However, they are s
210  </P>  </P>
211  <P>  <P>
212  The <i>mark</i> field is present from version 2 of the callout structure. In  The <i>mark</i> field is present from version 2 of the callout structure. In
213  callouts from <b>pcre_exec()</b> or <b>pcre16_exec()</b> it contains a pointer to  callouts from <b>pcre_exec()</b> or <b>pcre[16|32]_exec()</b> it contains a
214  the zero-terminated name of the most recently passed (*MARK), (*PRUNE), or  pointer to the zero-terminated name of the most recently passed (*MARK),
215  (*THEN) item in the match, or NULL if no such items have been passed. Instances  (*PRUNE), or (*THEN) item in the match, or NULL if no such items have been
216  of (*PRUNE) or (*THEN) without a name do not obliterate a previous (*MARK). In  passed. Instances of (*PRUNE) or (*THEN) without a name do not obliterate a
217  callouts from the DFA matching functions this field always contains NULL.  previous (*MARK). In callouts from the DFA matching functions this field always
218    contains NULL.
219  </P>  </P>
220  <br><a name="SEC4" href="#TOC1">RETURN VALUES</a><br>  <br><a name="SEC5" href="#TOC1">RETURN VALUES</a><br>
221  <P>  <P>
222  The external callout function returns an integer to PCRE. If the value is zero,  The external callout function returns an integer to PCRE. If the value is zero,
223  matching proceeds as normal. If the value is greater than zero, matching fails  matching proceeds as normal. If the value is greater than zero, matching fails
# Line 212  values. In particular, PCRE_ERROR_NOMATC Line 231  values. In particular, PCRE_ERROR_NOMATC
231  The error number PCRE_ERROR_CALLOUT is reserved for use by callout functions;  The error number PCRE_ERROR_CALLOUT is reserved for use by callout functions;
232  it will never be used by PCRE itself.  it will never be used by PCRE itself.
233  </P>  </P>
234  <br><a name="SEC5" href="#TOC1">AUTHOR</a><br>  <br><a name="SEC6" href="#TOC1">AUTHOR</a><br>
235  <P>  <P>
236  Philip Hazel  Philip Hazel
237  <br>  <br>
# Line 221  University Computing Service Line 240  University Computing Service
240  Cambridge CB2 3QH, England.  Cambridge CB2 3QH, England.
241  <br>  <br>
242  </P>  </P>
243  <br><a name="SEC6" href="#TOC1">REVISION</a><br>  <br><a name="SEC7" href="#TOC1">REVISION</a><br>
244  <P>  <P>
245  Last updated: 08 Janurary 2012  Last updated: 03 March 2013
246  <br>  <br>
247  Copyright &copy; 1997-2012 University of Cambridge.  Copyright &copy; 1997-2013 University of Cambridge.
248  <br>  <br>
249  <p>  <p>
250  Return to the <a href="index.html">PCRE index page</a>.  Return to the <a href="index.html">PCRE index page</a>.

Legend:
Removed from v.903  
changed lines
  Added in v.1298

  ViewVC Help
Powered by ViewVC 1.1.5