Implement callouts from pcre2_substitute().

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

1 files changed, 43 insertions, 8 deletions

diff --git a/doc/html/pcre2test.html b/doc/html/pcre2test.html
index af2b18c..ebff2c2 100644
--- a/doc/html/pcre2test.html
+++ b/doc/html/pcre2test.html
@@ -1041,6 +1041,7 @@ process.
       aftertext                  show text after match
       allaftertext               show text after captures
       allcaptures                show all captures
+      allvector                  show the entire ovector 
       allusedtext                show all consulted text
       altglobal                  alternative global matching
   /g  global                     global matching
@@ -1048,6 +1049,7 @@ process.
       mark                       show mark values
       replace=<string>           specify a replacement string
       startchar                  show starting character when relevant
+      substitute_callout         use substitution callouts 
       substitute_extended        use PCRE2_SUBSTITUTE_EXTENDED
       substitute_overflow_length use PCRE2_SUBSTITUTE_OVERFLOW_LENGTH
       substitute_unknown_unset   use PCRE2_SUBSTITUTE_UNKNOWN_UNSET
@@ -1185,6 +1187,7 @@ pattern.
       aftertext                  show text after match
       allaftertext               show text after captures
       allcaptures                show all captures
+      allvector                  show the entire ovector 
       allusedtext                show all consulted text (non-JIT only)
       altglobal                  alternative global matching
       callout_capture            show captures at callout time
@@ -1214,6 +1217,7 @@ pattern.
       replace=<string>           specify a replacement string
       startchar                  show startchar when relevant
       startoffset=<n>            same as offset=<n>
+      substitute_callout         use substitution callouts 
       substitute_extedded        use PCRE2_SUBSTITUTE_EXTENDED
       substitute_overflow_length use PCRE2_SUBSTITUTE_OVERFLOW_LENGTH
       substitute_unknown_unset   use PCRE2_SUBSTITUTE_UNKNOWN_UNSET
@@ -1281,10 +1285,28 @@ captured parentheses be output after a match. By default, only those up to the
 highest one actually used in the match are output (corresponding to the return
 code from <b>pcre2_match()</b>). Groups that did not take part in the match
 are output as "&#60;unset&#62;". This modifier is not relevant for DFA matching (which
-does no capturing); it is ignored, with a warning message, if present.
+does no capturing) and does not apply when <b>replace</b> is specified; it is
+ignored, with a warning message, if present.
 </P>
 <br><b>
-Testing callouts
+Showing the entire ovector, for all outcomes
+</b><br>
+<P>
+The <b>allvector</b> modifier requests that the entire ovector be shown,
+whatever the outcome of the match. Compare <b>allcaptures</b>, which shows only
+up to the maximum number of capture groups for the pattern, and then only for a
+successful complete non-DFA match. This modifier, which acts after any match
+result, and also for DFA matching, provides a means of checking that there are
+no unexpected modifications to ovector fields. Before each match attempt, the
+ovector is filled with a special value, and if this is found in both elements
+of a capturing pair, "&#60;unchanged&#62;" is output. After a successful match, this
+applies to all groups after the maximum capture group for the pattern. In other 
+cases it applies to the entire ovector. After a partial match, the first two 
+elements are the only ones that should be set. After a DFA match, the amount of 
+ovector that is used depends on the number of matches that were found.
+</P>
+<br><b>
+Testing pattern callouts
 </b><br>
 <P>
 A callout function is supplied when <b>pcre2test</b> calls the library matching
@@ -1292,6 +1314,9 @@ functions, unless <b>callout_none</b> is specified. Its behaviour can be
 controlled by various modifiers listed above whose names begin with
 <b>callout_</b>. Details are given in the section entitled "Callouts"
 <a href="#callouts">below.</a>
+Testing callouts from <b>pcre2_substitute()</b> is decribed separately in 
+"Testing the substitution function"
+<a href="#substitution">below.</a>
 </P>
 <br><b>
 Finding all matches in a string
@@ -1343,7 +1368,7 @@ instead of a colon. This is in addition to the normal full list. The string
 length (that is, the return from the extraction function) is given in
 parentheses after each substring, followed by the name when the extraction was
 by name.
-</P>
+<a name="substitution"></a></P>
 <br><b>
 Testing the substitution function
 </b><br>
@@ -1384,6 +1409,16 @@ simple example of a substitution test:
       =abc=abc=\=global
    2: =xxx=xxx=
 </pre>
+If the <b>substitute_callout</b> 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:
+<pre>
+  /abc/g,replace=&#60;$0&#62;,substitute_callout
+      abcdefabcpqr
+  Old 0 3  New 0 5
+  Old 6 9  New 8 13
+   2: &#60;abc&#62;def&#60;abc&#62;pqr
+</pre>
 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
@@ -1401,10 +1436,10 @@ The default action of <b>pcre2_substitute()</b> is to return
 PCRE2_ERROR_NOMEMORY when the output buffer is too small. However, if the
 PCRE2_SUBSTITUTE_OVERFLOW_LENGTH option is set (by using the
 <b>substitute_overflow_length</b> modifier), <b>pcre2_substitute()</b> continues
-to go through the motions of matching and substituting, in order to compute the
-size of buffer that is required. When this happens, <b>pcre2test</b> shows the
-required buffer length (which includes space for the trailing zero) as part of
-the error message. For example:
+to go through the motions of matching and substituting (but not doing any
+callouts), in order to compute the size of buffer that is required. When this
+happens, <b>pcre2test</b> shows the required buffer length (which includes space
+for the trailing zero) as part of the error message. For example:
 <pre>
   /abc/substitute_overflow_length
       123abc123\=replace=[9]XYZ
@@ -2004,7 +2039,7 @@ Cambridge, England.
 </P>
 <br><a name="SEC21" href="#TOC1">REVISION</a><br>
 <P>
-Last updated: 21 July 2018
+Last updated: 17 September 2018
 <br>
 Copyright &copy; 1997-2018 University of Cambridge.
 <br>