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-10-23 16:57:22 +00:00
parent 13fe9767cf
commit 76e1ce08a6
2 changed files with 51 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
doc/pcre2api.3
View File

@ -1,4 +1,4 @@
.TH PCRE2API 3 "13 October 2017" "PCRE2 10.31" .TH PCRE2API 3 "22 October 2017" "PCRE2 10.31"
.SH NAME .SH NAME
PCRE2 - Perl-compatible regular expressions (revised API) PCRE2 - Perl-compatible regular expressions (revised API)
.sp .sp
@ -859,11 +859,14 @@ The \fIoffset_limit\fP parameter limits how far an unanchored search can
advance in the subject string. The default value is PCRE2_UNSET. The advance in the subject string. The default value is PCRE2_UNSET. The
\fBpcre2_match()\fP and \fBpcre2_dfa_match()\fP functions return \fBpcre2_match()\fP and \fBpcre2_dfa_match()\fP functions return
PCRE2_ERROR_NOMATCH if a match with a starting point before or at the given PCRE2_ERROR_NOMATCH if a match with a starting point before or at the given
offset is not found. For example, if the pattern /abc/ is matched against offset is not found. The \fBpcre2_substitute()\fP function makes no more
"123abc" with an offset limit less than 3, the result is PCRE2_ERROR_NO_MATCH. substitutions.
A match can never be found if the \fIstartoffset\fP argument of .P
\fBpcre2_match()\fP or \fBpcre2_dfa_match()\fP is greater than the offset For example, if the pattern /abc/ is matched against "123abc" with an offset
limit. limit less than 3, the result is PCRE2_ERROR_NO_MATCH. A match can never be
found if the \fIstartoffset\fP argument of \fBpcre2_match()\fP,
\fBpcre2_dfa_match()\fP, or \fBpcre2_substitute()\fP is greater than the offset
limit set in the match context.
.P .P
When using this facility, you must set the PCRE2_USE_OFFSET_LIMIT option when When using this facility, you must set the PCRE2_USE_OFFSET_LIMIT option when
calling \fBpcre2_compile()\fP so that when JIT is in use, different code can be calling \fBpcre2_compile()\fP so that when JIT is in use, different code can be
@ -871,10 +874,11 @@ compiled. If a match is started with a non-default match limit when
PCRE2_USE_OFFSET_LIMIT is not set, an error is generated. PCRE2_USE_OFFSET_LIMIT is not set, an error is generated.
.P .P
The offset limit facility can be used to track progress when searching large The offset limit facility can be used to track progress when searching large
subject strings. See also the PCRE2_FIRSTLINE option, which requires a match to subject strings or to limit the extent of global substitutions. See also the
start within the first line of the subject. If this is set with an offset PCRE2_FIRSTLINE option, which requires a match to start within the first line
limit, a match must occur in the first line and also within the offset limit. of the subject. If this is set with an offset limit, a match must occur in the
In other words, whichever limit comes first is used. first line and also within the offset limit. In other words, whichever limit
comes first is used.
.sp .sp
.nf .nf
.B int pcre2_set_heap_limit(pcre2_match_context *\fImcontext\fP, .B int pcre2_set_heap_limit(pcre2_match_context *\fImcontext\fP,
@ -3166,13 +3170,26 @@ As well as the usual options for \fBpcre2_match()\fP, a number of additional
options can be set in the \fIoptions\fP argument of \fBpcre2_substitute()\fP. options can be set in the \fIoptions\fP argument of \fBpcre2_substitute()\fP.
.P .P
PCRE2_SUBSTITUTE_GLOBAL causes the function to iterate over the subject string, 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 replacing every matching substring. If this option is not set, only the first
substring is replaced. If any matched substring has zero length, after the matching substring is replaced. The search for matches takes place in the
substitution has happened, an attempt to find a non-empty match at the same original subject string (that is, previous replacements do not affect it).
position is performed. If this is not successful, the current position is Iteration is implemented by advancing the \fIstartoffset\fP value for each
advanced by one character except when CRLF is a valid newline sequence and the search, which is always passed the entire subject string. If an offset limit is
next two characters are CR, LF. In this case, the current position is advanced set in the match context, searching stops when that limit is reached.
by two characters. .P
You can restrict the effect of a global substitution to a portion of the
subject string by setting either or both of \fIstartoffset\fP and an offset
limit. Here is a \fPpcre2test\fP example:
.sp
/B/g,replace=!,use_offset_limit
ABC ABC ABC ABC\=offset=3,offset_limit=12
2: ABC A!C A!C ABC
.sp
When continuing with global substitutions after matching a substring with zero
length, an attempt to find a non-empty match at the same offset is performed.
If this is not successful, the offset is advanced by one character except when
CRLF is a valid newline sequence and the next two characters are CR, LF. In
this case, the offset is advanced by two characters.
.P .P
PCRE2_SUBSTITUTE_OVERFLOW_LENGTH changes what happens when the output buffer is PCRE2_SUBSTITUTE_OVERFLOW_LENGTH changes what happens when the output buffer is
too small. The default action is to return PCRE2_ERROR_NOMEMORY immediately. If too small. The default action is to return PCRE2_ERROR_NOMEMORY immediately. If
@ -3580,6 +3597,6 @@ Cambridge, England.
.rs .rs
.sp .sp
.nf .nf
Last updated: 13 October 2017 Last updated: 22 October 2017
Copyright (c) 1997-2017 University of Cambridge. Copyright (c) 1997-2017 University of Cambridge.
.fi .fi

28
doc/pcre2grep.1
View File

@ -1,4 +1,4 @@
.TH PCRE2GREP 1 "11 October 2017" "PCRE2 10.31" .TH PCRE2GREP 1 "23 October 2017" "PCRE2 10.31"
.SH NAME .SH NAME
pcre2grep - a grep with Perl-compatible regular expressions. pcre2grep - a grep with Perl-compatible regular expressions.
.SH SYNOPSIS .SH SYNOPSIS
@ -123,7 +123,7 @@ of changing the way binary files are handled.
.rs .rs
.sp .sp
The order in which some of the options appear can affect the output. For The order in which some of the options appear can affect the output. For
example, both the \fB-h\fP and \fB-l\fP options affect the printing of file example, both the \fB-H\fP and \fB-l\fP options affect the printing of file
names. Whichever comes later in the command line will be the one that takes names. Whichever comes later in the command line will be the one that takes
effect. Similarly, except where noted below, if an option is given twice, the effect. Similarly, except where noted below, if an option is given twice, the
later setting is used. Numerical values for options may be followed by K or M, later setting is used. Numerical values for options may be followed by K or M,
@ -341,13 +341,15 @@ searching a single file. By default, the file name is not shown in this case.
For matching lines, the file name is followed by a colon; for context lines, a For matching lines, the file name is followed by a colon; for context lines, a
hyphen separator is used. If a line number is also being output, it follows the hyphen separator is used. If a line number is also being output, it follows the
file name. When the \fB-M\fP option causes a pattern to match more than one file name. When the \fB-M\fP option causes a pattern to match more than one
line, only the first is preceded by the file name. line, only the first is preceded by the file name. This option overrides any
previous \fB-h\fP, \fB-l\fP, or \fB-L\fP options.
.TP .TP
\fB-h\fP, \fB--no-filename\fP \fB-h\fP, \fB--no-filename\fP
Suppress the output file names when searching multiple files. By default, Suppress the output file names when searching multiple files. By default,
file names are shown when multiple files are searched. For matching lines, the file names are shown when multiple files are searched. For matching lines, the
file name is followed by a colon; for context lines, a hyphen separator is used. file name is followed by a colon; for context lines, a hyphen separator is used.
If a line number is also being output, it follows the file name. If a line number is also being output, it follows the file name. This option
overrides any previous \fB-H\fP, \fB-L\fP, or \fB-l\fP options.
.TP .TP
\fB--heap-limit\fP=\fInumber\fP \fB--heap-limit\fP=\fInumber\fP
See \fB--match-limit\fP below. See \fB--match-limit\fP below.
@ -396,16 +398,18 @@ given any number of times. If a directory matches both \fB--include-dir\fP and
\fB-L\fP, \fB--files-without-match\fP \fB-L\fP, \fB--files-without-match\fP
Instead of outputting lines from the files, just output the names of the files Instead of outputting lines from the files, just output the names of the files
that do not contain any lines that would have been output. Each file name is that do not contain any lines that would have been output. Each file name is
output once, on a separate line. output once, on a separate line. This option overrides any previous \fB-H\fP,
\fB-h\fP, or \fB-l\fP options.
.TP .TP
\fB-l\fP, \fB--files-with-matches\fP \fB-l\fP, \fB--files-with-matches\fP
Instead of outputting lines from the files, just output the names of the files Instead of outputting lines from the files, just output the names of the files
containing lines that would have been output. Each file name is output containing lines that would have been output. Each file name is output once, on
once, on a separate line. Searching normally stops as soon as a matching line a separate line. Searching normally stops as soon as a matching line is found
is found in a file. However, if the \fB-c\fP (count) option is also used, in a file. However, if the \fB-c\fP (count) option is also used, matching
matching continues in order to obtain the correct count, and those files that continues in order to obtain the correct count, and those files that have at
have at least one match are listed along with their counts. Using this option least one match are listed along with their counts. Using this option with
with \fB-c\fP is a way of suppressing the listing of files with no matches. \fB-c\fP is a way of suppressing the listing of files with no matches. This
opeion overrides any previous \fB-H\fP, \fB-h\fP, or \fB-L\fP options.
.TP .TP
\fB--label\fP=\fIname\fP \fB--label\fP=\fIname\fP
This option supplies a name to be used for the standard input when file names This option supplies a name to be used for the standard input when file names
@ -854,6 +858,6 @@ Cambridge, England.
.rs .rs
.sp .sp
.nf .nf
Last updated: 11 October 2017 Last updated: 23 October 2017
Copyright (c) 1997-2017 University of Cambridge. Copyright (c) 1997-2017 University of Cambridge.
.fi .fi