Upgrade the as yet unreleased substitute callout facility.

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

1 files changed, 46 insertions, 12 deletions

diff --git a/doc/pcre2test.1 b/doc/pcre2test.1
index 17bebf5..df5431a 100644
--- a/doc/pcre2test.1
+++ b/doc/pcre2test.1
@@ -1,4 +1,4 @@
-.TH PCRE2TEST 1 "21 September 2018" "PCRE 10.33"
+.TH PCRE2TEST 1 "12 November 2018" "PCRE 10.33"
 .SH NAME
 pcre2test - a program for testing Perl-compatible regular expressions.
 .SH SYNOPSIS
@@ -1014,7 +1014,9 @@ process.
       startchar                  show starting character when relevant
       substitute_callout         use substitution callouts 
       substitute_extended        use PCRE2_SUBSTITUTE_EXTENDED
+      substitute_skip=<n>        skip substitution number n 
       substitute_overflow_length use PCRE2_SUBSTITUTE_OVERFLOW_LENGTH
+      substitute_stop=<n>        skip substitution number n and greater
       substitute_unknown_unset   use PCRE2_SUBSTITUTE_UNKNOWN_UNSET
       substitute_unset_empty     use PCRE2_SUBSTITUTE_UNSET_EMPTY
 .sp
@@ -1189,7 +1191,9 @@ pattern.
       startoffset=<n>            same as offset=<n>
       substitute_callout         use substitution callouts 
       substitute_extedded        use PCRE2_SUBSTITUTE_EXTENDED
+      substitute_skip=<n>        skip substitution number n 
       substitute_overflow_length use PCRE2_SUBSTITUTE_OVERFLOW_LENGTH
+      substitute_stop=<n>        skip substitution number n and greater
       substitute_unknown_unset   use PCRE2_SUBSTITUTE_UNKNOWN_UNSET
       substitute_unset_empty     use PCRE2_SUBSTITUTE_UNSET_EMPTY
       zero_terminate             pass the subject as zero-terminated
@@ -1377,16 +1381,6 @@ simple example of a substitution test:
       =abc=abc=\e=global
    2: =xxx=xxx=
 .sp
-If the \fBsubstitute_callout\fP modifier is set, a substitution callout 
-function is set up. When it is called (after each substitution), the offsets in
-the input and output strings are output. For example:
-.sp
-  /abc/g,replace=<$0>,substitute_callout
-      abcdefabcpqr
-  Old 0 3  New 0 5
-  Old 6 9  New 8 13
-   2: <abc>def<abc>pqr
-.sp
 Subject and replacement strings should be kept relatively short (fewer than 256
 characters) for substitution tests, as fixed-size buffers are used. To make it
 easy to test for buffer overflow, if the replacement string starts with a
@@ -1418,6 +1412,46 @@ matching provokes an error return ("bad option value") from
 \fBpcre2_substitute()\fP.
 .
 .
+.SS "Testing substitute callouts"
+.rs
+.sp
+If the \fBsubstitute_callout\fP modifier is set, a substitution callout 
+function is set up. When it is called (after each substitution), details of the
+the input and output strings are output. For example:
+.sp
+  /abc/g,replace=<$0>,substitute_callout
+      abcdefabcpqr
+   1(1) Old 0 3 "abc" New 0 5 "<abc>"
+   2(1) Old 6 9 "abc" New 8 13 "<abc>" 
+   2: <abc>def<abc>pqr
+.sp
+The first number on each callout line is the count of matches. The
+parenthesized number is the number of pairs that are set in the ovector (that
+is, one more than the number of capturing groups that were set). Then are
+listed the offsets of the old substring, its contents, and the same for the
+replacement.
+.P
+By default, the substitution callout function returns zero, which accepts the 
+replacement and causes matching to continue if /g was used. Two further 
+modifiers can be used to test other return values. If \fBsubstitute_skip\fP is 
+set to a value greater than zero the callout function returns +1 for the match 
+of that number, and similarly \fBsubstitute_stop\fP returns -1. These cause the 
+replacement to be rejected, and -1 causes no further matching to take place. If
+either of them are set, \fBsubstitute_callout\fP is assumed. For example:
+.sp
+  /abc/g,replace=<$0>,substitute_skip=1
+      abcdefabcpqr
+   1(1) Old 0 3 "abc" New 0 5 "<abc> SKIPPED"
+   2(1) Old 6 9 "abc" New 6 11 "<abc>"
+   2: abcdef<abc>pqr
+      abcdefabcpqr\e=substitute_stop=1
+   1(1) Old 0 3 "abc" New 0 5 "<abc> STOPPED"
+   1: abcdefabcpqr
+.sp
+If both are set for the same number, stop takes precedence. Only a single skip 
+or stop is supported, which is sufficient for testing that the feature works.
+.
+.
 .SS "Setting the JIT stack size"
 .rs
 .sp
@@ -2022,6 +2056,6 @@ Cambridge, England.
 .rs
 .sp
 .nf
-Last updated: 21 September 2018
+Last updated: 12 November 2018
 Copyright (c) 1997-2018 University of Cambridge.
 .fi