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

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

Parent Directory | Revision Log | View Patch Patch

-revision 75 by nigel,
Sat Feb 24 21:40:37 2007 UTC
+revision 172 by ph10,
Tue Jun  5 10:40:13 2007 UTC
 Line 17 
 man page, in case the conversion went wr
  <li><a name="TOC2" href="#SEC2">MISSING CALLOUTS</a>
  <li><a name="TOC3" href="#SEC3">THE CALLOUT INTERFACE</a>
  <li><a name="TOC4" href="#SEC4">RETURN VALUES</a>
+ <li><a name="TOC5" href="#SEC5">AUTHOR</a>
+ <li><a name="TOC6" href="#SEC6">REVISION</a>
  </ul>
  <br><a name="SEC1" href="#TOC1">PCRE CALLOUTS</a><br>
  <P>
-Line 35 
 function is to be called. Different call
+Line 37 
 function is to be called. Different call
  a number less than 256 after the letter C. The default value is zero.
  For example, this pattern has two callout points:
  <pre>
-   (?C1)\deabc(?C2)def
+   (?C1)abc(?C2)def
  </pre>
  If the PCRE_AUTO_CALLOUT option bit is set when <b>pcre_compile()</b> is called,
  PCRE automatically inserts callouts, all with number 255, before each item in
-Line 72 
 no match, the callout is obeyed.
+Line 74 
 no match, the callout is obeyed.
  <br><a name="SEC3" href="#TOC1">THE CALLOUT INTERFACE</a><br>
  <P>
  During matching, when PCRE reaches a callout point, the external function
- 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
- 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
- fields:
+ only argument to the callout function is a pointer to a <b>pcre_callout</b>
+ block. This structure contains the following fields:
  <pre>
    int          <i>version</i>;
    int          <i>callout_number</i>;
-Line 101 
 automatically generated callouts).
+Line 104 
 automatically generated callouts).
  </P>
  <P>
  The <i>offset_vector</i> field is a pointer to the vector of offsets that was
- 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
- 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
- for extracting substrings after a match has completed.
+ substrings that have been matched so far, in the same way as for extracting
+ substrings after a match has completed. For <b>pcre_dfa_exec()</b> this field is
+ not useful.
  </P>
  <P>
  The <i>subject</i> and <i>subject_length</i> fields contain copies of the values
  that were passed to <b>pcre_exec()</b>.
  </P>
  <P>
- The <i>start_match</i> field contains the offset within the subject at which the
+ The <i>start_match</i> field normally contains the offset within the subject at
- current match attempt started. If the pattern is not anchored, the callout
+ which the current match attempt started. However, if the escape sequence \K
- function may be called several times from the same point in the pattern for
+ has been encountered, this value is changed to reflect the modified starting
- different starting points in the subject.
+ point. If the pattern is not anchored, the callout function may be called
+ several times from the same point in the pattern for different starting points
+ in the subject.
  </P>
  <P>
  The <i>current_position</i> field contains the offset within the subject of the
  current match pointer.
  </P>
  <P>
- 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
- numbered captured substring so far. If no substrings have been captured,
+ contains one more than the number of the highest numbered captured substring so
- the value of <i>capture_top</i> is one.
+ far. If no substrings have been captured, the value of <i>capture_top</i> is
+ one. This is always the case when <b>pcre_dfa_exec()</b> is used, because it
+ does not support captured substrings.
  </P>
  <P>
  The <i>capture_last</i> field contains the number of the most recently captured
- 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
+ the case when <b>pcre_dfa_exec()</b> is used.
  </P>
  <P>
  The <i>callout_data</i> field contains a value that is passed to
- <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
- 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
- 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
- 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
- <b>pcre_extra</b> structure in the
+ description of the <b>pcre_extra</b> structure in the
  <a href="pcreapi.html"><b>pcreapi</b></a>
  documentation.
  </P>
-Line 160 
 same callout number. However, they are s
+Line 170 
 same callout number. However, they are s
  <P>
  The external callout function returns an integer to PCRE. If the value is zero,
  matching proceeds as normal. If the value is greater than zero, matching fails
- at the current point, but backtracking to test other matching possibilities
+ at the current point, but the testing of other matching possibilities goes
- 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
- 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>)
- value.
+ returns the negative value.
  </P>
  <P>
  Negative values should normally be chosen from the set of PCRE_ERROR_xxx
-Line 171 
 values. In particular, PCRE_ERROR_NOMATC
+Line 181 
 values. In particular, PCRE_ERROR_NOMATC
  The error number PCRE_ERROR_CALLOUT is reserved for use by callout functions;
  it will never be used by PCRE itself.
  </P>
+ <br><a name="SEC5" href="#TOC1">AUTHOR</a><br>
  <P>
- Last updated: 09 September 2004
+ Philip Hazel
+ <br>
+ University Computing Service
+ <br>
+ Cambridge CB2 3QH, England.
+ <br>
+ </P>
+ <br><a name="SEC6" href="#TOC1">REVISION</a><br>
+ <P>
+ Last updated: 29 May 2007
+ <br>
+ Copyright &copy; 1997-2007 University of Cambridge.
  <br>
- Copyright &copy; 1997-2004 University of Cambridge.
  <p>
  Return to the <a href="index.html">PCRE index page</a>.
  </p>

 Legend:



Removed from v.75
 


changed lines


 
Added in v.172
 Legend:



Removed from v.75
 


changed lines


 
Added in v.172
-Removed from v.75
+Added in v.172

	ViewVC Help
Powered by ViewVC 1.1.5