/[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 75 by nigel, Sat Feb 24 21:40:37 2007 UTC revision 96 by nigel, Fri Mar 2 13:10:43 2007 UTC
# Line 72  no match, the callout is obeyed. Line 72  no match, the callout is obeyed.
72  <br><a name="SEC3" href="#TOC1">THE CALLOUT INTERFACE</a><br>  <br><a name="SEC3" href="#TOC1">THE CALLOUT INTERFACE</a><br>
73  <P>  <P>
74  During matching, when PCRE reaches a callout point, the external function  During matching, when PCRE reaches a callout point, the external function
75  defined by <i>pcre_callout</i> is called (if it is set). The only argument is a  defined by <i>pcre_callout</i> is called (if it is set). This applies to both
76  pointer to a <b>pcre_callout</b> block. This structure contains the following  the <b>pcre_exec()</b> and the <b>pcre_dfa_exec()</b> matching functions. The
77  fields:  only argument to the callout function is a pointer to a <b>pcre_callout</b>
78    block. This structure contains the following fields:
79  <pre>  <pre>
80    int          <i>version</i>;    int          <i>version</i>;
81    int          <i>callout_number</i>;    int          <i>callout_number</i>;
# Line 101  automatically generated callouts). Line 102  automatically generated callouts).
102  </P>  </P>
103  <P>  <P>
104  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
105  passed by the caller to <b>pcre_exec()</b>. The contents can be inspected in  passed by the caller to <b>pcre_exec()</b> or <b>pcre_dfa_exec()</b>. When
106  order to extract substrings that have been matched so far, in the same way as  <b>pcre_exec()</b> is used, the contents can be inspected in order to extract
107  for extracting substrings after a match has completed.  substrings that have been matched so far, in the same way as for extracting
108    substrings after a match has completed. For <b>pcre_dfa_exec()</b> this field is
109    not useful.
110  </P>  </P>
111  <P>  <P>
112  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 120  The <i>current_position</i> field contai Line 123  The <i>current_position</i> field contai
123  current match pointer.  current match pointer.
124  </P>  </P>
125  <P>  <P>
126  The <i>capture_top</i> field contains one more than the number of the highest  When the <b>pcre_exec()</b> function is used, the <i>capture_top</i> field
127  numbered captured substring so far. If no substrings have been captured,  contains one more than the number of the highest numbered captured substring so
128  the value of <i>capture_top</i> is one.  far. If no substrings have been captured, the value of <i>capture_top</i> is
129    one. This is always the case when <b>pcre_dfa_exec()</b> is used, because it
130    does not support captured substrings.
131  </P>  </P>
132  <P>  <P>
133  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
134  substring. If no substrings have been captured, its value is -1.  substring. If no substrings have been captured, its value is -1. This is always
135    the case when <b>pcre_dfa_exec()</b> is used.
136  </P>  </P>
137  <P>  <P>
138  The <i>callout_data</i> field contains a value that is passed to  The <i>callout_data</i> field contains a value that is passed to
139  <b>pcre_exec()</b> by the caller specifically so that it can be passed back in  <b>pcre_exec()</b> or <b>pcre_dfa_exec()</b> specifically so that it can be
140  callouts. It is passed in the <i>pcre_callout</i> field of the <b>pcre_extra</b>  passed back in callouts. It is passed in the <i>pcre_callout</i> field of the
141  data structure. If no such data was passed, the value of <i>callout_data</i> in  <b>pcre_extra</b> data structure. If no such data was passed, the value of
142  a <b>pcre_callout</b> block is NULL. There is a description of the  <i>callout_data</i> in a <b>pcre_callout</b> block is NULL. There is a
143  <b>pcre_extra</b> structure in the  description of the <b>pcre_extra</b> structure in the
144  <a href="pcreapi.html"><b>pcreapi</b></a>  <a href="pcreapi.html"><b>pcreapi</b></a>
145  documentation.  documentation.
146  </P>  </P>
# Line 160  same callout number. However, they are s Line 166  same callout number. However, they are s
166  <P>  <P>
167  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,
168  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
169  at the current point, but backtracking to test other matching possibilities  at the current point, but the testing of other matching possibilities goes
170  goes ahead, just as if a lookahead assertion had failed. If the value is less  ahead, just as if a lookahead assertion had failed. If the value is less than
171  than zero, the match is abandoned, and <b>pcre_exec()</b> returns the negative  zero, the match is abandoned, and <b>pcre_exec()</b> (or <b>pcre_dfa_exec()</b>)
172  value.  returns the negative value.
173  </P>  </P>
174  <P>  <P>
175  Negative values should normally be chosen from the set of PCRE_ERROR_xxx  Negative values should normally be chosen from the set of PCRE_ERROR_xxx
# Line 172  The error number PCRE_ERROR_CALLOUT is r Line 178  The error number PCRE_ERROR_CALLOUT is r
178  it will never be used by PCRE itself.  it will never be used by PCRE itself.
179  </P>  </P>
180  <P>  <P>
181  Last updated: 09 September 2004  Last updated: 28 February 2005
182  <br>  <br>
183  Copyright &copy; 1997-2004 University of Cambridge.  Copyright &copy; 1997-2005 University of Cambridge.
184  <p>  <p>
185  Return to the <a href="index.html">PCRE index page</a>.  Return to the <a href="index.html">PCRE index page</a>.
186  </p>  </p>

Legend:
Removed from v.75  
changed lines
  Added in v.96

  ViewVC Help
Powered by ViewVC 1.1.5