Revision: 870
http://www.exim.org/viewvc/pcre2?view=rev&revision=870
Author: ph10
Date: 2017-10-13 17:26:24 +0100 (Fri, 13 Oct 2017)
Log Message:
-----------
Documentation update.
Modified Paths:
--------------
code/trunk/doc/pcre2_get_mark.3
code/trunk/doc/pcre2api.3
Modified: code/trunk/doc/pcre2_get_mark.3
===================================================================
--- code/trunk/doc/pcre2_get_mark.3 2017-10-11 16:54:22 UTC (rev 869)
+++ code/trunk/doc/pcre2_get_mark.3 2017-10-13 16:26:24 UTC (rev 870)
@@ -1,4 +1,4 @@
-.TH PCRE2_GET_MARK 3 "24 October 2014" "PCRE2 10.00"
+.TH PCRE2_GET_MARK 3 "13 October 2017" "PCRE2 10.31"
.SH NAME
PCRE2 - Perl-compatible regular expressions (revised API)
.SH SYNOPSIS
@@ -14,12 +14,15 @@
.rs
.sp
After a call of \fBpcre2_match()\fP 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
+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
There is a complete description of the PCRE2 native API in the
.\" HREF
\fBpcre2api\fP
Modified: code/trunk/doc/pcre2api.3
===================================================================
--- code/trunk/doc/pcre2api.3 2017-10-11 16:54:22 UTC (rev 869)
+++ code/trunk/doc/pcre2api.3 2017-10-13 16:26:24 UTC (rev 870)
@@ -1,4 +1,4 @@
-.TH PCRE2API 3 "25 September 2017" "PCRE2 10.31"
+.TH PCRE2API 3 "13 October 2017" "PCRE2 10.31"
.SH NAME
PCRE2 - Perl-compatible regular expressions (revised API)
.sp
@@ -2717,24 +2717,27 @@
undefined.
.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
-\fBpcre2_get_mark()\fP 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 \fBpcre2_get_mark()\fP 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
-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:
.sp
^(*MARK:A)((*MARK:B)a|b)c
.sp
-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
After a successful match, a partial match, or one of the invalid UTF errors
(for example, PCRE2_ERROR_UTF8_ERR5), \fBpcre2_get_startchar()\fP can be
@@ -3135,12 +3138,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:
.sp
$$ 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
.sp
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
@@ -3148,15 +3151,19 @@
For example, if the pattern a(b)c is matched with "=abc=" and the replacement
string "+$1$0$1+", the result is "=+babcb+=".
.P
-The facility for inserting a (*MARK) name can be used to perform simple
-simultaneous substitutions, as this \fBpcre2test\fP 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
+\fBpcre2test\fP example shows:
.sp
- /(*:pear)apple|(*:orange)lemon/g,replace=${*MARK}
+ /(*MARK:pear)apple|(*MARK:orange)lemon/g,replace=${*MARK}
apple lemon
2: pear orange
.sp
As well as the usual options for \fBpcre2_match()\fP, a number of additional
-options can be set in the \fIoptions\fP argument.
+options can be set in the \fIoptions\fP argument of \fBpcre2_substitute()\fP.
.P
PCRE2_SUBSTITUTE_GLOBAL causes the function to iterate over the subject string,
replacing every matching substring. If this is not set, only the first matching
@@ -3573,6 +3580,6 @@
.rs
.sp
.nf
-Last updated: 25 September 2017
+Last updated: 13 October 2017
Copyright (c) 1997-2017 University of Cambridge.
.fi
