Revision: 521
http://www.exim.org/viewvc/pcre2?view=rev&revision=521
Author: ph10
Date: 2016-06-05 17:04:38 +0100 (Sun, 05 Jun 2016)
Log Message:
-----------
Fix typo in pcre2grep documentation.
Modified Paths:
--------------
code/trunk/doc/html/pcre2grep.html
code/trunk/doc/pcre2grep.1
code/trunk/doc/pcre2grep.txt
Modified: code/trunk/doc/html/pcre2grep.html
===================================================================
--- code/trunk/doc/html/pcre2grep.html 2016-05-31 11:36:10 UTC (rev 520)
+++ code/trunk/doc/html/pcre2grep.html 2016-06-05 16:04:38 UTC (rev 521)
@@ -22,11 +22,12 @@
<li><a name="TOC7" href="#SEC7">NEWLINES</a>
<li><a name="TOC8" href="#SEC8">OPTIONS COMPATIBILITY</a>
<li><a name="TOC9" href="#SEC9">OPTIONS WITH DATA</a>
-<li><a name="TOC10" href="#SEC10">MATCHING ERRORS</a>
-<li><a name="TOC11" href="#SEC11">DIAGNOSTICS</a>
-<li><a name="TOC12" href="#SEC12">SEE ALSO</a>
-<li><a name="TOC13" href="#SEC13">AUTHOR</a>
-<li><a name="TOC14" href="#SEC14">REVISION</a>
+<li><a name="TOC10" href="#SEC10">CALLING EXTERNAL SCRIPTS</a>
+<li><a name="TOC11" href="#SEC11">MATCHING ERRORS</a>
+<li><a name="TOC12" href="#SEC12">DIAGNOSTICS</a>
+<li><a name="TOC13" href="#SEC13">SEE ALSO</a>
+<li><a name="TOC14" href="#SEC14">AUTHOR</a>
+<li><a name="TOC15" href="#SEC15">REVISION</a>
</ul>
<br><a name="SEC1" href="#TOC1">SYNOPSIS</a><br>
<P>
@@ -735,8 +736,58 @@
options does have data, it must be given in the first form, using an equals
character. Otherwise <b>pcre2grep</b> will assume that it has no data.
</P>
-<br><a name="SEC10" href="#TOC1">MATCHING ERRORS</a><br>
+<br><a name="SEC10" href="#TOC1">CALLING EXTERNAL SCRIPTS</a><br>
<P>
+On non-Windows systems, <b>pcre2grep</b> 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 <b>pcre2grep</b> is built.
+You can find out whether your binary has support for callouts by running it
+with the <b>--help</b> option. If the support is not enabled, all callouts in
+patterns are ignored by <b>pcre2grep</b>.
+</P>
+<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
+<a href="pcre2callout.html"><b>pcre2callout</b></a>
+documentation for details). Numbered callouts are ignored by <b>pcre2grep</b>.
+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:
+<pre>
+ executable_name|arg1|arg2|...
+</pre>
+Any substring (including the executable name) may contain escape sequences
+started by a dollar character: $<digits> or ${<digits>} is replaced by the
+captured substring of the given decimal number, which must be greater than
+zero. If the number is greater than the number of capturing substrings, or if
+the capture is unset, the replacement is empty.
+</P>
+<P>
+Any other character is substituted by itself. In particular, $$ is replaced by
+a single dollar and $| is replaced by a pipe character. Here is an example:
+<pre>
+ echo -e "abcde\n12345" | pcre2grep \
+ '(?x)(.)(..(.))
+ (?C"/bin/echo|Arg1: [$1] [$2] [$3]|Arg2: $|${1}$| ($4)")()' -
+
+ Output:
+
+ Arg1: [a] [bcd] [d] Arg2: |a| ()
+ abcde
+ Arg1: [1] [234] [4] Arg2: |1| ()
+ 12345
+</pre>
+The parameters for the <b>execv()</b> system call that is used to run the
+program or script are zero-terminated strings. This means that binary zero
+characters in the callout argument will cause premature termination of their
+substrings, and therefore should not be present. Any syntax errors in the
+string (for example, a dollar not followed by another character) cause the
+callout to be ignored. If running the program fails for any reason (including
+the non-existence of the executable), a local matching failure occurs and the
+matcher backtracks in the normal way.
+</P>
+<br><a name="SEC11" href="#TOC1">MATCHING ERRORS</a><br>
+<P>
It is possible to supply a regular expression that takes a very long time to
fail to match certain lines. Such patterns normally involve nested indefinite
repeats, for example: (a+)*\d when matched against a line of a's with no final
@@ -751,7 +802,7 @@
that sets a limit on the amount of memory (usually stack) that is used (see the
discussion of these options above).
</P>
-<br><a name="SEC11" href="#TOC1">DIAGNOSTICS</a><br>
+<br><a name="SEC12" href="#TOC1">DIAGNOSTICS</a><br>
<P>
Exit status is 0 if any matches were found, 1 if no matches were found, and 2
for syntax errors, overlong lines, non-existent or inaccessible files (even if
@@ -759,11 +810,11 @@
<b>-s</b> option to suppress error messages about inaccessible files does not
affect the return code.
</P>
-<br><a name="SEC12" href="#TOC1">SEE ALSO</a><br>
+<br><a name="SEC13" href="#TOC1">SEE ALSO</a><br>
<P>
-<b>pcre2pattern</b>(3), <b>pcre2syntax</b>(3).
+<b>pcre2pattern</b>(3), <b>pcre2syntax</b>(3), <b>pcre2callout</b>(3).
</P>
-<br><a name="SEC13" href="#TOC1">AUTHOR</a><br>
+<br><a name="SEC14" href="#TOC1">AUTHOR</a><br>
<P>
Philip Hazel
<br>
@@ -772,11 +823,11 @@
Cambridge, England.
<br>
</P>
-<br><a name="SEC14" href="#TOC1">REVISION</a><br>
+<br><a name="SEC15" href="#TOC1">REVISION</a><br>
<P>
-Last updated: 03 January 2015
+Last updated: 06 April 2016
<br>
-Copyright © 1997-2015 University of Cambridge.
+Copyright © 1997-2016 University of Cambridge.
<br>
<p>
Return to the <a href="index.html">PCRE2 index page</a>.
Modified: code/trunk/doc/pcre2grep.1
===================================================================
--- code/trunk/doc/pcre2grep.1 2016-05-31 11:36:10 UTC (rev 520)
+++ code/trunk/doc/pcre2grep.1 2016-06-05 16:04:38 UTC (rev 521)
@@ -687,9 +687,9 @@
echo -e "abcde\en12345" | pcre2grep \e
'(?x)(.)(..(.))
(?C"/bin/echo|Arg1: [$1] [$2] [$3]|Arg2: $|${1}$| ($4)")()' -
-
+.sp
Output:
-
+.sp
Arg1: [a] [bcd] [d] Arg2: |a| ()
abcde
Arg1: [1] [234] [4] Arg2: |1| ()
Modified: code/trunk/doc/pcre2grep.txt
===================================================================
--- code/trunk/doc/pcre2grep.txt 2016-05-31 11:36:10 UTC (rev 520)
+++ code/trunk/doc/pcre2grep.txt 2016-06-05 16:04:38 UTC (rev 521)
@@ -725,20 +725,71 @@
equals character. Otherwise pcre2grep will assume that it has no data.
+CALLING EXTERNAL SCRIPTS
+
+ On non-Windows systems, pcre2grep 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 pcre2grep
+ is built. You can find out whether your binary has support for call-
+ outs by running it with the --help option. If the support is not
+ enabled, all callouts in patterns are ignored by pcre2grep.
+
+ A callout in a PCRE2 pattern is of the form (?C<arg>) where the argu-
+ ment is either a number or a quoted string (see the pcre2callout docu-
+ mentation for details). Numbered callouts are ignored by pcre2grep.
+ 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:
+
+ executable_name|arg1|arg2|...
+
+ Any substring (including the executable name) may contain escape
+ sequences started by a dollar character: $<digits> or ${<digits>} is
+ replaced by the captured substring of the given decimal number, which
+ must be greater than zero. If the number is greater than the number of
+ capturing substrings, or if the capture is unset, the replacement is
+ empty.
+
+ Any other character is substituted by itself. In particular, $$ is
+ replaced by a single dollar and $| is replaced by a pipe character.
+ Here is an example:
+
+ echo -e "abcde\n12345" | pcre2grep \
+ '(?x)(.)(..(.))
+ (?C"/bin/echo|Arg1: [$1] [$2] [$3]|Arg2: $|${1}$| ($4)")()' -
+
+ Output:
+
+ Arg1: [a] [bcd] [d] Arg2: |a| ()
+ abcde
+ Arg1: [1] [234] [4] Arg2: |1| ()
+ 12345
+
+ The parameters for the execv() system call that is used to run the pro-
+ gram or script are zero-terminated strings. This means that binary zero
+ characters in the callout argument will cause premature termination of
+ their substrings, and therefore should not be present. Any syntax
+ errors in the string (for example, a dollar not followed by another
+ character) cause the callout to be ignored. If running the program
+ fails for any reason (including the non-existence of the executable), a
+ local matching failure occurs and the matcher backtracks in the normal
+ way.
+
+
MATCHING ERRORS
- It is possible to supply a regular expression that takes a very long
- time to fail to match certain lines. Such patterns normally involve
- nested indefinite repeats, for example: (a+)*\d when matched against a
- line of a's with no final digit. The PCRE2 matching function has a
- resource limit that causes it to abort in these circumstances. If this
- happens, pcre2grep outputs an error message and the line that caused
- the problem to the standard error stream. If there are more than 20
+ It is possible to supply a regular expression that takes a very long
+ time to fail to match certain lines. Such patterns normally involve
+ nested indefinite repeats, for example: (a+)*\d when matched against a
+ line of a's with no final digit. The PCRE2 matching function has a
+ resource limit that causes it to abort in these circumstances. If this
+ happens, pcre2grep outputs an error message and the line that caused
+ the problem to the standard error stream. If there are more than 20
such errors, pcre2grep gives up.
- The --match-limit option of pcre2grep can be used to set the overall
- resource limit; there is a second option called --recursion-limit that
- sets a limit on the amount of memory (usually stack) that is used (see
+ The --match-limit option of pcre2grep can be used to set the overall
+ resource limit; there is a second option called --recursion-limit that
+ sets a limit on the amount of memory (usually stack) that is used (see
the discussion of these options above).
@@ -745,8 +796,8 @@
DIAGNOSTICS
Exit status is 0 if any matches were found, 1 if no matches were found,
- and 2 for syntax errors, overlong lines, non-existent or inaccessible
- files (even if matches were found in other files) or too many matching
+ and 2 for syntax errors, overlong lines, non-existent or inaccessible
+ files (even if matches were found in other files) or too many matching
errors. Using the -s option to suppress error messages about inaccessi-
ble files does not affect the return code.
@@ -753,7 +804,7 @@
SEE ALSO
- pcre2pattern(3), pcre2syntax(3).
+ pcre2pattern(3), pcre2syntax(3), pcre2callout(3).
AUTHOR
@@ -765,5 +816,5 @@
REVISION
- Last updated: 03 January 2015
- Copyright (c) 1997-2015 University of Cambridge.
+ Last updated: 06 April 2016
+ Copyright (c) 1997-2016 University of Cambridge.
