From 89a834b75e3d0c27b58153d47fb975f49a7fd5dc Mon Sep 17 00:00:00 2001 From: "Philip.Hazel" Date: Fri, 13 Oct 2017 16:26:24 +0000 Subject: [PATCH] Documentation update. --- doc/pcre2_get_mark.3 | 15 +++++++------ doc/pcre2api.3 | 51 +++++++++++++++++++++++++------------------- 2 files changed, 38 insertions(+), 28 deletions(-) diff --git a/doc/pcre2_get_mark.3 b/doc/pcre2_get_mark.3 index e741dfe..3b12d4e 100644 --- a/doc/pcre2_get_mark.3 +++ b/doc/pcre2_get_mark.3 @@ -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,11 +14,14 @@ PCRE2 - Perl-compatible regular expressions (revised API) .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 diff --git a/doc/pcre2api.3 b/doc/pcre2api.3 index 343abe4..57c9da5 100644 --- a/doc/pcre2api.3 +++ b/doc/pcre2api.3 @@ -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 @@ appropriate circumstances. If they are called at other times, the result is 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 @@ length is in code units, not bytes. 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 $ or ${} insert the contents of group - $*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 . Curly brackets are required only if the following character would be interpreted as part of the @@ -3148,15 +3151,19 @@ 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 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 @@ Cambridge, England. .rs .sp .nf -Last updated: 25 September 2017 +Last updated: 13 October 2017 Copyright (c) 1997-2017 University of Cambridge. .fi