Jason Hood's pcre2grep patches (modified a bit) to add --output to pcre2grep,

and also an inbuilt callout echo.


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

1 files changed, 65 insertions, 20 deletions

diff --git a/doc/pcre2grep.1 b/doc/pcre2grep.1
index a18bffe..b450375 100644
--- a/doc/pcre2grep.1
+++ b/doc/pcre2grep.1
@@ -1,4 +1,4 @@
-.TH PCRE2GREP 1 "31 March 2017" "PCRE2 10.30"
+.TH PCRE2GREP 1 "06 April 2017" "PCRE2 10.30"
 .SH NAME
 pcre2grep - a grep with Perl-compatible regular expressions.
 .SH SYNOPSIS
@@ -330,8 +330,8 @@ Instead of showing lines or parts of lines that match, show each match as an
 offset from the start of the file and a length, separated by a comma. In this
 mode, no context is shown. That is, the \fB-A\fP, \fB-B\fP, and \fB-C\fP
 options are ignored. If there is more than one match in a line, each of them is
-shown separately. This option is mutually exclusive with \fB--line-offsets\fP
-and \fB--only-matching\fP.
+shown separately. This option is mutually exclusive with \fB--output\fP,
+\fB--line-offsets\fP, and \fB--only-matching\fP.
 .TP
 \fB-H\fP, \fB--with-filename\fP
 Force the inclusion of the file name at the start of output lines when
@@ -424,7 +424,8 @@ number is terminated by a colon (as usual; see the \fB-n\fP option), and the
 offset and length are separated by a comma. In this mode, no context is shown.
 That is, the \fB-A\fP, \fB-B\fP, and \fB-C\fP options are ignored. If there is
 more than one match in a line, each of them is shown separately. This option is
-mutually exclusive with \fB--file-offsets\fP and \fB--only-matching\fP.
+mutually exclusive with \fB--output\fP, \fB--file-offsets\fP, and
+\fB--only-matching\fP.
 .TP
 \fB--locale\fP=\fIlocale-name\fP
 This option specifies a locale to be used for pattern matching. It overrides
@@ -521,6 +522,30 @@ was explicitly disabled at build time. This option can be used to disable the
 use of JIT at run time. It is provided for testing and working round problems.
 It should never be needed in normal use.
 .TP
+\fB-O\fP \fItext\fP, \fB--output\fP=\fItext\fP
+When there is a match, instead of outputting the whole line that matched,
+output just the given text. This option is mutually exclusive with
+\fB--only-matching\fP, \fB--file-offsets\fP, and \fB--line-offsets\fP. Escape
+sequences starting with a dollar character may be used to insert the 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.
+.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.
+.sp
+$o<digits> is replaced by the character represented by the given octal
+number; up to three digits are processed.
+.sp
+$x<digits> is replaced by the character represented by the given hexadecimal
+number; up to two digits are processed.
+.sp
+Any other character is substituted by itself. In particular, $$ is replaced by
+a single dollar.
+.TP
 \fB-o\fP, \fB--only-matching\fP
 Show only the part of the line that matched a pattern instead of the whole
 line. In this mode, no context is shown. That is, the \fB-A\fP, \fB-B\fP, and
@@ -530,7 +555,7 @@ combined with \fB-v\fP (invert the sense of the match to find non-matching
 lines), no output is generated, but the return code is set appropriately. If
 the matched portion of the line is empty, nothing is output unless the file
 name or line number are being printed, in which case they are shown on an
-otherwise empty line. This option is mutually exclusive with
+otherwise empty line. This option is mutually exclusive with \fB--output\fP,
 \fB--file-offsets\fP and \fB--line-offsets\fP.
 .TP
 \fB-o\fP\fInumber\fP, \fB--only-matching\fP=\fInumber\fP
@@ -539,7 +564,7 @@ given number. Up to 32 capturing parentheses are supported, and -o0 is
 equivalent to \fB-o\fP without a number. Because these options can be given
 without an argument (see above), if an argument is present, it must be given in
 the same shell item, for example, -o3 or --only-matching=2. The comments given
-for the non-argument case above also apply to this case. If the specified
+for the non-argument case above also apply to this option. If the specified
 capturing parentheses do not exist in the pattern, or were not set in the
 match, nothing is output unless the file name or line number are being output.
 .sp
@@ -647,9 +672,9 @@ as in the GNU \fBgrep\fP program. Any long option of the form
 (PCRE2 terminology). However, the \fB--depth-limit\fP, \fB--file-list\fP,
 \fB--file-offsets\fP, \fB--include-dir\fP, \fB--line-offsets\fP,
 \fB--locale\fP, \fB--match-limit\fP, \fB-M\fP, \fB--multiline\fP, \fB-N\fP,
-\fB--newline\fP, \fB--om-separator\fP, \fB-u\fP, and \fB--utf-8\fP options are
-specific to \fBpcre2grep\fP, as is the use of the \fB--only-matching\fP option
-with a capturing parentheses number.
+\fB--newline\fP, \fB--om-separator\fP, \fB--output\fP, \fB-u\fP, and
+\fB--utf-8\fP options are specific to \fBpcre2grep\fP, as is the use of the
+\fB--only-matching\fP option with a capturing parentheses number.
 .P
 Although most of the common options work the same way, a few are different in
 \fBpcre2grep\fP. For example, the \fB--include\fP option's argument is a glob
@@ -690,25 +715,32 @@ options does have data, it must be given in the first form, using an equals
 character. Otherwise \fBpcre2grep\fP will assume that it has no data.
 .
 .
-.SH "CALLING EXTERNAL SCRIPTS"
+.SH "USING PCRE2'S CALLOUT FACILITY"
 .rs
 .sp
 \fBpcre2grep\fP has, by default, support for calling external programs or
-scripts during matching by making use of PCRE2's callout facility. However,
-this support can be disabled when \fBpcre2grep\fP is built. You can find out
-whether your binary has support for callouts by running it with the \fB--help\fP
-option. If the support is not enabled, all callouts in patterns are ignored by
-\fBpcre2grep\fP.
+scripts or echoing specific strings during matching by making use of PCRE2's
+callout facility. However, this support can be disabled when \fBpcre2grep\fP is
+built. You can find out whether your binary has support for callouts by running
+it with the \fB--help\fP option. If the support is not enabled, all callouts in
+patterns are ignored by \fBpcre2grep\fP.
 .P
 A callout in a PCRE2 pattern is of the form (?C<arg>) where the argument is
 either a number or a quoted string (see the
 .\" HREF
 \fBpcre2callout\fP
 .\"
-documentation for details). Numbered callouts are ignored by \fBpcre2grep\fP.
-String arguments are parsed as a list of substrings separated by pipe (vertical
-bar) characters. The first substring must be an executable name, with the
-following substrings specifying arguments:
+documentation for details). Numbered callouts are ignored by \fBpcre2grep\fP; 
+only callouts with string arguments are useful.
+.
+.
+.SS "Calling external programs or scripts"
+.rs
+.sp
+If the callout string does not start with a pipe (vertical bar) character, it
+is parsed into a list of substrings separated by pipe characters. The first
+substring must be an executable name, with the following substrings specifying
+arguments:
 .sp
   executable_name|arg1|arg2|...
 .sp
@@ -742,6 +774,19 @@ the non-existence of the executable), a local matching failure occurs and the
 matcher backtracks in the normal way.
 .
 .
+.SS "Echoing a specific string"
+.rs
+.sp
+If the callout string starts with a pipe (vertical bar) character, the rest of
+the string is written to the output, having been passed through the same escape
+processing as text from the --output option. This provides a simple echoing
+facility that avoids calling an external program or script. No terminator is 
+added to the string, so if you want a newline, you must include it explicitly.
+Matching continues normally after the string is output. If you want to see only 
+the callout output but not any output from an actual match, you should end the 
+relevant pattern with (*FAIL).
+.
+.
 .SH "MATCHING ERRORS"
 .rs
 .sp
@@ -789,6 +834,6 @@ Cambridge, England.
 .rs
 .sp
 .nf
-Last updated: 31 March 2017
+Last updated: 06 April 2017
 Copyright (c) 1997-2017 University of Cambridge.
 .fi