/[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 1193 by ph10, Sat Jan 21 16:37:17 2012 UTC revision 1194 by ph10, Wed Oct 31 17:42:29 2012 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 68  The use of callouts in a pattern makes i Line 76  The use of callouts in a pattern makes i
76  just-in-time compiler. Studying such a pattern with the PCRE_STUDY_JIT_COMPILE  just-in-time compiler. Studying such a pattern with the PCRE_STUDY_JIT_COMPILE
77  option always fails.  option always fails.
78  </P>  </P>
79  <br><a name="SEC2" href="#TOC1">MISSING CALLOUTS</a><br>  <br><a name="SEC3" href="#TOC1">MISSING CALLOUTS</a><br>
80  <P>  <P>
81  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
82  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 101  option to the matching function, or by s
101  (*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
102  callouts such as the example above are obeyed.  callouts such as the example above are obeyed.
103  </P>  </P>
104  <br><a name="SEC3" href="#TOC1">THE CALLOUT INTERFACE</a><br>  <br><a name="SEC4" href="#TOC1">THE CALLOUT INTERFACE</a><br>
105  <P>  <P>
106  During matching, when PCRE reaches a callout point, the external function  During matching, when PCRE reaches a callout point, the external function
107  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
108  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
109  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>
110    or <b>pcre[16|32]_callout</b> block.
111  These structures contains the following fields:  These structures contains the following fields:
112  <pre>  <pre>
113    int           <i>version</i>;    int           <i>version</i>;
# Line 106  These structures contains the following Line 115  These structures contains the following
115    int          *<i>offset_vector</i>;    int          *<i>offset_vector</i>;
116    const char   *<i>subject</i>;           (8-bit version)    const char   *<i>subject</i>;           (8-bit version)
117    PCRE_SPTR16   <i>subject</i>;           (16-bit version)    PCRE_SPTR16   <i>subject</i>;           (16-bit version)
118      PCRE_SPTR32   <i>subject</i>;           (32-bit version)
119    int           <i>subject_length</i>;    int           <i>subject_length</i>;
120    int           <i>start_match</i>;    int           <i>start_match</i>;
121    int           <i>current_position</i>;    int           <i>current_position</i>;
# Line 116  These structures contains the following Line 126  These structures contains the following
126    int           <i>next_item_length</i>;    int           <i>next_item_length</i>;
127    const unsigned char *<i>mark</i>;       (8-bit version)    const unsigned char *<i>mark</i>;       (8-bit version)
128    const PCRE_UCHAR16  *<i>mark</i>;       (16-bit version)    const PCRE_UCHAR16  *<i>mark</i>;       (16-bit version)
129      const PCRE_UCHAR32  *<i>mark</i>;       (32-bit version)
130  </pre>  </pre>
131  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
132  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 141  automatically generated callouts).
141  <P>  <P>
142  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
143  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
144  <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 extract
145  substrings that have been matched so far, in the same way as for extracting  substrings that have been matched so far, in the same way as for extracting
146  substrings after a match has completed. For the DFA matching functions, this  substrings after a match has completed. For the DFA matching functions, this
147  field is not useful.  field is not useful.
# Line 152  The <i>current_position</i> field contai Line 163  The <i>current_position</i> field contai
163  current match pointer.  current match pointer.
164  </P>  </P>
165  <P>  <P>
166  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
167  <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
168  numbered captured substring so far. If no substrings have been captured, the  numbered captured substring so far. If no substrings have been captured, the
169  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 166  the case for the DFA matching functions. Line 177  the case for the DFA matching functions.
177  <P>  <P>
178  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
179  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
180  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>
181  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
182  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>
183  structure in the  structure in the
# Line 192  same callout number. However, they are s Line 203  same callout number. However, they are s
203  </P>  </P>
204  <P>  <P>
205  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
206  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 pointer to
207  the zero-terminated name of the most recently passed (*MARK), (*PRUNE), or  the zero-terminated name of the most recently passed (*MARK), (*PRUNE), or
208  (*THEN) item in the match, or NULL if no such items have been passed. Instances  (*THEN) item in the match, or NULL if no such items have been passed. Instances
209  of (*PRUNE) or (*THEN) without a name do not obliterate a previous (*MARK). In  of (*PRUNE) or (*THEN) without a name do not obliterate a previous (*MARK). In
210  callouts from the DFA matching functions this field always contains NULL.  callouts from the DFA matching functions this field always contains NULL.
211  </P>  </P>
212  <br><a name="SEC4" href="#TOC1">RETURN VALUES</a><br>  <br><a name="SEC5" href="#TOC1">RETURN VALUES</a><br>
213  <P>  <P>
214  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,
215  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 223  values. In particular, PCRE_ERROR_NOMATC
223  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;
224  it will never be used by PCRE itself.  it will never be used by PCRE itself.
225  </P>  </P>
226  <br><a name="SEC5" href="#TOC1">AUTHOR</a><br>  <br><a name="SEC6" href="#TOC1">AUTHOR</a><br>
227  <P>  <P>
228  Philip Hazel  Philip Hazel
229  <br>  <br>
# Line 221  University Computing Service Line 232  University Computing Service
232  Cambridge CB2 3QH, England.  Cambridge CB2 3QH, England.
233  <br>  <br>
234  </P>  </P>
235  <br><a name="SEC6" href="#TOC1">REVISION</a><br>  <br><a name="SEC7" href="#TOC1">REVISION</a><br>
236  <P>  <P>
237  Last updated: 08 Janurary 2012  Last updated: 24 June 2012
238  <br>  <br>
239  Copyright &copy; 1997-2012 University of Cambridge.  Copyright &copy; 1997-2012 University of Cambridge.
240  <br>  <br>

Legend:
Removed from v.1193  
changed lines
  Added in v.1194

  ViewVC Help
Powered by ViewVC 1.1.5