Documentation for callouts with string arguments.

git-svn-id: svn://vcs.exim.org/pcre2/code/trunk@226 6239d852-aaf2-0410-a92c-79f79f948069

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