--- code/trunk/doc/html/pcrecallout.html 2007/02/24 21:40:37 75 +++ code/trunk/doc/html/pcrecallout.html 2007/03/08 16:53:09 111 @@ -17,6 +17,8 @@
  • MISSING CALLOUTS
  • THE CALLOUT INTERFACE
  • RETURN VALUES +
  • AUTHOR +
  • REVISION
    PCRE CALLOUTS

    @@ -72,9 +74,10 @@
    THE CALLOUT INTERFACE

    During matching, when PCRE reaches a callout point, the external function -defined by pcre_callout is called (if it is set). The only argument is a -pointer to a pcre_callout block. This structure contains the following -fields: +defined by pcre_callout is called (if it is set). This applies to both +the pcre_exec() and the pcre_dfa_exec() matching functions. The +only argument to the callout function is a pointer to a pcre_callout +block. This structure contains the following fields:

       int          version;
       int          callout_number;
    @@ -101,9 +104,11 @@
     

    The offset_vector field is a pointer to the vector of offsets that was -passed by the caller to pcre_exec(). The contents can be inspected in -order to extract substrings that have been matched so far, in the same way as -for extracting substrings after a match has completed. +passed by the caller to pcre_exec() or pcre_dfa_exec(). When +pcre_exec() is used, the contents can be inspected in order to extract +substrings that have been matched so far, in the same way as for extracting +substrings after a match has completed. For pcre_dfa_exec() this field is +not useful.

    The subject and subject_length fields contain copies of the values @@ -120,21 +125,24 @@ current match pointer.

    -The capture_top field contains one more than the number of the highest -numbered captured substring so far. If no substrings have been captured, -the value of capture_top is one. +When the pcre_exec() function is used, the capture_top field +contains one more than the number of the highest numbered captured substring so +far. If no substrings have been captured, the value of capture_top is +one. This is always the case when pcre_dfa_exec() is used, because it +does not support captured substrings.

    The capture_last 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 pcre_dfa_exec() is used.

    The callout_data field contains a value that is passed to -pcre_exec() by the caller specifically so that it can be passed back in -callouts. It is passed in the pcre_callout field of the pcre_extra -data structure. If no such data was passed, the value of callout_data in -a pcre_callout block is NULL. There is a description of the -pcre_extra structure in the +pcre_exec() or pcre_dfa_exec() specifically so that it can be +passed back in callouts. It is passed in the pcre_callout field of the +pcre_extra data structure. If no such data was passed, the value of +callout_data in a pcre_callout block is NULL. There is a +description of the pcre_extra structure in the pcreapi documentation.

    @@ -160,10 +168,10 @@

    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 -goes ahead, just as if a lookahead assertion had failed. If the value is less -than zero, the match is abandoned, and pcre_exec() returns the negative -value. +at the current point, but the testing of other matching possibilities goes +ahead, just as if a lookahead assertion had failed. If the value is less than +zero, the match is abandoned, and pcre_exec() (or pcre_dfa_exec()) +returns the negative value.

    Negative values should normally be chosen from the set of PCRE_ERROR_xxx @@ -171,10 +179,21 @@ The error number PCRE_ERROR_CALLOUT is reserved for use by callout functions; it will never be used by PCRE itself.

    +
    AUTHOR

    -Last updated: 09 September 2004 +Philip Hazel +
    +University Computing Service +
    +Cambridge CB2 3QH, England. +
    +

    +
    REVISION
    +

    +Last updated: 06 March 2007 +
    +Copyright © 1997-2007 University of Cambridge.
    -Copyright © 1997-2004 University of Cambridge.

    Return to the PCRE index page.