Perl has a feature whereby using the sequence (?{...}) causes
arbitrary Perl code to be obeyed in the middle of matching a
regular expression. This makes it possible, amongst other things,
to extract different substrings that match the same pair of
parentheses when there is a repetition.
PCRE provides a similar feature, but of course it cannot obey
arbitrary Perl code. The feature is called "callout". The caller
of PCRE provides an external function by putting its entry point
in the global variable pcre_callout (8-bit library) or
pcre[16|32]_callout (16-bit or 32-bit library). By default, this
variable contains NULL, which disables all calling out.
Within a regular expression, (?C) indicates the points at which
the external function is to be called. If you want to identify
different callout points, you can put a number less than 256
after the letter C. The default value is zero. For example, this
pattern has two callout points:
(?C1)abc(?C2)def
If the PCRE_AUTO_CALLOUT flag is passed to a compiling function,
callouts are automatically installed before each item in the
pattern. They are all numbered 255. If there is a conditional
group in the pattern whose condition is an assertion, an
additional callout is inserted just before the condition. An
explicit callout may also be set at this position, as in this
example:
(?(?C9)(?=a)abc|def)
Note that this applies only to assertion conditions, not to other
types of condition.
During matching, when PCRE reaches a callout point, the external
function is called. It is provided with the number of the
callout, the position in the pattern, and, optionally, one item
of data originally supplied by the caller of the matching
function. The callout function may cause matching to proceed, to
backtrack, or to fail altogether.
By default, PCRE implements a number of optimizations at compile
time and matching time, and one side-effect is that sometimes
callouts are skipped. If you need all possible callouts to
happen, you need to set options that disable the relevant
optimizations. More details, and a complete description of the
interface to the callout function, are given in the pcrecallout
documentation.
