Implement PCRE2_SUBSTITUTE_LITERAL.

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

8 files changed, 77 insertions, 40 deletions

diff --git a/doc/html/pcre2_substitute.html b/doc/html/pcre2_substitute.html
index 2215ce9..295ca1f 100644
--- a/doc/html/pcre2_substitute.html
+++ b/doc/html/pcre2_substitute.html
@@ -74,10 +74,15 @@ zero-terminated strings. The options are:
                               PCRE2_UTF was set at compile time)
   PCRE2_SUBSTITUTE_EXTENDED  Do extended replacement processing
   PCRE2_SUBSTITUTE_GLOBAL    Replace all occurrences in the subject
+  PCRE2_SUBSTITUTE_LITERAL   The replacement string is literal 
   PCRE2_SUBSTITUTE_OVERFLOW_LENGTH  If overflow, compute needed length
   PCRE2_SUBSTITUTE_UNKNOWN_UNSET  Treat unknown group as unset
   PCRE2_SUBSTITUTE_UNSET_EMPTY  Simple unset insert = empty string
 </pre>
+PCRE2_SUBSTITUTE_LITERAL overrides PCRE2_SUBSTITUTE_EXTENDED, 
+PCRE2_SUBSTITUTE_UNKNOWN_UNSET, and PCRE2_SUBSTITUTE_UNSET_EMPTY.
+</P>
+<P>
 The function returns the number of substitutions, which may be zero if there
 were no matches. The result can be greater than one only when
 PCRE2_SUBSTITUTE_GLOBAL is set. In the event of an error, a negative error code
diff --git a/doc/html/pcre2api.html b/doc/html/pcre2api.html
index 82aabee..585386d 100644
--- a/doc/html/pcre2api.html
+++ b/doc/html/pcre2api.html
@@ -3349,11 +3349,12 @@ of giving an error return as soon as the buffer overflows. Note also that the
 length is in code units, not bytes.
 </P>
 <P>
-In the replacement string, which is interpreted as a UTF string in UTF mode,
-and is checked for UTF validity unless the PCRE2_NO_UTF_CHECK option is set, a
-dollar character is an escape character that can specify the insertion of
-characters from capture groups or names from (*MARK) or other control verbs
-in the pattern. The following forms are always recognized:
+The replacement string, which is interpreted as a UTF string in UTF mode,
+is checked for UTF validity unless the PCRE2_NO_UTF_CHECK option is set. If the
+PCRE2_SUBSTITUTE_LITERAL option is set, it is not interpreted in any way. By
+default, however, a dollar character is an escape character that can specify
+the insertion of characters from capture groups or names from (*MARK) or other
+control verbs in the pattern. The following forms are always recognized:
 <pre>
   $$                  insert a dollar character
   $&#60;n&#62; or ${&#60;n&#62;}      insert the contents of group &#60;n&#62;
@@ -3381,6 +3382,12 @@ As well as the usual options for <b>pcre2_match()</b>, a number of additional
 options can be set in the <i>options</i> argument of <b>pcre2_substitute()</b>.
 </P>
 <P>
+As mentioned above, PCRE2_SUBSTITUTE_LITERAL causes the replacement string to 
+be treated as a literal, with no interpretation. If this option is set, 
+PCRE2_SUBSTITUTE_EXTENDED, PCRE2_SUBSTITUTE_UNKNOWN_UNSET, and 
+PCRE2_SUBSTITUTE_UNSET_EMPTY are irrelevant and are ignored.
+</P>
+<P>
 PCRE2_SUBSTITUTE_GLOBAL causes the function to iterate over the subject string,
 replacing every matching substring. If this option is not set, only the first
 matching substring is replaced. The search for matches takes place in the
@@ -3869,7 +3876,7 @@ Cambridge, England.
 </P>
 <br><a name="SEC42" href="#TOC1">REVISION</a><br>
 <P>
-Last updated: 02 September 2019
+Last updated: 26 December 2019
 <br>
 Copyright &copy; 1997-2019 University of Cambridge.
 <br>
diff --git a/doc/html/pcre2test.html b/doc/html/pcre2test.html
index e387315..c73d360 100644
--- a/doc/html/pcre2test.html
+++ b/doc/html/pcre2test.html
@@ -1063,8 +1063,9 @@ process.
       startchar                  show starting character when relevant
       substitute_callout         use substitution callouts
       substitute_extended        use PCRE2_SUBSTITUTE_EXTENDED
-      substitute_skip=&#60;n&#62;        skip substitution number n
+      substitute_literal         use PCRE2_SUBSTITUTE_LITERAL 
       substitute_overflow_length use PCRE2_SUBSTITUTE_OVERFLOW_LENGTH
+      substitute_skip=&#60;n&#62;        skip substitution number n
       substitute_stop=&#60;n&#62;        skip substitution number n and greater
       substitute_unknown_unset   use PCRE2_SUBSTITUTE_UNKNOWN_UNSET
       substitute_unset_empty     use PCRE2_SUBSTITUTE_UNSET_EMPTY
@@ -1233,8 +1234,9 @@ pattern.
       startoffset=&#60;n&#62;            same as offset=&#60;n&#62;
       substitute_callout         use substitution callouts
       substitute_extedded        use PCRE2_SUBSTITUTE_EXTENDED
-      substitute_skip=&#60;n&#62;        skip substitution number n
+      substitute_literal         use PCRE2_SUBSTITUTE_LITERAL 
       substitute_overflow_length use PCRE2_SUBSTITUTE_OVERFLOW_LENGTH
+      substitute_skip=&#60;n&#62;        skip substitution number n
       substitute_stop=&#60;n&#62;        skip substitution number n and greater
       substitute_unknown_unset   use PCRE2_SUBSTITUTE_UNKNOWN_UNSET
       substitute_unset_empty     use PCRE2_SUBSTITUTE_UNSET_EMPTY
@@ -1413,6 +1415,7 @@ for <b>pcre2_substitute()</b>:
 <pre>
   global                      PCRE2_SUBSTITUTE_GLOBAL
   substitute_extended         PCRE2_SUBSTITUTE_EXTENDED
+  substitute_literal          PCRE2_SUBSTITUTE_LITERAL 
   substitute_overflow_length  PCRE2_SUBSTITUTE_OVERFLOW_LENGTH
   substitute_unknown_unset    PCRE2_SUBSTITUTE_UNKNOWN_UNSET
   substitute_unset_empty      PCRE2_SUBSTITUTE_UNSET_EMPTY
@@ -2093,7 +2096,7 @@ Cambridge, England.
 </P>
 <br><a name="SEC21" href="#TOC1">REVISION</a><br>
 <P>
-Last updated: 30 July 2019
+Last updated: 26 December 2019
 <br>
 Copyright &copy; 1997-2019 University of Cambridge.
 <br>
diff --git a/doc/pcre2.txt b/doc/pcre2.txt
index ed4b4e3..b140f6c 100644
--- a/doc/pcre2.txt
+++ b/doc/pcre2.txt
@@ -3236,38 +3236,44 @@ CREATING A NEW STRING WITH SUBSTITUTIONS
        ing an error return as soon as the buffer overflows. Note also that the
        length is in code units, not bytes.
 
-       In  the replacement string, which is interpreted as a UTF string in UTF
-       mode, and is checked for UTF validity unless the PCRE2_NO_UTF_CHECK op-
-       tion is set, a dollar character is an escape character that can specify
-       the insertion of characters from capture groups or names  from  (*MARK)
-       or  other  control verbs in the pattern. The following forms are always
-       recognized:
+       The  replacement  string,  which  is interpreted as a UTF string in UTF
+       mode, is checked for UTF validity unless the PCRE2_NO_UTF_CHECK  option
+       is set. If the PCRE2_SUBSTITUTE_LITERAL option is set, it is not inter-
+       preted in any way. By default, however, a dollar character is an escape
+       character  that  can  specify  the insertion of characters from capture
+       groups or names from (*MARK) or other control verbs in the pattern. The
+       following forms are always recognized:
 
          $$                  insert a dollar character
          $<n> or ${<n>}      insert the contents of group <n>
          $*MARK or ${*MARK}  insert a control verb name
 
-       Either a group number or a group name  can  be  given  for  <n>.  Curly
-       brackets  are  required only if the following character would be inter-
+       Either  a  group  number  or  a  group name can be given for <n>. Curly
+       brackets are required only if the following character would  be  inter-
        preted as part of the number or name. The number may be zero to include
-       the  entire  matched  string.   For  example,  if  the pattern a(b)c is
-       matched with "=abc=" and the replacement string "+$1$0$1+", the  result
+       the entire matched string.   For  example,  if  the  pattern  a(b)c  is
+       matched  with "=abc=" and the replacement string "+$1$0$1+", the result
        is "=+babcb+=".
 
-       $*MARK  inserts the name from the last encountered backtracking control
-       verb on the matching path that has a name. (*MARK) must always  include
-       a  name,  but  the  other  verbs  need not. For example, in the case of
+       $*MARK inserts the name from the last encountered backtracking  control
+       verb  on the matching path that has a name. (*MARK) must always include
+       a name, but the other verbs need not.  For  example,  in  the  case  of
        (*MARK:A)(*PRUNE) the name inserted is "A", but for (*MARK:A)(*PRUNE:B)
-       the  relevant  name is "B". This facility can be used to perform simple
+       the relevant name is "B". This facility can be used to  perform  simple
        simultaneous substitutions, as this pcre2test example shows:
 
          /(*MARK:pear)apple|(*MARK:orange)lemon/g,replace=${*MARK}
              apple lemon
           2: pear orange
 
-       As well as the usual options for pcre2_match(), a number of  additional
+       As  well as the usual options for pcre2_match(), a number of additional
        options can be set in the options argument of pcre2_substitute().
 
+       As mentioned above,  PCRE2_SUBSTITUTE_LITERAL  causes  the  replacement
+       string  to be treated as a literal, with no interpretation. If this op-
+       tion is set, PCRE2_SUBSTITUTE_EXTENDED, PCRE2_SUBSTITUTE_UNKNOWN_UNSET,
+       and PCRE2_SUBSTITUTE_UNSET_EMPTY are irrelevant and are ignored.
+
        PCRE2_SUBSTITUTE_GLOBAL causes the function to iterate over the subject
        string, replacing every matching substring. If this option is not  set,
        only  the  first matching substring is replaced. The search for matches
@@ -3721,7 +3727,7 @@ AUTHOR
 
 REVISION
 
-       Last updated: 02 September 2019
+       Last updated: 26 December 2019
        Copyright (c) 1997-2019 University of Cambridge.
 ------------------------------------------------------------------------------
  
diff --git a/doc/pcre2_substitute.3 b/doc/pcre2_substitute.3
index 7da668c..4670206 100644
--- a/doc/pcre2_substitute.3
+++ b/doc/pcre2_substitute.3
@@ -1,4 +1,4 @@
-.TH PCRE2_SUBSTITUTE 3 "04 April 2017" "PCRE2 10.30"
+.TH PCRE2_SUBSTITUTE 3 "26 December 2019" "PCRE2 10.35"
 .SH NAME
 PCRE2 - Perl-compatible regular expressions (revised API)
 .SH SYNOPSIS
@@ -66,10 +66,14 @@ zero-terminated strings. The options are:
                               PCRE2_UTF was set at compile time)
   PCRE2_SUBSTITUTE_EXTENDED  Do extended replacement processing
   PCRE2_SUBSTITUTE_GLOBAL    Replace all occurrences in the subject
+  PCRE2_SUBSTITUTE_LITERAL   The replacement string is literal 
   PCRE2_SUBSTITUTE_OVERFLOW_LENGTH  If overflow, compute needed length
   PCRE2_SUBSTITUTE_UNKNOWN_UNSET  Treat unknown group as unset
   PCRE2_SUBSTITUTE_UNSET_EMPTY  Simple unset insert = empty string
 .sp
+PCRE2_SUBSTITUTE_LITERAL overrides PCRE2_SUBSTITUTE_EXTENDED, 
+PCRE2_SUBSTITUTE_UNKNOWN_UNSET, and PCRE2_SUBSTITUTE_UNSET_EMPTY.
+.P
 The function returns the number of substitutions, which may be zero if there
 were no matches. The result can be greater than one only when
 PCRE2_SUBSTITUTE_GLOBAL is set. In the event of an error, a negative error code
diff --git a/doc/pcre2api.3 b/doc/pcre2api.3
index 27e3ef4..424c979 100644
--- a/doc/pcre2api.3
+++ b/doc/pcre2api.3
@@ -1,4 +1,4 @@
-.TH PCRE2API 3 "02 September 2019" "PCRE2 10.34"
+.TH PCRE2API 3 "26 December 2019" "PCRE2 10.35"
 .SH NAME
 PCRE2 - Perl-compatible regular expressions (revised API)
 .sp
@@ -3362,11 +3362,12 @@ space for the trailing zero. Note that in order to compute the required length,
 of giving an error return as soon as the buffer overflows. Note also that the
 length is in code units, not bytes.
 .P
-In the replacement string, which is interpreted as a UTF string in UTF mode,
-and is checked for UTF validity unless the PCRE2_NO_UTF_CHECK option is set, a
-dollar character is an escape character that can specify the insertion of
-characters from capture groups or names from (*MARK) or other control verbs
-in the pattern. The following forms are always recognized:
+The replacement string, which is interpreted as a UTF string in UTF mode,
+is checked for UTF validity unless the PCRE2_NO_UTF_CHECK option is set. If the
+PCRE2_SUBSTITUTE_LITERAL option is set, it is not interpreted in any way. By
+default, however, a dollar character is an escape character that can specify
+the insertion of characters from capture groups or names from (*MARK) or other
+control verbs in the pattern. The following forms are always recognized:
 .sp
   $$                  insert a dollar character
   $<n> or ${<n>}      insert the contents of group <n>
@@ -3392,6 +3393,11 @@ facility can be used to perform simple simultaneous substitutions, as this
 As well as the usual options for \fBpcre2_match()\fP, a number of additional
 options can be set in the \fIoptions\fP argument of \fBpcre2_substitute()\fP.
 .P
+As mentioned above, PCRE2_SUBSTITUTE_LITERAL causes the replacement string to 
+be treated as a literal, with no interpretation. If this option is set, 
+PCRE2_SUBSTITUTE_EXTENDED, PCRE2_SUBSTITUTE_UNKNOWN_UNSET, and 
+PCRE2_SUBSTITUTE_UNSET_EMPTY are irrelevant and are ignored.
+.P
 PCRE2_SUBSTITUTE_GLOBAL causes the function to iterate over the subject string,
 replacing every matching substring. If this option is not set, only the first
 matching substring is replaced. The search for matches takes place in the
@@ -3878,6 +3884,6 @@ Cambridge, England.
 .rs
 .sp
 .nf
-Last updated: 02 September 2019
+Last updated: 26 December 2019
 Copyright (c) 1997-2019 University of Cambridge.
 .fi
diff --git a/doc/pcre2test.1 b/doc/pcre2test.1
index 355dc75..df73e01 100644
--- a/doc/pcre2test.1
+++ b/doc/pcre2test.1
@@ -1,4 +1,4 @@
-.TH PCRE2TEST 1 "30 July 2019" "PCRE 10.34"
+.TH PCRE2TEST 1 "26 December 2019" "PCRE 10.35"
 .SH NAME
 pcre2test - a program for testing Perl-compatible regular expressions.
 .SH SYNOPSIS
@@ -1024,8 +1024,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_literal         use PCRE2_SUBSTITUTE_LITERAL 
       substitute_overflow_length use PCRE2_SUBSTITUTE_OVERFLOW_LENGTH
+      substitute_skip=<n>        skip substitution number n
       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
@@ -1201,8 +1202,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_literal         use PCRE2_SUBSTITUTE_LITERAL 
       substitute_overflow_length use PCRE2_SUBSTITUTE_OVERFLOW_LENGTH
+      substitute_skip=<n>        skip substitution number n
       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
@@ -1381,6 +1383,7 @@ for \fBpcre2_substitute()\fP:
 .sp
   global                      PCRE2_SUBSTITUTE_GLOBAL
   substitute_extended         PCRE2_SUBSTITUTE_EXTENDED
+  substitute_literal          PCRE2_SUBSTITUTE_LITERAL 
   substitute_overflow_length  PCRE2_SUBSTITUTE_OVERFLOW_LENGTH
   substitute_unknown_unset    PCRE2_SUBSTITUTE_UNKNOWN_UNSET
   substitute_unset_empty      PCRE2_SUBSTITUTE_UNSET_EMPTY
@@ -2073,6 +2076,6 @@ Cambridge, England.
 .rs
 .sp
 .nf
-Last updated: 30 July 2019
+Last updated: 26 December 2019
 Copyright (c) 1997-2019 University of Cambridge.
 .fi
diff --git a/doc/pcre2test.txt b/doc/pcre2test.txt
index fcd830f..d388f61 100644
--- a/doc/pcre2test.txt
+++ b/doc/pcre2test.txt
@@ -949,8 +949,9 @@ PATTERN MODIFIERS
              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_literal         use PCRE2_SUBSTITUTE_LITERAL
              substitute_overflow_length use PCRE2_SUBSTITUTE_OVERFLOW_LENGTH
+             substitute_skip=<n>        skip substitution number n
              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
@@ -1103,8 +1104,9 @@ SUBJECT MODIFIERS
              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_literal         use PCRE2_SUBSTITUTE_LITERAL
              substitute_overflow_length use PCRE2_SUBSTITUTE_OVERFLOW_LENGTH
+             substitute_skip=<n>        skip substitution number n
              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
@@ -1265,6 +1267,7 @@ SUBJECT MODIFIERS
 
          global                      PCRE2_SUBSTITUTE_GLOBAL
          substitute_extended         PCRE2_SUBSTITUTE_EXTENDED
+         substitute_literal          PCRE2_SUBSTITUTE_LITERAL
          substitute_overflow_length  PCRE2_SUBSTITUTE_OVERFLOW_LENGTH
          substitute_unknown_unset    PCRE2_SUBSTITUTE_UNKNOWN_UNSET
          substitute_unset_empty      PCRE2_SUBSTITUTE_UNSET_EMPTY
@@ -1902,5 +1905,5 @@ AUTHOR
 
 REVISION
 
-       Last updated: 30 July 2019
+       Last updated: 26 December 2019
        Copyright (c) 1997-2019 University of Cambridge.