diff options
Diffstat (limited to 'dist2/doc/pcre2test.1')
| -rw-r--r-- | dist2/doc/pcre2test.1 | 113 |
1 files changed, 18 insertions, 95 deletions
diff --git a/dist2/doc/pcre2test.1 b/dist2/doc/pcre2test.1 index 568e7054..f590fe16 100644 --- a/dist2/doc/pcre2test.1 +++ b/dist2/doc/pcre2test.1 @@ -1,4 +1,4 @@ -.TH PCRE2TEST 1 "11 March 2019" "PCRE 10.33" +.TH PCRE2TEST 1 "21 July 2018" "PCRE 10.32" .SH NAME pcre2test - a program for testing Perl-compatible regular expressions. .SH SYNOPSIS @@ -565,10 +565,8 @@ for a description of the effects of these options. /s dotall set PCRE2_DOTALL dupnames set PCRE2_DUPNAMES endanchored set PCRE2_ENDANCHORED - escaped_cr_is_lf set PCRE2_EXTRA_ESCAPED_CR_IS_LF /x extended set PCRE2_EXTENDED /xx extended_more set PCRE2_EXTENDED_MORE - extra_alt_bsux set PCRE2_EXTRA_ALT_BSUX firstline set PCRE2_FIRSTLINE literal set PCRE2_LITERAL match_line set PCRE2_EXTRA_MATCH_LINE @@ -673,14 +671,14 @@ information is obtained from the \fBpcre2_pattern_info()\fP function. Here are some typical examples: .sp re> /(?i)(^a|^b)/m,info - Capture group count = 1 + Capturing subpattern count = 1 Compile options: multiline Overall options: caseless multiline First code unit at start or follows newline Subject length lower bound = 1 .sp re> /(?i)abc/info - Capture group count = 0 + Capturing subpattern count = 0 Compile options: <none> Overall options: caseless First code unit = 'a' (caseless) @@ -1005,7 +1003,6 @@ process. aftertext show text after match allaftertext show text after captures allcaptures show all captures - allvector show the entire ovector allusedtext show all consulted text altglobal alternative global matching /g global global matching @@ -1013,11 +1010,8 @@ process. mark show mark values replace=<string> specify a replacement string startchar show starting character when relevant - substitute_callout use substitution callouts substitute_extended use PCRE2_SUBSTITUTE_EXTENDED - substitute_skip=<n> skip substitution number n substitute_overflow_length use PCRE2_SUBSTITUTE_OVERFLOW_LENGTH - substitute_stop=<n> skip substitution number n and greater substitute_unknown_unset use PCRE2_SUBSTITUTE_UNKNOWN_UNSET substitute_unset_empty use PCRE2_SUBSTITUTE_UNSET_EMPTY .sp @@ -1160,7 +1154,6 @@ pattern. aftertext show text after match allaftertext show text after captures allcaptures show all captures - allvector show the entire ovector allusedtext show all consulted text (non-JIT only) altglobal alternative global matching callout_capture show captures at callout time @@ -1190,11 +1183,8 @@ pattern. replace=<string> specify a replacement string startchar show startchar when relevant startoffset=<n> same as offset=<n> - substitute_callout use substitution callouts substitute_extedded use PCRE2_SUBSTITUTE_EXTENDED - substitute_skip=<n> skip substitution number n substitute_overflow_length use PCRE2_SUBSTITUTE_OVERFLOW_LENGTH - substitute_stop=<n> skip substitution number n and greater substitute_unknown_unset use PCRE2_SUBSTITUTE_UNKNOWN_UNSET substitute_unset_empty use PCRE2_SUBSTITUTE_UNSET_EMPTY zero_terminate pass the subject as zero-terminated @@ -1258,28 +1248,10 @@ captured parentheses be output after a match. By default, only those up to the highest one actually used in the match are output (corresponding to the return code from \fBpcre2_match()\fP). Groups that did not take part in the match are output as "<unset>". This modifier is not relevant for DFA matching (which -does no capturing) and does not apply when \fBreplace\fP is specified; it is -ignored, with a warning message, if present. +does no capturing); it is ignored, with a warning message, if present. . . -.SS "Showing the entire ovector, for all outcomes" -.rs -.sp -The \fBallvector\fP modifier requests that the entire ovector be shown, -whatever the outcome of the match. Compare \fBallcaptures\fP, which shows only -up to the maximum number of capture groups for the pattern, and then only for a -successful complete non-DFA match. This modifier, which acts after any match -result, and also for DFA matching, provides a means of checking that there are -no unexpected modifications to ovector fields. Before each match attempt, the -ovector is filled with a special value, and if this is found in both elements -of a capturing pair, "<unchanged>" is output. After a successful match, this -applies to all groups after the maximum capture group for the pattern. In other -cases it applies to the entire ovector. After a partial match, the first two -elements are the only ones that should be set. After a DFA match, the amount of -ovector that is used depends on the number of matches that were found. -. -. -.SS "Testing pattern callouts" +.SS "Testing callouts" .rs .sp A callout function is supplied when \fBpcre2test\fP calls the library matching @@ -1290,12 +1262,6 @@ controlled by various modifiers listed above whose names begin with .\" </a> below. .\" -Testing callouts from \fBpcre2_substitute()\fP is decribed separately in -"Testing the substitution function" -.\" HTML <a href="#substitution"> -.\" </a> -below. -.\" . . .SS "Finding all matches in a string" @@ -1326,8 +1292,8 @@ current character is CR followed by LF, an advance of two characters occurs. .sp The \fBcopy\fP and \fBget\fP modifiers can be used to test the \fBpcre2_substring_copy_xxx()\fP and \fBpcre2_substring_get_xxx()\fP functions. -They can be given more than once, and each can specify a capture group name or -number, for example: +They can be given more than once, and each can specify a group name or number, +for example: .sp abcd\e=copy=1,copy=3,get=G1 .sp @@ -1346,7 +1312,6 @@ parentheses after each substring, followed by the name when the extraction was by name. . . -.\" HTML <a name="substitution"></a> .SS "Testing the substitution function" .rs .sp @@ -1399,10 +1364,10 @@ The default action of \fBpcre2_substitute()\fP is to return PCRE2_ERROR_NOMEMORY when the output buffer is too small. However, if the PCRE2_SUBSTITUTE_OVERFLOW_LENGTH option is set (by using the \fBsubstitute_overflow_length\fP modifier), \fBpcre2_substitute()\fP continues -to go through the motions of matching and substituting (but not doing any -callouts), in order to compute the size of buffer that is required. When this -happens, \fBpcre2test\fP shows the required buffer length (which includes space -for the trailing zero) as part of the error message. For example: +to go through the motions of matching and substituting, in order to compute the +size of buffer that is required. When this happens, \fBpcre2test\fP shows the +required buffer length (which includes space for the trailing zero) as part of +the error message. For example: .sp /abc/substitute_overflow_length 123abc123\e=replace=[9]XYZ @@ -1413,48 +1378,6 @@ matching provokes an error return ("bad option value") from \fBpcre2_substitute()\fP. . . -.SS "Testing substitute callouts" -.rs -.sp -If the \fBsubstitute_callout\fP modifier is set, a substitution callout -function is set up. The \fBnull_context\fP modifier must not be set, because -the address of the callout function is passed in a match context. When the -callout function is called (after each substitution), details of the the input -and output strings are output. For example: -.sp - /abc/g,replace=<$0>,substitute_callout - abcdefabcpqr - 1(1) Old 0 3 "abc" New 0 5 "<abc>" - 2(1) Old 6 9 "abc" New 8 13 "<abc>" - 2: <abc>def<abc>pqr -.sp -The first number on each callout line is the count of matches. The -parenthesized number is the number of pairs that are set in the ovector (that -is, one more than the number of capturing groups that were set). Then are -listed the offsets of the old substring, its contents, and the same for the -replacement. -.P -By default, the substitution callout function returns zero, which accepts the -replacement and causes matching to continue if /g was used. Two further -modifiers can be used to test other return values. If \fBsubstitute_skip\fP is -set to a value greater than zero the callout function returns +1 for the match -of that number, and similarly \fBsubstitute_stop\fP returns -1. These cause the -replacement to be rejected, and -1 causes no further matching to take place. If -either of them are set, \fBsubstitute_callout\fP is assumed. For example: -.sp - /abc/g,replace=<$0>,substitute_skip=1 - abcdefabcpqr - 1(1) Old 0 3 "abc" New 0 5 "<abc> SKIPPED" - 2(1) Old 6 9 "abc" New 6 11 "<abc>" - 2: abcdef<abc>pqr - abcdefabcpqr\e=substitute_stop=1 - 1(1) Old 0 3 "abc" New 0 5 "<abc> STOPPED" - 1: abcdefabcpqr -.sp -If both are set for the same number, stop takes precedence. Only a single skip -or stop is supported, which is sufficient for testing that the feature works. -. -. .SS "Setting the JIT stack size" .rs .sp @@ -1589,11 +1512,11 @@ passing the replacement string as zero-terminated. .rs .sp Normally, \fBpcre2test\fP passes a context block to \fBpcre2_match()\fP, -\fBpcre2_dfa_match()\fP, \fBpcre2_jit_match()\fP or \fBpcre2_substitute()\fP. -If the \fBnull_context\fP modifier is set, however, NULL is passed. This is for -testing that the matching and substitution functions behave correctly in this -case (they use default values). This modifier cannot be used with the -\fBfind_limits\fP or \fBsubstitute_callout\fP modifiers. +\fBpcre2_dfa_match()\fP or \fBpcre2_jit_match()\fP. If the \fBnull_context\fP +modifier is set, however, NULL is passed. This is for testing that the matching +functions behave correctly in this case (they use default values). This +modifier cannot be used with the \fBfind_limits\fP modifier or when testing the +substitution function. . . .SH "THE ALTERNATIVE MATCHING FUNCTION" @@ -2059,6 +1982,6 @@ Cambridge, England. .rs .sp .nf -Last updated: 11 March 2019 -Copyright (c) 1997-2019 University of Cambridge. +Last updated: 21 July 2018 +Copyright (c) 1997-2018 University of Cambridge. .fi |