walkero
/
pcre2
1
0
Fork 0
Code Issues Pull Requests Projects Releases 1 Wiki Activity

Derived documentation update.

This commit is contained in:
Philip.Hazel 2017-10-17 16:26:40 +00:00
parent cc2182261a
commit 71d0ee75d2
6 changed files with 94 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
doc/html/pcre2_get_mark.html
View File

@ -26,11 +26,15 @@ DESCRIPTION
</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

49
doc/html/pcre2api.html
View File

@ -2719,25 +2719,28 @@ undefined.
</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 @@ 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:
<pre>
$$ insert a dollar character
$&#60;n&#62; or ${&#60;n&#62;} insert the contents of group &#60;n&#62;
$*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 &#60;n&#62;. Curly brackets are
required only if the following character would be interpreted as part of the
@ -3138,15 +3141,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>
<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 @@ Cambridge, England.
</P>
<br><a name="SEC42" href="#TOC1">REVISION</a><br>
<P>
Last updated: 25 September 2017
Last updated: 13 October 2017
<br>
Copyright &copy; 1997-2017 University of Cambridge.
<br>

6
doc/html/pcre2grep.html
View File

@ -922,6 +922,10 @@ matches were found in other files) or too many matching errors. Using the
<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 @@ Cambridge, England.
</P>
<br><a name="SEC15" href="#TOC1">REVISION</a><br>
<P>
Last updated: 17 June 2017
Last updated: 11 October 2017
<br>
Copyright &copy; 1997-2017 University of Cambridge.
<br>

16
doc/html/pcre2test.html
View File

@ -167,7 +167,8 @@ internal binary form of the pattern is output after compilation.
<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 @@ successful compilation, each pattern is passed to the just-in-time compiler, if
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 @@ Setting certain match controls
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=&#60;n&#62; set size of JIT stack
mark show mark values
@ -1905,7 +1913,7 @@ Cambridge, England.
</P>
<br><a name="SEC21" href="#TOC1">REVISION</a><br>
<P>
Last updated: 12 July 2017
Last updated: 17 October 2017
<br>
Copyright &copy; 1997-2017 University of Cambridge.
<br>

60
doc/pcre2.txt
View File

@ -2647,25 +2647,29 @@ OTHER INFORMATION ABOUT A MATCH
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 @@ CREATING A NEW STRING WITH SUBSTITUTIONS
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 @@ AUTHOR
REVISION
Last updated: 25 September 2017
Last updated: 13 October 2017
Copyright (c) 1997-2017 University of Cambridge.
------------------------------------------------------------------------------

6
doc/pcre2grep.txt
View File

@ -903,6 +903,10 @@ DIAGNOSTICS
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
@ -918,5 +922,5 @@ AUTHOR
REVISION
Last updated: 17 June 2017
Last updated: 11 October 2017
Copyright (c) 1997-2017 University of Cambridge.