diff options
Diffstat (limited to 'doc/pcre2callout.3')
-rw-r--r-- | doc/pcre2callout.3 | 82 |
1 files changed, 62 insertions, 20 deletions
diff --git a/doc/pcre2callout.3 b/doc/pcre2callout.3 index eeac0d5..a485e1d 100644 --- a/doc/pcre2callout.3 +++ b/doc/pcre2callout.3 @@ -1,4 +1,4 @@ -.TH PCRE2CALLOUT 3 "02 January 2015" "PCRE2 10.00" +.TH PCRE2CALLOUT 3 "15 March 2015" "PCRE2 10.20" .SH NAME PCRE2 - Perl-compatible regular expressions (revised API) .SH SYNOPSIS @@ -15,18 +15,22 @@ PCRE2 - Perl-compatible regular expressions (revised API) PCRE2 provides a feature called "callout", which is a means of temporarily passing control to the caller of PCRE2 in the middle of pattern matching. The caller of PCRE2 provides an external function by putting its entry point in -a match context (see \fBpcre2_set_callout()\fP) in the +a match context (see \fBpcre2_set_callout()\fP in the .\" HREF \fBpcre2api\fP .\" documentation). .P -Within a regular expression, (?C) indicates the points at which the external +Within a regular expression, (?C<arg>) indicates a point 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: +Alternatively, the argument may be a delimited string. The starting delimiter +must be one of ` ' " ^ % # $ { and the ending delimiter is the same as the +start, except for {, where the ending delimiter is }. If the ending delimiter +is needed within the string, it must be doubled. For example, this pattern has +two callout points: .sp - (?C1)abc(?C2)def + (?C1)abc(?C"some ""arbitrary"" text")def .sp If the PCRE2_AUTO_CALLOUT option bit is set when a pattern is compiled, PCRE2 automatically inserts callouts, all with number 255, before each item in the @@ -43,20 +47,19 @@ alternation bar. If the pattern contains a conditional group whose condition is an assertion, an automatic callout is inserted immediately before the condition. Such a callout may also be inserted explicitly, for example: .sp - (?(?C9)(?=a)ab|de) + (?(?C9)(?=a)ab|de) (?(?C%text%)(?!=d)ab|de) .sp This applies only to assertion conditions (because they are themselves independent groups). .P -Automatic callouts can be used for tracking the progress of pattern matching. -The +Callouts can be useful for tracking the progress of pattern matching. The .\" HREF \fBpcre2test\fP .\" -program has a pattern qualifier (/auto_callout) that sets automatic callouts; -when it is used, the output indicates how the pattern is being matched. This is -useful information when you are trying to optimize the performance of a -particular pattern. +program has a pattern qualifier (/auto_callout) that sets automatic callouts. +When any callouts are present, the output from \fBpcre2test\fP indicates how +the pattern is being matched. This is useful information when you are trying to +optimize the performance of a particular pattern. . . .SH "MISSING CALLOUTS" @@ -193,15 +196,52 @@ documentation). The callout block structure contains the following fields: PCRE2_SIZE \fIcurrent_position\fP; PCRE2_SIZE \fIpattern_position\fP; PCRE2_SIZE \fInext_item_length\fP; + PCRE2_SIZE \fIcallout_string_offset\fP; + PCRE2_SPTR \fIcallout_string\fP; + uint32_t \fIcallout_string_length\fP; + .sp The \fIversion\fP field contains the version number of the block format. The -current version is 0. The version number will change in future if additional -fields are added, but the intention is never to remove any of the existing -fields. +current version is 1; the three callout string fields were added for this +version. If you are writing an application that might use an earlier release of +PCRE2, you should check the version number before accessing any of these +fields. The version number will increase in future if more fields are added, +but the intention is never to remove any of the existing fields. +. +. +.SS "Fields for numerical callouts" +.rs +.sp +For a numerical callout, \fIcallout_string\fP is NULL, and \fIcallout_number\fP +contains the number of the callout, in the range 0-255. This is the number +that follows (?C for manual callouts; it is 255 for automatically generated +callouts. +. +. +.SS "Fields for string callouts" +.rs +.sp +For callouts with string arguments, \fIcallout_number\fP is always zero, and +\fIcallout_string\fP points to the string that is contained within the compiled +pattern. Its length is given by \fIcallout_string_length\fP. Duplicated ending +delimiters that were present in the original pattern string have been turned +into single characters. An additional code unit containing binary zero is +present after the string, but is not included in the length. The delimiter that +was used to start the string is also stored within the pattern, immediately +before the string itself. You can therefore access this delimiter as +\fIcallout_string\fP[-1] if you need it. .P -The \fIcallout_number\fP field contains the number of the callout, as compiled -into the pattern (that is, the number after ?C for manual callouts, and 255 for -automatically generated callouts). +The \fIcallout_string_offset\fP field is the code unit offset to the start of +the callout argument string within the original pattern string. This is +provided for the benefit of applications such as script languages that might +need to report errors in the callout string within the pattern. +. +. +.SS "Fields for all callouts" +.rs +.sp +The remaining fields in the callout block are the same for both kinds of +callout. .P The \fIoffset_vector\fP field is a pointer to the vector of capturing offsets (the "ovector") that was passed to the matching function in the match data @@ -246,7 +286,9 @@ of the entire subpattern. .P The \fIpattern_position\fP and \fInext_item_length\fP fields are intended to help in distinguishing between different automatic callouts, which all have the -same callout number. However, they are set for all callouts. +same callout number. However, they are set for all callouts, and are used by +\fBpcre2test\fP to show the next item to be matched when displaying callout +information. .P In callouts from \fBpcre2_match()\fP the \fImark\fP field contains a pointer to the zero-terminated name of the most recently passed (*MARK), (*PRUNE), or @@ -285,6 +327,6 @@ Cambridge, England. .rs .sp .nf -Last updated: 02 January 2015 +Last updated: 15 March 2015 Copyright (c) 1997-2015 University of Cambridge. .fi |