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:
(?C1)\dabc(?C2)def
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.
| 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. |