Callout callback function

PCRE provides a feature called "callout", which is a means of temporarily passing control to the caller of PCRE in the middle of pattern matching. Within a regular expression, (?C) indicates the points at which the external function is to be called. Different callout points can be identified by putting a number less than 256 after the letter C. The default value is zero. For example, this pattern has two callout points:




Types FINDRX (used with findrx) and REPLACERX (used with str.replacerx) have member fcallout. If fcallout is address of user-defined function, that function is called each time a callout is encountered in pattern.


A template is available in menu -> File -> New -> Templates.


The function must begin with:


function[c]# CALLOUT&x


x is variable of type CALLOUT.


type CALLOUT version number CHARRANGE*vec $subject length start_match current_position capture_top capture_last FINDRX*frx []REPLACERX*rrx


version - version number of the type.

number - number of the callout, as compiled into the pattern (that is, the number after ?C).

vec - array of offsets in subject string. The content can be inspected in order to extract substrings that have been matched so far.

subject - subject string ( s in str.replacerx, string in findrx).

length - length of subject string.

start_match - 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 for different starting points.

current_position - offset within the subject of the current match pointer.

capture_top - one more than the number of the highest numbered captured substring so far (that is, vec length). If no substrings have been captured, the value of capture_top is one.

capture_last - number of the most recently captured substring.

rf - address of variable that was passed to findrx.

rr - address of variable that was passed to str.replacerx.


Return values

0 matching proceeds as normal.
> 0 matching fails at the current point, but backtracking to test other possibilities goes ahead, just as if a lookahead assertion had failed.
-1 matching fails (not found).
< -1 generate error with this error number. Should be < -100.