pcre2grep: add $& as an alias for $0 (#519)

Perl does not use $0 anymore to refer to the text of the matched subject
and `pcre2_substitute()` was recently updated to also provide that value
using the variable Perl prefers: `$&`.

In a similar context, either as part of the formatted output from a match
or during the processing of a callback, teach pcre2grep to also populate
$&.

While at it, update the ChangeLog with recent changes.

NEWS

@@ -52,7 +52,7 @@ a list). Those that are not bugfixes or code tidies are:
   matches the "fullwidth" versions of hex digits. PCRE2_EXTRA_ASCII_DIGIT can
   be used to keep it ASCII only.
 
-* Make PCRE2_UCP the default in UTF mode in pcre2grep and add -no_ucp,
+* Make PCRE2_UCP the default in UTF mode in pcre2grep and add --no-ucp,
   --case-restrict and --posix-digit.
 
 * Add --group-separator and --no-group-separator to pcre2grep.

RunGrepTest

@@ -637,6 +637,8 @@ echo "RC=$?" >>testtrygrep
 echo "---------------------------- Test 120 ------------------------------" >>testtrygrep
 (cd $srcdir; $valgrind $vjs $pcre2grep -HO '$0:$2$1$3' '(\w+) binary (\w+)(\.)?' ./testdata/grepinput) >>testtrygrep
 echo "RC=$?" >>testtrygrep
+(cd $srcdir; $valgrind $vjs $pcre2grep -HO '$&:$2$1$3' '(\w+) binary (\w+)(\.)?' ./testdata/grepinput) >>testtrygrep
+echo "RC=$?" >>testtrygrep
 (cd $srcdir; $valgrind $vjs $pcre2grep -m 1 -O '$0:$a$b$e$f$r$t$v' '(\w+) binary (\w+)(\.)?' ./testdata/grepinput) >>testtrygrep
 echo "RC=$?" >>testtrygrep
 (cd $srcdir; $valgrind $vjs $pcre2grep -HO '${X}' '(\w+) binary (\w+)(\.)?' ./testdata/grepinput) >>testtrygrep 2>&1

doc/html/pcre2api.html

@@ -4082,7 +4082,7 @@ <h1>pcre2api man page</h1>
 </PRE>
 </P>
 <P>
-The default case transformations applied by PCRE2 are reasonably complete, and, 
+The default case transformations applied by PCRE2 are reasonably complete, and,
 in UTF or UCP mode, perform the basic locale-invariant case transformations as
 specified by Unicode. This is suitable for the internal (invisible)
 case-equivalence procedures used during pattern matching, but an application

doc/html/pcre2grep.html

@@ -724,9 +724,9 @@ <h1>pcre2grep man page</h1>
 <br>
 <br>
 $&#60;digits&#62; or ${&#60;digits&#62;} is replaced by the captured substring of the given
-decimal number; zero substitutes the whole match. If the number is greater than
-the number of capturing substrings, or if the capture is unset, the replacement
-is empty.
+decimal number; $& (or the legacy $0) substitutes the whole match. If the
+number is greater than the number of capturing substrings, or if the capture
+is unset, the replacement is empty.
 <br>
 <br>
 $a is replaced by bell; $b by backspace; $e by escape; $f by form feed; $n by
@@ -1025,9 +1025,9 @@ <h1>pcre2grep man page</h1>
 zero-terminated string, which means it should not contain any internal binary
 zeros. It is written to the output, having first been passed through the same
 escape processing as text from the <b>--output</b> (<b>-O</b>) option (see
-above). However, $0 cannot be used to insert a matched substring because the
-match is still in progress. Instead, the single character '0' is inserted. Any
-syntax errors in the string (for example, a dollar not followed by another
+above). However, $0 or $& cannot be used to insert a matched substring because
+the match is still in progress. Instead, the single character '0' is inserted.
+Any syntax errors in the string (for example, a dollar not followed by another
 character) causes the callout to be ignored. No terminator is added to the
 output string, so if you want a newline, you must include it explicitly using
 the escape $n. For example:
@@ -1057,9 +1057,9 @@ <h1>pcre2grep man page</h1>
 </pre>
 Any substring (including the executable name) may contain escape sequences
 started by a dollar character. These are the same as for the <b>--output</b>
-(<b>-O</b>) option documented above, except that $0 cannot insert the matched
-string because the match is still in progress. Instead, the character '0'
-is inserted. If you need a literal dollar or pipe character in any
+(<b>-O</b>) option documented above, except that $0 or $& cannot insert the
+matched string because the match is still in progress. Instead, the character
+'0' is inserted. If you need a literal dollar or pipe character in any
 substring, use $$ or $| respectively. Here is an example:
 <pre>
   echo -e "abcde\n12345" | pcre2grep \

doc/pcre2.txt

@@ -188,8 +188,8 @@ REVISION
 
 PCRE2 10.38                     27 August 2021                        PCRE2(3)
 ------------------------------------------------------------------------------
- 
- 
+
+
 PCRE2API(3)                Library Functions Manual                PCRE2API(3)
 
 
@@ -4209,8 +4209,8 @@ REVISION
 
 PCRE2 10.45                     04 October 2024                    PCRE2API(3)
 ------------------------------------------------------------------------------
- 
- 
+
+
 PCRE2BUILD(3)              Library Functions Manual              PCRE2BUILD(3)
 
 
@@ -4835,8 +4835,8 @@ REVISION
 
 PCRE2 10.44                      15 April 2024                   PCRE2BUILD(3)
 ------------------------------------------------------------------------------
- 
- 
+
+
 PCRE2CALLOUT(3)            Library Functions Manual            PCRE2CALLOUT(3)
 
 
@@ -5268,8 +5268,8 @@ REVISION
 
 PCRE2 10.43                     19 January 2024                PCRE2CALLOUT(3)
 ------------------------------------------------------------------------------
- 
- 
+
+
 PCRE2COMPAT(3)             Library Functions Manual             PCRE2COMPAT(3)
 
 
@@ -5522,8 +5522,8 @@ REVISION
 
 PCRE2 10.45                    01 September 2024                PCRE2COMPAT(3)
 ------------------------------------------------------------------------------
- 
- 
+
+
 PCRE2JIT(3)                Library Functions Manual                PCRE2JIT(3)
 
 
@@ -5977,8 +5977,8 @@ REVISION
 
 PCRE2 10.45                      23 July 2024                      PCRE2JIT(3)
 ------------------------------------------------------------------------------
- 
- 
+
+
 PCRE2LIMITS(3)             Library Functions Manual             PCRE2LIMITS(3)
 
 
@@ -6060,8 +6060,8 @@ REVISION
 
 PCRE2 10.43                      1 August 2023                  PCRE2LIMITS(3)
 ------------------------------------------------------------------------------
- 
- 
+
+
 PCRE2MATCHING(3)           Library Functions Manual           PCRE2MATCHING(3)
 
 
@@ -6293,8 +6293,8 @@ REVISION
 
 PCRE2 10.45                     30 August 2024                PCRE2MATCHING(3)
 ------------------------------------------------------------------------------
- 
- 
+
+
 PCRE2PARTIAL(3)            Library Functions Manual            PCRE2PARTIAL(3)
 
 
@@ -6676,8 +6676,8 @@ REVISION
 
 PCRE2 10.34                    04 September 2019               PCRE2PARTIAL(3)
 ------------------------------------------------------------------------------
- 
- 
+
+
 PCRE2PATTERN(3)            Library Functions Manual            PCRE2PATTERN(3)
 
 
@@ -10368,8 +10368,8 @@ REVISION
 
 PCRE2 10.45                    21 Sepbember 2024               PCRE2PATTERN(3)
 ------------------------------------------------------------------------------
- 
- 
+
+
 PCRE2PERFORM(3)            Library Functions Manual            PCRE2PERFORM(3)
 
 
@@ -10623,8 +10623,8 @@ REVISION
 
 PCRE2 10.41                      27 July 2022                  PCRE2PERFORM(3)
 ------------------------------------------------------------------------------
- 
- 
+
+
 PCRE2POSIX(3)              Library Functions Manual              PCRE2POSIX(3)
 
 
@@ -10981,8 +10981,8 @@ REVISION
 
 PCRE2 10.43                     19 January 2024                  PCRE2POSIX(3)
 ------------------------------------------------------------------------------
- 
- 
+
+
 PCRE2SAMPLE(3)             Library Functions Manual             PCRE2SAMPLE(3)
 
 
@@ -11265,8 +11265,8 @@ REVISION
 
 PCRE2 10.32                      27 June 2018                PCRE2SERIALIZE(3)
 ------------------------------------------------------------------------------
- 
- 
+
+
 PCRE2SYNTAX(3)             Library Functions Manual             PCRE2SYNTAX(3)
 
 
@@ -11923,8 +11923,8 @@ REVISION
 
 PCRE2 10.45                    24 September 2024                PCRE2SYNTAX(3)
 ------------------------------------------------------------------------------
- 
- 
+
+
 PCRE2UNICODE(3)            Library Functions Manual            PCRE2UNICODE(3)
 
 
@@ -12393,5 +12393,5 @@ REVISION
 
 PCRE2 10.45                      22 July 2024                  PCRE2UNICODE(3)
 ------------------------------------------------------------------------------
- 
- 
+
+

doc/pcre2api.3

@@ -4064,7 +4064,7 @@ processing a substitution such as:
 .sp
     pcre2_substitute(..., "\e\eU$1", ...)
 .P
-The default case transformations applied by PCRE2 are reasonably complete, and, 
+The default case transformations applied by PCRE2 are reasonably complete, and,
 in UTF or UCP mode, perform the basic locale-invariant case transformations as
 specified by Unicode. This is suitable for the internal (invisible)
 case-equivalence procedures used during pattern matching, but an application

doc/pcre2demo.3

@@ -1,4 +1,4 @@
-.TH PCRE2DEMO 3 " 4 October 2024" "PCRE2 10.44"
+.TH PCRE2DEMO 3 " 8 October 2024" "PCRE2 10.44"
 .\"AUTOMATICALLY GENERATED BY PrepareRelease - do not EDIT!
 .SH NAME
 PCRE2DEMO - A demonstration C program for PCRE2

doc/pcre2grep.1

@@ -629,9 +629,9 @@ contents of the matched part of the line and/or captured substrings into the
 text.
 .sp
 $<digits> or ${<digits>} is replaced by the captured substring of the given
-decimal number; zero substitutes the whole match. If the number is greater than
-the number of capturing substrings, or if the capture is unset, the replacement
-is empty.
+decimal number; $& (or the legacy $0) substitutes the whole match. If the
+number is greater than the number of capturing substrings, or if the capture
+is unset, the replacement is empty.
 .sp
 $a is replaced by bell; $b by backspace; $e by escape; $f by form feed; $n by
 newline; $r by carriage return; $t by tab; $v by vertical tab.
@@ -914,9 +914,9 @@ available, provided that callouts were not completely disabled when
 zero-terminated string, which means it should not contain any internal binary
 zeros. It is written to the output, having first been passed through the same
 escape processing as text from the \fB--output\fP (\fB-O\fP) option (see
-above). However, $0 cannot be used to insert a matched substring because the
-match is still in progress. Instead, the single character '0' is inserted. Any
-syntax errors in the string (for example, a dollar not followed by another
+above). However, $0 or $& cannot be used to insert a matched substring because
+the match is still in progress. Instead, the single character '0' is inserted.
+Any syntax errors in the string (for example, a dollar not followed by another
 character) causes the callout to be ignored. No terminator is added to the
 output string, so if you want a newline, you must include it explicitly using
 the escape $n. For example:
@@ -945,9 +945,9 @@ arguments:
 .sp
 Any substring (including the executable name) may contain escape sequences
 started by a dollar character. These are the same as for the \fB--output\fP
-(\fB-O\fP) option documented above, except that $0 cannot insert the matched
-string because the match is still in progress. Instead, the character '0'
-is inserted. If you need a literal dollar or pipe character in any
+(\fB-O\fP) option documented above, except that $0 or $& cannot insert the
+matched string because the match is still in progress. Instead, the character
+'0' is inserted. If you need a literal dollar or pipe character in any
 substring, use $$ or $| respectively. Here is an example:
 .sp
   echo -e "abcde\en12345" | pcre2grep \e