--- code/trunk/doc/html/pcrecallout.html 2007/02/24 21:40:37 75 +++ code/trunk/doc/html/pcrecallout.html 2007/06/05 10:40:13 172 @@ -17,6 +17,8 @@
  • MISSING CALLOUTS
  • THE CALLOUT INTERFACE
  • RETURN VALUES +
  • AUTHOR +
  • REVISION
    PCRE CALLOUTS

    @@ -35,7 +37,7 @@ a number less than 256 after the letter C. The default value is zero. For example, this pattern has two callout points:

    -  (?C1)\deabc(?C2)def
    +  (?C1)abc(?C2)def
     
    If the PCRE_AUTO_CALLOUT option bit is set when pcre_compile() is called, PCRE automatically inserts callouts, all with number 255, before each item in @@ -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,40 +104,47 @@
     

    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 that were passed to pcre_exec().

    -The start_match field contains the offset within the subject at which the -current match attempt started. 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. +The start_match field normally contains the offset within the subject at +which the current match attempt started. However, if the escape sequence \K +has been encountered, this value is changed to reflect the modified starting +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.

    The current_position field contains the offset within the subject of the 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 +170,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 +181,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: 29 May 2007 +
    +Copyright © 1997-2007 University of Cambridge.
    -Copyright © 1997-2004 University of Cambridge.

    Return to the PCRE index page.