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

Documentation update

This commit is contained in:
Philip.Hazel 2017-03-25 11:52:22 +00:00
parent 25cec7a966
commit 935183d2d5
4 changed files with 182 additions and 162 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
doc/html/pcre2_match.html
View File

@ -43,26 +43,25 @@ offsets to captured substrings. Its arguments are:
A match context is needed only if you want to: A match context is needed only if you want to:
<pre> <pre>
Set up a callout function Set up a callout function
Change the limit for calling the internal function <i>match()</i> Set a matching offset limit
Change the limit for calling <i>match()</i> recursively Change the backtracking match limit
Set custom memory management when the heap is used for recursion Change the backtracking depth limit
Set custom memory management in the match context
</pre> </pre>
The <i>length</i> and <i>startoffset</i> values are code The <i>length</i> and <i>startoffset</i> values are code
units, not characters. The options are: units, not characters. The length may be given as PCRE2_ZERO_TERMINATE for a
subject that is terminated by a binary zero code unit. The options are:
<pre> <pre>
PCRE2_ANCHORED Match only at the first position PCRE2_ANCHORED Match only at the first position
PCRE2_NOTBOL Subject string is not the beginning of a line PCRE2_NOTBOL Subject string is not the beginning of a line
PCRE2_NOTEOL Subject string is not the end of a line PCRE2_NOTEOL Subject string is not the end of a line
PCRE2_NOTEMPTY An empty string is not a valid match PCRE2_NOTEMPTY An empty string is not a valid match
PCRE2_NOTEMPTY_ATSTART An empty string at the start of the subject PCRE2_NOTEMPTY_ATSTART An empty string at the start of the subject is not a valid match
is not a valid match PCRE2_NO_JIT Do not use JIT matching
PCRE2_NO_UTF_CHECK Do not check the subject for UTF PCRE2_NO_UTF_CHECK Do not check the subject for UTF validity (only relevant if PCRE2_UTF
validity (only relevant if PCRE2_UTF
was set at compile time) was set at compile time)
PCRE2_PARTIAL_SOFT Return PCRE2_ERROR_PARTIAL for a partial PCRE2_PARTIAL_HARD Return PCRE2_ERROR_PARTIAL for a partial match even if there is a full match
match if no full matches are found PCRE2_PARTIAL_SOFT Return PCRE2_ERROR_PARTIAL for a partial match if no full matches are found
PCRE2_PARTIAL_HARD Return PCRE2_ERROR_PARTIAL for a partial match
if that is found before a full match
</pre> </pre>
For details of partial matching, see the For details of partial matching, see the
<a href="pcre2partial.html"><b>pcre2partial</b></a> <a href="pcre2partial.html"><b>pcre2partial</b></a>

37
doc/html/pcre2test.html
View File

@ -1082,14 +1082,14 @@ pattern.
copy=&#60;number or name&#62; copy captured substring copy=&#60;number or name&#62; copy captured substring
depth_limit=&#60;n&#62; set a depth limit depth_limit=&#60;n&#62; set a depth limit
dfa use <b>pcre2_dfa_match()</b> dfa use <b>pcre2_dfa_match()</b>
find_limits find match and recursion limits find_limits find match and depth limits
get=&#60;number or name&#62; extract captured substring get=&#60;number or name&#62; extract captured substring
getall extract all captured substrings getall extract all captured substrings
/g global global matching /g global global matching
jitstack=&#60;n&#62; set size of JIT stack jitstack=&#60;n&#62; set size of JIT stack
mark show mark values mark show mark values
match_limit=&#60;n&#62; set a match limit match_limit=&#60;n&#62; set a match limit
memory show memory usage memory show heap memory usage
null_context match with a NULL context null_context match with a NULL context
offset=&#60;n&#62; set starting offset offset=&#60;n&#62; set starting offset
offset_limit=&#60;n&#62; set offset limit offset_limit=&#60;n&#62; set offset limit
@ -1339,25 +1339,29 @@ limits in the match context. These values are ignored when the
Finding minimum limits Finding minimum limits
</b><br> </b><br>
<P> <P>
If the <b>find_limits</b> modifier is present, <b>pcre2test</b> calls If the <b>find_limits</b> modifier is present on a subject line, <b>pcre2test</b>
<b>pcre2_match()</b> several times, setting different values in the match calls the relevant matching function several times, setting different values in
context via <b>pcre2_set_match_limit()</b> and <b>pcre2_set_depth_limit()</b> the match context via <b>pcre2_set_match_limit()</b> or
until it finds the minimum values for each parameter that allow <b>pcre2_set_depth_limit()</b> until it finds the minimum values for each
<b>pcre2_match()</b> to complete without error. parameter that allows the match to complete without error.
</P> </P>
<P> <P>
If JIT is being used, only the match limit is relevant. If DFA matching is If JIT is being used, only the match limit is relevant. If DFA matching is
being used, only the depth limit is relevant, but at present this modifier is being used, only the depth limit is relevant.
ignored (with a warning message).
</P> </P>
<P> <P>
The <i>match_limit</i> number is a measure of the amount of backtracking The <i>match_limit</i> number is a measure of the amount of backtracking
that takes place, and learning the minimum value can be instructive. For most that takes place, and learning the minimum value can be instructive. For most
simple matches, the number is quite small, but for patterns with very large simple matches, the number is quite small, but for patterns with very large
numbers of matching possibilities, it can become large very quickly with numbers of matching possibilities, it can become large very quickly with
increasing length of subject string. The <i>depth_limit</i> number is increasing length of subject string.
a measure of how much memory for recording backtracking points is needed to </P>
complete the match attempt. <P>
For non-DFA matching, the minimum <i>depth_limit</i> number is a measure of how
much memory for recording backtracking points is needed to complete the match
attempt. In the case of DFA matching, <i>depth_limit</i> controls the depth of
recursive calls of the internal function that is used for handling pattern
recursion, lookaround assertions, and atomic groups.
</P> </P>
<br><b> <br><b>
Showing MARK names Showing MARK names
@ -1373,8 +1377,11 @@ is added to the non-match message.
Showing memory usage Showing memory usage
</b><br> </b><br>
<P> <P>
The <b>memory</b> modifier causes <b>pcre2test</b> to log all memory allocation The <b>memory</b> modifier causes <b>pcre2test</b> to log all heap memory
and freeing calls that occur during a match operation. allocation and freeing calls that occur during a call to <b>pcre2_match()</b>.
These occur only when a match requires a bigger vector than the default for
remembering backtracking points. In many cases there will be none. No heap
memory is allocated during matching with <b>pcre2_dfa_match</b> or with JIT.
</P> </P>
<br><b> <br><b>
Setting a starting offset Setting a starting offset
@ -1787,7 +1794,7 @@ Cambridge, England.
</P> </P>
<br><a name="SEC21" href="#TOC1">REVISION</a><br> <br><a name="SEC21" href="#TOC1">REVISION</a><br>
<P> <P>
Last updated: 21 March 2017 Last updated: 24 March 2017
<br> <br>
Copyright &copy; 1997-2017 University of Cambridge. Copyright &copy; 1997-2017 University of Cambridge.
<br> <br>

21
doc/pcre2_match.3
View File

@ -1,4 +1,4 @@
.TH PCRE2_MATCH 3 "21 October 2014" "PCRE2 10.00" .TH PCRE2_MATCH 3 "25 March 2017" "PCRE2 10.30"
.SH NAME .SH NAME
PCRE2 - Perl-compatible regular expressions (revised API) PCRE2 - Perl-compatible regular expressions (revised API)
.SH SYNOPSIS .SH SYNOPSIS
@ -31,26 +31,33 @@ offsets to captured substrings. Its arguments are:
A match context is needed only if you want to: A match context is needed only if you want to:
.sp .sp
Set up a callout function Set up a callout function
Change the limit for calling the internal function \fImatch()\fP Set a matching offset limit
Change the limit for calling \fImatch()\fP recursively Change the backtracking match limit
Set custom memory management when the heap is used for recursion Change the backtracking depth limit
Set custom memory management in the match context
.sp .sp
The \fIlength\fP and \fIstartoffset\fP values are code The \fIlength\fP and \fIstartoffset\fP values are code
units, not characters. The options are: units, not characters. The length may be given as PCRE2_ZERO_TERMINATE for a
subject that is terminated by a binary zero code unit. The options are:
.sp .sp
PCRE2_ANCHORED Match only at the first position PCRE2_ANCHORED Match only at the first position
PCRE2_NOTBOL Subject string is not the beginning of a line PCRE2_NOTBOL Subject string is not the beginning of a line
PCRE2_NOTEOL Subject string is not the end of a line PCRE2_NOTEOL Subject string is not the end of a line
PCRE2_NOTEMPTY An empty string is not a valid match PCRE2_NOTEMPTY An empty string is not a valid match
.\" JOIN
PCRE2_NOTEMPTY_ATSTART An empty string at the start of the subject PCRE2_NOTEMPTY_ATSTART An empty string at the start of the subject
is not a valid match is not a valid match
PCRE2_NO_JIT Do not use JIT matching
.\" JOIN
PCRE2_NO_UTF_CHECK Do not check the subject for UTF PCRE2_NO_UTF_CHECK Do not check the subject for UTF
validity (only relevant if PCRE2_UTF validity (only relevant if PCRE2_UTF
was set at compile time) was set at compile time)
.\" JOIN
PCRE2_PARTIAL_HARD Return PCRE2_ERROR_PARTIAL for a partial
match even if there is a full match
.\" JOIN
PCRE2_PARTIAL_SOFT Return PCRE2_ERROR_PARTIAL for a partial PCRE2_PARTIAL_SOFT Return PCRE2_ERROR_PARTIAL for a partial
match if no full matches are found match if no full matches are found
PCRE2_PARTIAL_HARD Return PCRE2_ERROR_PARTIAL for a partial match
if that is found before a full match
.sp .sp
For details of partial matching, see the For details of partial matching, see the
.\" HREF .\" HREF

37
doc/pcre2test.txt
View File

@ -966,14 +966,14 @@ SUBJECT MODIFIERS
copy=<number or name> copy captured substring copy=<number or name> copy captured substring
depth_limit=<n> set a depth limit depth_limit=<n> set a depth limit
dfa use pcre2_dfa_match() dfa use pcre2_dfa_match()
find_limits find match and recursion limits find_limits find match and depth limits
get=<number or name> extract captured substring get=<number or name> extract captured substring
getall extract all captured substrings getall extract all captured substrings
/g global global matching /g global global matching
jitstack=<n> set size of JIT stack jitstack=<n> set size of JIT stack
mark show mark values mark show mark values
match_limit=<n> set a match limit match_limit=<n> set a match limit
memory show memory usage memory show heap memory usage
null_context match with a NULL context null_context match with a NULL context
offset=<n> set starting offset offset=<n> set starting offset
offset_limit=<n> set offset limit offset_limit=<n> set offset limit
@ -1202,23 +1202,26 @@ SUBJECT MODIFIERS
Finding minimum limits Finding minimum limits
If the find_limits modifier is present, pcre2test calls pcre2_match() If the find_limits modifier is present on a subject line, pcre2test
several times, setting different values in the match context via calls the relevant matching function several times, setting different
pcre2_set_match_limit() and pcre2_set_depth_limit() until it finds the values in the match context via pcre2_set_match_limit() or
minimum values for each parameter that allow pcre2_match() to complete pcre2_set_depth_limit() until it finds the minimum values for each
without error. parameter that allows the match to complete without error.
If JIT is being used, only the match limit is relevant. If DFA matching If JIT is being used, only the match limit is relevant. If DFA matching
is being used, only the depth limit is relevant, but at present this is being used, only the depth limit is relevant.
modifier is ignored (with a warning message).
The match_limit number is a measure of the amount of backtracking that The match_limit number is a measure of the amount of backtracking that
takes place, and learning the minimum value can be instructive. For takes place, and learning the minimum value can be instructive. For
most simple matches, the number is quite small, but for patterns with most simple matches, the number is quite small, but for patterns with
very large numbers of matching possibilities, it can become large very very large numbers of matching possibilities, it can become large very
quickly with increasing length of subject string. The depth_limit num- quickly with increasing length of subject string.
ber is a measure of how much memory for recording backtracking points
is needed to complete the match attempt. For non-DFA matching, the minimum depth_limit number is a measure of
how much memory for recording backtracking points is needed to complete
the match attempt. In the case of DFA matching, depth_limit controls
the depth of recursive calls of the internal function that is used for
handling pattern recursion, lookaround assertions, and atomic groups.
Showing MARK names Showing MARK names
@ -1231,8 +1234,12 @@ SUBJECT MODIFIERS
Showing memory usage Showing memory usage
The memory modifier causes pcre2test to log all memory allocation and The memory modifier causes pcre2test to log all heap memory allocation
freeing calls that occur during a match operation. and freeing calls that occur during a call to pcre2_match(). These
occur only when a match requires a bigger vector than the default for
remembering backtracking points. In many cases there will be none. No
heap memory is allocated during matching with pcre2_dfa_match or with
JIT.
Setting a starting offset Setting a starting offset
@ -1619,5 +1626,5 @@ AUTHOR
REVISION REVISION
Last updated: 21 March 2017 Last updated: 24 March 2017
Copyright (c) 1997-2017 University of Cambridge. Copyright (c) 1997-2017 University of Cambridge.