Revision: 872
http://www.exim.org/viewvc/pcre2?view=rev&revision=872
Author: ph10
Date: 2017-10-17 17:26:40 +0100 (Tue, 17 Oct 2017)
Log Message:
-----------
Derived documentation update.
Modified Paths:
--------------
code/trunk/doc/html/pcre2_get_mark.html
code/trunk/doc/html/pcre2api.html
code/trunk/doc/html/pcre2grep.html
code/trunk/doc/html/pcre2test.html
code/trunk/doc/pcre2.txt
code/trunk/doc/pcre2grep.txt
Modified: code/trunk/doc/html/pcre2_get_mark.html
===================================================================
--- code/trunk/doc/html/pcre2_get_mark.html 2017-10-17 16:26:20 UTC (rev 871)
+++ code/trunk/doc/html/pcre2_get_mark.html 2017-10-17 16:26:40 UTC (rev 872)
@@ -26,13 +26,17 @@
</b><br>
<P>
After a call of <b>pcre2_match()</b> that was passed the match block that is
-this function's argument, this function returns a pointer to the last (*MARK)
-name that was encountered. The name is zero-terminated, and is within the
-compiled pattern. If no (*MARK) name is available, NULL is returned. A (*MARK)
-name may be available after a failed match or a partial match, as well as after
-a successful one.
+this function's argument, this function returns a pointer to the last (*MARK),
+(*PRUNE), or (*THEN) name that was encountered during the matching process. The
+name is zero-terminated, and is within the compiled pattern. The length of the
+name is in the preceding code unit. If no name is available, NULL is returned.
</P>
<P>
+After a successful match, the name that is returned is the last one on the
+matching path. After a failed match or a partial match, the last encountered
+name is returned.
+</P>
+<P>
There is a complete description of the PCRE2 native API in the
<a href="pcre2api.html"><b>pcre2api</b></a>
page and a description of the POSIX API in the
Modified: code/trunk/doc/html/pcre2api.html
===================================================================
--- code/trunk/doc/html/pcre2api.html 2017-10-17 16:26:20 UTC (rev 871)
+++ code/trunk/doc/html/pcre2api.html 2017-10-17 16:26:40 UTC (rev 872)
@@ -2719,25 +2719,28 @@
</P>
<P>
After a successful match, a partial match (PCRE2_ERROR_PARTIAL), or a failure
-to match (PCRE2_ERROR_NOMATCH), a (*MARK) name may be available, and
-<b>pcre2_get_mark()</b> can be called. It returns a pointer to the
-zero-terminated name, which is within the compiled pattern. Otherwise NULL is
-returned. The length of the (*MARK) name (excluding the terminating zero) is
-stored in the code unit that preceeds the name. You should use this instead of
-relying on the terminating zero if the (*MARK) name might contain a binary
-zero.
+to match (PCRE2_ERROR_NOMATCH), a (*MARK), (*PRUNE), or (*THEN) name may be
+available. The function <b>pcre2_get_mark()</b> can be called to access this
+name. The same function applies to all three verbs. It returns a pointer to the
+zero-terminated name, which is within the compiled pattern. If no name is
+available, NULL is returned. The length of the name (excluding the terminating
+zero) is stored in the code unit that precedes the name. You should use this
+length instead of relying on the terminating zero if the name might contain a
+binary zero.
</P>
<P>
-After a successful match, the (*MARK) name that is returned is the
-last one encountered on the matching path through the pattern. After a "no
-match" or a partial match, the last encountered (*MARK) name is returned. For
-example, consider this pattern:
+After a successful match, the name that is returned is the last (*MARK),
+(*PRUNE), or (*THEN) name encountered on the matching path through the pattern.
+Instances of (*PRUNE) and (*THEN) without names are ignored. Thus, for example,
+if the matching path contains (*MARK:A)(*PRUNE), the name "A" is returned.
+After a "no match" or a partial match, the last encountered name is returned.
+For example, consider this pattern:
<pre>
^(*MARK:A)((*MARK:B)a|b)c
</pre>
-When it matches "bc", the returned mark is A. The B mark is "seen" in the first
+When it matches "bc", the returned name is A. The B mark is "seen" in the first
branch of the group, but it is not on the matching path. On the other hand,
-when this pattern fails to match "bx", the returned mark is B.
+when this pattern fails to match "bx", the returned name is B.
</P>
<P>
After a successful match, a partial match, or one of the invalid UTF errors
@@ -3124,12 +3127,12 @@
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 capturing groups or (*MARK) items in the pattern. The following
-forms are always recognized:
+characters from capturing groups or (*MARK), (*PRUNE), or (*THEN) items in the
+pattern. The following forms are always recognized:
<pre>
$$ insert a dollar character
$<n> or ${<n>} insert the contents of group <n>
- $*MARK or ${*MARK} insert the name of the last (*MARK) encountered
+ $*MARK or ${*MARK} insert a (*MARK), (*PRUNE), or (*THEN) name
</pre>
Either a group number or a group name can be given for <n>. Curly brackets are
required only if the following character would be interpreted as part of the
@@ -3138,15 +3141,19 @@
string "+$1$0$1+", the result is "=+babcb+=".
</P>
<P>
-The facility for inserting a (*MARK) name can be used to perform simple
-simultaneous substitutions, as this <b>pcre2test</b> example shows:
+$*MARK inserts the name from the last encountered (*MARK), (*PRUNE), or (*THEN)
+on the matching path that has a name. (*MARK) must always include a name, but
+(*PRUNE) and (*THEN) 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 simultaneous substitutions, as this
+<b>pcre2test</b> example shows:
<pre>
- /(*:pear)apple|(*:orange)lemon/g,replace=${*MARK}
+ /(*MARK:pear)apple|(*MARK:orange)lemon/g,replace=${*MARK}
apple lemon
2: pear orange
</pre>
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.
+options can be set in the <i>options</i> argument of <b>pcre2_substitute()</b>.
</P>
<P>
PCRE2_SUBSTITUTE_GLOBAL causes the function to iterate over the subject string,
@@ -3560,7 +3567,7 @@
</P>
<br><a name="SEC42" href="#TOC1">REVISION</a><br>
<P>
-Last updated: 25 September 2017
+Last updated: 13 October 2017
<br>
Copyright © 1997-2017 University of Cambridge.
<br>
Modified: code/trunk/doc/html/pcre2grep.html
===================================================================
--- code/trunk/doc/html/pcre2grep.html 2017-10-17 16:26:20 UTC (rev 871)
+++ code/trunk/doc/html/pcre2grep.html 2017-10-17 16:26:40 UTC (rev 872)
@@ -922,6 +922,10 @@
<b>-s</b> option to suppress error messages about inaccessible files does not
affect the return code.
</P>
+<P>
+When run under VMS, the return code is placed in the symbol PCRE2GREP_RC
+because VMS does not distinguish between exit(0) and exit(1).
+</P>
<br><a name="SEC13" href="#TOC1">SEE ALSO</a><br>
<P>
<b>pcre2pattern</b>(3), <b>pcre2syntax</b>(3), <b>pcre2callout</b>(3).
@@ -937,7 +941,7 @@
</P>
<br><a name="SEC15" href="#TOC1">REVISION</a><br>
<P>
-Last updated: 17 June 2017
+Last updated: 11 October 2017
<br>
Copyright © 1997-2017 University of Cambridge.
<br>
Modified: code/trunk/doc/html/pcre2test.html
===================================================================
--- code/trunk/doc/html/pcre2test.html 2017-10-17 16:26:20 UTC (rev 871)
+++ code/trunk/doc/html/pcre2test.html 2017-10-17 16:26:40 UTC (rev 872)
@@ -167,7 +167,8 @@
<b>-C</b>
Output the version number of the PCRE2 library, and all available information
about the optional features that are included, and then exit with zero exit
-code. All other options are ignored.
+code. All other options are ignored. If both -C and -LM are present, whichever
+is first is recognized.
</P>
<P>
<b>-C</b> <i>option</i>
@@ -241,6 +242,12 @@
available, and the use of JIT is verified.
</P>
<P>
+<b>-LM</b>
+List modifiers: write a list of available pattern and subject modifiers to the
+standard output, then exit with zero exit code. All other options are ignored.
+If both -C and -LM are present, whichever is first is recognized.
+</P>
+<P>
\fB-pattern\fB <i>modifier-list</i>
Behave as if each pattern line contains the given modifiers.
</P>
@@ -1020,13 +1027,14 @@
The following modifiers are really subject modifiers, and are described under
"Subject Modifiers" below. However, they may be included in a pattern's
modifier list, in which case they are applied to every subject line that is
-processed with that pattern. They may not appear in <b>#pattern</b> commands.
-These modifiers do not affect the compilation process.
+processed with that pattern. These modifiers do not affect the compilation
+process.
<pre>
aftertext show text after match
allaftertext show text after captures
allcaptures show all captures
allusedtext show all consulted text
+ altglobal alternative global matching
/g global global matching
jitstack=<n> set size of JIT stack
mark show mark values
@@ -1905,7 +1913,7 @@
</P>
<br><a name="SEC21" href="#TOC1">REVISION</a><br>
<P>
-Last updated: 12 July 2017
+Last updated: 17 October 2017
<br>
Copyright © 1997-2017 University of Cambridge.
<br>
Modified: code/trunk/doc/pcre2.txt
===================================================================
--- code/trunk/doc/pcre2.txt 2017-10-17 16:26:20 UTC (rev 871)
+++ code/trunk/doc/pcre2.txt 2017-10-17 16:26:40 UTC (rev 872)
@@ -2647,25 +2647,29 @@
times, the result is undefined.
After a successful match, a partial match (PCRE2_ERROR_PARTIAL), or a
- failure to match (PCRE2_ERROR_NOMATCH), a (*MARK) name may be avail-
- able, and pcre2_get_mark() can be called. It returns a pointer to the
- zero-terminated name, which is within the compiled pattern. Otherwise
- NULL is returned. The length of the (*MARK) name (excluding the termi-
- nating zero) is stored in the code unit that preceeds the name. You
- should use this instead of relying on the terminating zero if the
- (*MARK) name might contain a binary zero.
+ failure to match (PCRE2_ERROR_NOMATCH), a (*MARK), (*PRUNE), or (*THEN)
+ name may be available. The function pcre2_get_mark() can be called to
+ access this name. The same function applies to all three verbs. It
+ returns a pointer to the zero-terminated name, which is within the com-
+ piled pattern. If no name is available, NULL is returned. The length of
+ the name (excluding the terminating zero) is stored in the code unit
+ that precedes the name. You should use this length instead of relying
+ on the terminating zero if the name might contain a binary zero.
- After a successful match, the (*MARK) name that is returned is the last
- one encountered on the matching path through the pattern. After a "no
- match" or a partial match, the last encountered (*MARK) name is
- returned. For example, consider this pattern:
+ After a successful match, the name that is returned is the last
+ (*MARK), (*PRUNE), or (*THEN) name encountered on the matching path
+ through the pattern. Instances of (*PRUNE) and (*THEN) without names
+ are ignored. Thus, for example, if the matching path contains
+ (*MARK:A)(*PRUNE), the name "A" is returned. After a "no match" or a
+ partial match, the last encountered name is returned. For example,
+ consider this pattern:
^(*MARK:A)((*MARK:B)a|b)c
- When it matches "bc", the returned mark is A. The B mark is "seen" in
+ When it matches "bc", the returned name is A. The B mark is "seen" in
the first branch of the group, but it is not on the matching path. On
the other hand, when this pattern fails to match "bx", the returned
- mark is B.
+ name is B.
After a successful match, a partial match, or one of the invalid UTF
errors (for example, PCRE2_ERROR_UTF8_ERR5), pcre2_get_startchar() can
@@ -3027,29 +3031,35 @@
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 spec-
- ify the insertion of characters from capturing groups or (*MARK) items
- in the pattern. The following forms are always recognized:
+ ify the insertion of characters from capturing groups or (*MARK),
+ (*PRUNE), or (*THEN) items 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 the name of the last (*MARK) encountered
+ $*MARK or ${*MARK} insert a (*MARK), (*PRUNE), or (*THEN) 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+=".
- The facility for inserting a (*MARK) name can be used to perform simple
- simultaneous substitutions, as this pcre2test example shows:
+ $*MARK inserts the name from the last encountered (*MARK), (*PRUNE), or
+ (*THEN) on the matching path that has a name. (*MARK) must always
+ include a name, but (*PRUNE) and (*THEN) 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 simultaneous substitutions, as this pcre2test
+ example shows:
- /(*:pear)apple|(*:orange)lemon/g,replace=${*MARK}
+ /(*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
- options can be set in the options argument.
+ options can be set in the options argument of pcre2_substitute().
PCRE2_SUBSTITUTE_GLOBAL causes the function to iterate over the subject
string, replacing every matching substring. If this is not set, only
@@ -3437,7 +3447,7 @@
REVISION
- Last updated: 25 September 2017
+ Last updated: 13 October 2017
Copyright (c) 1997-2017 University of Cambridge.
------------------------------------------------------------------------------
Modified: code/trunk/doc/pcre2grep.txt
===================================================================
--- code/trunk/doc/pcre2grep.txt 2017-10-17 16:26:20 UTC (rev 871)
+++ code/trunk/doc/pcre2grep.txt 2017-10-17 16:26:40 UTC (rev 872)
@@ -903,7 +903,11 @@
errors. Using the -s option to suppress error messages about inaccessi-
ble files does not affect the return code.
+ When run under VMS, the return code is placed in the symbol
+ PCRE2GREP_RC because VMS does not distinguish between exit(0) and
+ exit(1).
+
SEE ALSO
pcre2pattern(3), pcre2syntax(3), pcre2callout(3).
@@ -918,5 +922,5 @@
REVISION
- Last updated: 17 June 2017
+ Last updated: 11 October 2017
Copyright (c) 1997-2017 University of Cambridge.
