diff options
| author | ph10 <ph10@6239d852-aaf2-0410-a92c-79f79f948069> | 2014-11-03 17:13:00 +0000 |
|---|---|---|
| committer | ph10 <ph10@6239d852-aaf2-0410-a92c-79f79f948069> | 2014-11-03 17:13:00 +0000 |
| commit | dbde828d9540f7373f1f5d9fbf17880b9e045f7d (patch) | |
| tree | 73924eb053b8b29cb91070334079138b58808645 /doc/pcre2test.txt | |
| parent | 6a8bc7690a3773eef65bba413c1d5563f3bd63e8 (diff) | |
| download | pcre2-dbde828d9540f7373f1f5d9fbf17880b9e045f7d.tar.gz | |
Changed jit_stack_alloc to jit_stack_create.
git-svn-id: svn://vcs.exim.org/pcre2/code/trunk@131 6239d852-aaf2-0410-a92c-79f79f948069
Diffstat (limited to 'doc/pcre2test.txt')
| -rw-r--r-- | doc/pcre2test.txt | 414 |
1 files changed, 223 insertions, 191 deletions
diff --git a/doc/pcre2test.txt b/doc/pcre2test.txt index 5da745a..0172c49 100644 --- a/doc/pcre2test.txt +++ b/doc/pcre2test.txt @@ -169,137 +169,138 @@ COMMAND LINE OPTIONS DESCRIPTION If pcre2test is given two filename arguments, it reads from the first - and writes to the second. If it is given only one filename argument, it - reads from that file and writes to stdout. Otherwise, it reads from - stdin and writes to stdout, and prompts for each line of input, using - "re>" to prompt for regular expression patterns, and "data>" to prompt - for subject lines. - - When pcre2test is built, a configuration option can specify that it - should be linked with the libreadline or libedit library. When this is - done, if the input is from a terminal, it is read using the readline() + and writes to the second. If the first name is "-", input is taken from + the standard input. If pcre2test is given only one argument, it reads + from that file and writes to stdout. Otherwise, it reads from stdin and + writes to stdout. When the input is a terminal, it prompts for each + line of input, using "re>" to prompt for regular expression patterns, + and "data>" to prompt for subject lines. + + When pcre2test is built, a configuration option can specify that it + should be linked with the libreadline or libedit library. When this is + done, if the input is from a terminal, it is read using the readline() function. This provides line-editing and history facilities. The output from the -help option states whether or not readline() will be used. - The program handles any number of tests, each of which consists of a - set of input lines. Each set starts with a regular expression pattern, + The program handles any number of tests, each of which consists of a + set of input lines. Each set starts with a regular expression pattern, followed by any number of subject lines to be matched against that pat- - tern. In between sets of test data, command lines that begin with a - hash (#) character may appear. This file format, with some restric- + tern. In between sets of test data, command lines that begin with a + hash (#) character may appear. This file format, with some restric- tions, can also be processed by the perltest.pl script that is distrib- - uted with PCRE2 as a means of checking that the behaviour of PCRE2 and + uted with PCRE2 as a means of checking that the behaviour of PCRE2 and Perl is the same. - Each subject line is matched separately and independently. If you want + Each subject line is matched separately and independently. If you want to do multi-line matches, you have to use the \n escape sequence (or \r - or \r\n, etc., depending on the newline setting) in a single line of - input to encode the newline sequences. There is no limit on the length - of subject lines; the input buffer is automatically extended if it is - too small. There is a replication feature that makes it possible to + or \r\n, etc., depending on the newline setting) in a single line of + input to encode the newline sequences. There is no limit on the length + of subject lines; the input buffer is automatically extended if it is + too small. There is a replication feature that makes it possible to generate long subject lines without having to supply them explicitly. - An empty line or the end of the file signals the end of the subject - lines for a test, at which point a new pattern or command line is + An empty line or the end of the file signals the end of the subject + lines for a test, at which point a new pattern or command line is expected if there is still input to be read. COMMAND LINES - In between sets of test data, a line that begins with a hash (#) char- - acter is interpreted as a command line. If the first character is fol- - lowed by white space or an exclamation mark, the line is treated as a - comment, and ignored. Otherwise, the following commands are recog- + In between sets of test data, a line that begins with a hash (#) char- + acter is interpreted as a command line. If the first character is fol- + lowed by white space or an exclamation mark, the line is treated as a + comment, and ignored. Otherwise, the following commands are recog- nized: #forbid_utf - Subsequent patterns automatically have the PCRE2_NEVER_UTF and + Subsequent patterns automatically have the PCRE2_NEVER_UTF and PCRE2_NEVER_UCP options set, which locks out the use of UTF and Unicode - property features. This is a trigger guard that is used in test files - to ensure that UTF/Unicode tests are not accidentally added to files - that are used when UTF support is not included in the library. This - effect can also be obtained by the use of #pattern; the difference is - that #forbid_utf cannot be unset, and the automatic options are not + property features. This is a trigger guard that is used in test files + to ensure that UTF/Unicode tests are not accidentally added to files + that are used when UTF support is not included in the library. This + effect can also be obtained by the use of #pattern; the difference is + that #forbid_utf cannot be unset, and the automatic options are not displayed in pattern information, to avoid cluttering up test output. #pattern <modifier-list> - This command sets a default modifier list that applies to all subse- + This command sets a default modifier list that applies to all subse- quent patterns. Modifiers on a pattern can change these settings. #perltest - The appearance of this line causes all subsequent modifier settings to + The appearance of this line causes all subsequent modifier settings to be checked for compatibility with the perltest.pl script, which is used - to confirm that Perl gives the same results as PCRE2. Also, apart from - comment lines, none of the other command lines are permitted, because - they and many of the modifiers are specific to pcre2test, and should - not be used in test files that are also processed by perltest.pl. The - #perltest command helps detect tests that are accidentally put in the + to confirm that Perl gives the same results as PCRE2. Also, apart from + comment lines, none of the other command lines are permitted, because + they and many of the modifiers are specific to pcre2test, and should + not be used in test files that are also processed by perltest.pl. The + #perltest command helps detect tests that are accidentally put in the wrong file. #subject <modifier-list> - This command sets a default modifier list that applies to all subse- - quent subject lines. Modifiers on a subject line can change these set- + This command sets a default modifier list that applies to all subse- + quent subject lines. Modifiers on a subject line can change these set- tings. MODIFIER SYNTAX Modifier lists are used with both pattern and subject lines. Items in a - list are separated by commas and optional white space. Some modifiers - may be given for both patterns and subject lines, whereas others are - valid for one or the other only. Each modifier has a long name, for + list are separated by commas and optional white space. Some modifiers + may be given for both patterns and subject lines, whereas others are + valid for one or the other only. Each modifier has a long name, for example "anchored", and some of them must be followed by an equals sign and a value, for example, "offset=12". Modifiers that do not take val- ues may be preceded by a minus sign to turn off a previous default set- ting. A few of the more common modifiers can also be specified as single let- - ters, for example "i" for "caseless". In documentation, following the + ters, for example "i" for "caseless". In documentation, following the Perl convention, these are written with a slash ("the /i modifier") for - clarity. Abbreviated modifiers must all be concatenated in the first - item of a modifier list. If the first item is not recognized as a long - modifier name, it is interpreted as a sequence of these abbreviations. + clarity. Abbreviated modifiers must all be concatenated in the first + item of a modifier list. If the first item is not recognized as a long + modifier name, it is interpreted as a sequence of these abbreviations. For example: /abc/ig,newline=cr,jit=3 - This is a pattern line whose modifier list starts with two one-letter - modifiers (/i and /g). The lower-case abbreviated modifiers are the + This is a pattern line whose modifier list starts with two one-letter + modifiers (/i and /g). The lower-case abbreviated modifiers are the same as used in Perl. PATTERN SYNTAX - A pattern line must start with one of the following characters (common + A pattern line must start with one of the following characters (common symbols, excluding pattern meta-characters): / ! " ' ` - = _ : ; , % & @ ~ - This is interpreted as the pattern's delimiter. A regular expression - may be continued over several input lines, in which case the newline + This is interpreted as the pattern's delimiter. A regular expression + may be continued over several input lines, in which case the newline characters are included within it. It is possible to include the delim- iter within the pattern by escaping it with a backslash, for example /abc\/def/ - If you do this, the escape and the delimiter form part of the pattern, + If you do this, the escape and the delimiter form part of the pattern, but since the delimiters are all non-alphanumeric, this does not affect - its interpretation. If the terminating delimiter is immediately fol- + its interpretation. If the terminating delimiter is immediately fol- lowed by a backslash, for example, /abc/\ - then a backslash is added to the end of the pattern. This is done to - provide a way of testing the error condition that arises if a pattern + then a backslash is added to the end of the pattern. This is done to + provide a way of testing the error condition that arises if a pattern finishes with a backslash, because /abc\/ - is interpreted as the first line of a pattern that starts with "abc/", - causing pcre2test to read the next line as a continuation of the regu- + is interpreted as the first line of a pattern that starts with "abc/", + causing pcre2test to read the next line as a continuation of the regu- lar expression. A pattern can be followed by a modifier list (details below). @@ -307,7 +308,7 @@ PATTERN SYNTAX SUBJECT LINE SYNTAX - Before each subject line is passed to pcre2_match() or + Before each subject line is passed to pcre2_match() or pcre2_dfa_match(), leading and trailing white space is removed, and the line is scanned for backslash escapes. The following provide a means of encoding non-printing characters in a visible way: @@ -327,23 +328,23 @@ SUBJECT LINE SYNTAX \x{hh...} hexadecimal character (any number of hex digits) The use of \x{hh...} is not dependent on the use of the utf modifier on - the pattern. It is recognized always. There may be any number of hexa- - decimal digits inside the braces; invalid values provoke error mes- + the pattern. It is recognized always. There may be any number of hexa- + decimal digits inside the braces; invalid values provoke error mes- sages. - Note that \xhh specifies one byte rather than one character in UTF-8 - mode; this makes it possible to construct invalid UTF-8 sequences for - testing purposes. On the other hand, \x{hh} is interpreted as a UTF-8 - character in UTF-8 mode, generating more than one byte if the value is - greater than 127. When testing the 8-bit library not in UTF-8 mode, + Note that \xhh specifies one byte rather than one character in UTF-8 + mode; this makes it possible to construct invalid UTF-8 sequences for + testing purposes. On the other hand, \x{hh} is interpreted as a UTF-8 + character in UTF-8 mode, generating more than one byte if the value is + greater than 127. When testing the 8-bit library not in UTF-8 mode, \x{hh} generates one byte for values less than 256, and causes an error for greater values. In UTF-16 mode, all 4-digit \x{hhhh} values are accepted. This makes it possible to construct invalid UTF-16 sequences for testing purposes. - In UTF-32 mode, all 4- to 8-digit \x{...} values are accepted. This - makes it possible to construct invalid UTF-32 sequences for testing + In UTF-32 mode, all 4- to 8-digit \x{...} values are accepted. This + makes it possible to construct invalid UTF-32 sequences for testing purposes. There is a special backslash sequence that specifies replication of one @@ -351,38 +352,38 @@ SUBJECT LINE SYNTAX \[<characters>]{<count>} - This makes it possible to test long strings without having to provide + This makes it possible to test long strings without having to provide them as part of the file. For example: \[abc]{4} - is converted to "abcabcabcabc". This feature does not support nesting. + is converted to "abcabcabcabc". This feature does not support nesting. To include a closing square bracket in the characters, code it as \x5D. - A backslash followed by an equals sign marke the end of the subject + A backslash followed by an equals sign marke the end of the subject string and the start of a modifier list. For example: abc\=notbol,notempty - A backslash followed by any other non-alphanumeric character just + A backslash followed by any other non-alphanumeric character just escapes that character. A backslash followed by anything else causes an - error. However, if the very last character in the line is a backslash - (and there is no modifier list), it is ignored. This gives a way of - passing an empty line as data, since a real empty line terminates the + error. However, if the very last character in the line is a backslash + (and there is no modifier list), it is ignored. This gives a way of + passing an empty line as data, since a real empty line terminates the data input. PATTERN MODIFIERS There are three types of modifier that can appear in pattern lines, two - of which may also be used in a #pattern command. A pattern's modifier + of which may also be used in a #pattern command. A pattern's modifier list can add to or override default modifiers that were set by a previ- ous #pattern command. Setting compilation options - The following modifiers set options for pcre2_compile(). The most com- - mon ones have single-letter abbreviations. See pcreapi for a descrip- + The following modifiers set options for pcre2_compile(). The most com- + mon ones have single-letter abbreviations. See pcreapi for a descrip- tion of their effects. allow_empty_class set PCRE2_ALLOW_EMPTY_CLASS @@ -408,13 +409,13 @@ PATTERN MODIFIERS utf set PCRE2_UTF As well as turning on the PCRE2_UTF option, the utf modifier causes all - non-printing characters in output strings to be printed using the - \x{hh...} notation. Otherwise, those less than 0x100 are output in hex + non-printing characters in output strings to be printed using the + \x{hh...} notation. Otherwise, those less than 0x100 are output in hex without the curly brackets. Setting compilation controls - The following modifiers affect the compilation process or request + The following modifiers affect the compilation process or request information about the pattern: bsr=[anycrlf|unicode] specify \R handling @@ -424,6 +425,7 @@ PATTERN MODIFIERS /I info show info about compiled pattern hex pattern is coded in hexadecimal jit[=<number>] use JIT + jitfast use JIT fast path jitverify verify JIT use locale=<name> use this locale memory show memory used @@ -440,55 +442,55 @@ PATTERN MODIFIERS Newline and \R handling - The bsr modifier specifies what \R in a pattern should match. If it is - set to "anycrlf", \R matches CR, LF, or CRLF only. If it is set to - "unicode", \R matches any Unicode newline sequence. The default is + The bsr modifier specifies what \R in a pattern should match. If it is + set to "anycrlf", \R matches CR, LF, or CRLF only. If it is set to + "unicode", \R matches any Unicode newline sequence. The default is specified when PCRE2 is built, with the default default being Unicode. - The newline modifier specifies which characters are to be interpreted + The newline modifier specifies which characters are to be interpreted as newlines, both in the pattern and (by default) in subject lines. The type must be one of CR, LF, CRLF, ANYCRLF, or ANY. Information about a pattern - The debug modifier is a shorthand for info,fullbincode, requesting all + The debug modifier is a shorthand for info,fullbincode, requesting all available information. The bincode modifier causes a representation of the compiled code to be - output after compilation. This information does not contain length and + output after compilation. This information does not contain length and offset values, which ensures that the same output is generated for dif- - ferent internal link sizes and different code unit widths. By using - bincode, the same regression tests can be used in different environ- + ferent internal link sizes and different code unit widths. By using + bincode, the same regression tests can be used in different environ- ments. - The fullbincode modifier, by contrast, does include length and offset + The fullbincode modifier, by contrast, does include length and offset values. This is used in a few special tests and is also useful for one- off tests. - The info modifier requests information about the compiled pattern - (whether it is anchored, has a fixed first character, and so on). The + The info modifier requests information about the compiled pattern + (whether it is anchored, has a fixed first character, and so on). The information is obtained from the pcre2_pattern_info() function. Specifying a pattern in hex The hex modifier specifies that the characters of the pattern are to be - interpreted as pairs of hexadecimal digits. White space is permitted + interpreted as pairs of hexadecimal digits. White space is permitted between pairs. For example: /ab 32 59/hex - This feature is provided as a way of creating patterns that contain + This feature is provided as a way of creating patterns that contain binary zero characters. When hex is set, it implies use_length. Using the pattern's length - By default, pcre2test passes patterns as zero-terminated strings to - pcre2_compile(), giving the length as -1. If use_length is set, the + By default, pcre2test passes patterns as zero-terminated strings to + pcre2_compile(), giving the length as -1. If use_length is set, the length of the pattern is passed. This is implied if hex is set. JIT compilation - The /jit modifier may optionally be followed by and equals sign and a + The /jit modifier may optionally be followed by and equals sign and a number in the range 0 to 7: 0 disable JIT @@ -499,17 +501,23 @@ PATTERN MODIFIERS 6 use JIT for soft and hard partial match 7 all three modes - If no number is given, 7 is assumed. If JIT compilation is successful, - the compiled JIT code will automatically be used when pcre2_match() is - run for the appropriate type of match, except when incompatible run- + If no number is given, 7 is assumed. If JIT compilation is successful, + the compiled JIT code will automatically be used when pcre2_match() is + run for the appropriate type of match, except when incompatible run- time options are specified. For more details, see the pcre2jit documen- - tation. See also the jitstack modifier below for a way of setting the + tation. See also the jitstack modifier below for a way of setting the size of the JIT stack. - If the jitverify modifier is specified, information about the compiled - pattern shows whether JIT compilation was or was not successful. If - jitverify is specified without jit, jit=7 is assumed. If JIT compila- - tion is successful when jitverify is set, the text "(JIT)" is added to + If the jitfast modifier is specified, matching is done using the JIT + "fast path" interface (pcre2_jit_match()), which skips some of the san- + ity checks that are done by pcre2_match(), and of course does not work + when JIT is not supported. If jitfast is specified without jit, jit=7 + is assumed. + + If the jitverify modifier is specified, information about the compiled + pattern shows whether JIT compilation was or was not successful. If + jitverify is specified without jit, jit=7 is assumed. If JIT compila- + tion is successful when jitverify is set, the text "(JIT)" is added to the first output line after a match or non match when JIT-compiled code was actually used. @@ -520,31 +528,33 @@ PATTERN MODIFIERS /pattern/locale=fr_FR The given locale is set, pcre2_maketables() is called to build a set of - character tables for the locale, and this is then passed to pcre2_com- - pile() when compiling the regular expression. The same tables are used + character tables for the locale, and this is then passed to pcre2_com- + pile() when compiling the regular expression. The same tables are used when matching the following subject lines. The /locale modifier applies only to the pattern on which it appears, but can be given in a #pattern - command if a default is needed. Setting a locale and alternate charac- + command if a default is needed. Setting a locale and alternate charac- ter tables are mutually exclusive. Showing pattern memory - The /memory modifier causes the size in bytes of the memory block used - to hold the compiled pattern to be output. This does not include the - size of the pcre2_code block; it is just the actual compiled data. If + The /memory modifier causes the size in bytes of the memory block used + to hold the compiled pattern to be output. This does not include the + size of the pcre2_code block; it is just the actual compiled data. If the pattern is subsequently passed to the JIT compiler, the size of the JIT compiled code is also output. Limiting nested parentheses - The parens_nest_limit modifier sets a limit on the depth of nested - parentheses in a pattern. Breaching the limit causes a compilation - error. + The parens_nest_limit modifier sets a limit on the depth of nested + parentheses in a pattern. Breaching the limit causes a compilation + error. The default for the library is set when PCRE2 is built, but + pcre2test sets its own default of 220, which is required for running + the standard test suite. Using the POSIX wrapper API - The /posix modifier causes pcre2test to call PCRE2 via the POSIX wrap- - per API rather than its native API. This supports only the 8-bit + The /posix modifier causes pcre2test to call PCRE2 via the POSIX wrap- + per API rather than its native API. This supports only the 8-bit library. When the POSIX API is being used, the following pattern modi- fiers set options for the regcomp() function: @@ -556,25 +566,25 @@ PATTERN MODIFIERS ucp REG_UCP ) the POSIX standard utf REG_UTF8 ) - The aftertext and allaftertext subject modifiers work as described + The aftertext and allaftertext subject modifiers work as described below. All other modifiers cause an error. Testing the stack guard feature - The /stackguard modifier is used to test the use of pcre2_set_com- - pile_recursion_guard(), a function that is provided to enable stack - availability to be checked during compilation (see the pcre2api docu- - mentation for details). If the number specified by the modifier is + The /stackguard modifier is used to test the use of pcre2_set_com- + pile_recursion_guard(), a function that is provided to enable stack + availability to be checked during compilation (see the pcre2api docu- + mentation for details). If the number specified by the modifier is greater than zero, pcre2_set_compile_recursion_guard() is called to set - up callback from pcre2_compile() to a local function. The argument it - is passed is the current nesting parenthesis depth; if this is greater + up callback from pcre2_compile() to a local function. The argument it + is passed is the current nesting parenthesis depth; if this is greater than the value given by the modifier, non-zero is returned, causing the compilation to be aborted. Using alternative character tables - The /tables modifier must be followed by a single digit. It causes a - specific set of built-in character tables to be passed to pcre2_com- + The /tables modifier must be followed by a single digit. It causes a + specific set of built-in character tables to be passed to pcre2_com- pile(). This is used in the PCRE2 tests to check behaviour with differ- ent character tables. The digit specifies the tables as follows: @@ -583,25 +593,26 @@ PATTERN MODIFIERS pcre2_chartables.c.dist 2 a set of tables defining ISO 8859 characters - In table 2, some characters whose codes are greater than 128 are iden- - tified as letters, digits, spaces, etc. Setting alternate character + In table 2, some characters whose codes are greater than 128 are iden- + tified as letters, digits, spaces, etc. Setting alternate character tables and a locale are mutually exclusive. Setting certain match controls The following modifiers are really subject modifiers, and are described - 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 + 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 do not affect the compilation process. - aftertext show text after match - allaftertext show text after captures - allcaptures show all captures - allusedtext show all consulted text - /g global global matching - mark show mark values + aftertext show text after match + allaftertext show text after captures + allcaptures show all captures + allusedtext show all consulted text + /g global global matching + mark show mark values + startchar show starting character when relevant - These modifiers may not appear in a #pattern command. If you want them + These modifiers may not appear in a #pattern command. If you want them as defaults, set them in a #subject command. @@ -612,7 +623,7 @@ SUBJECT MODIFIERS Setting match options - The following modifiers set options for pcre2_match() or + The following modifiers set options for pcre2_match() or pcre2_dfa_match(). See pcreapi for a description of their effects. anchored set PCRE2_ANCHORED @@ -626,20 +637,20 @@ SUBJECT MODIFIERS partial_hard (or ph) set PCRE2_PARTIAL_HARD partial_soft (or ps) set PCRE2_PARTIAL_SOFT - The partial matching modifiers are provided with abbreviations because + The partial matching modifiers are provided with abbreviations because they appear frequently in tests. - If the /posix modifier was present on the pattern, causing the POSIX + If the /posix modifier was present on the pattern, causing the POSIX wrapper API to be used, the only option-setting modifiers that have any - effect are notbol, notempty, and noteol, causing REG_NOTBOL, - REG_NOTEMPTY, and REG_NOTEOL, respectively, to be passed to regexec(). + effect are notbol, notempty, and noteol, causing REG_NOTBOL, + REG_NOTEMPTY, and REG_NOTEOL, respectively, to be passed to regexec(). Any other modifiers cause an error. Setting match controls - The following modifiers affect the matching process or request addi- - tional information. Some of them may also be specified on a pattern - line (see above), in which case they apply to every subject line that + The following modifiers affect the matching process or request addi- + tional information. Some of them may also be specified on a pattern + line (see above), in which case they apply to every subject line that is matched against that pattern. aftertext show text after match @@ -664,39 +675,56 @@ SUBJECT MODIFIERS offset=<n> set starting offset ovector=<n> set size of output vector recursion_limit=<n> set a recursion limit + startchar show startchar when relevant The effects of these modifiers are described in the following sections. FIXME: Give more examples. Showing more text - The aftertext modifier requests that as well as outputting the sub- - string that matched the entire pattern, pcre2test should in addition - output the remainder of the subject string. This is useful for tests - where the subject contains multiple copies of the same substring. The - allaftertext modifier requests the same action for captured substrings - as well as the main matched substring. In each case the remainder is - output on the following line with a plus character following the cap- + The aftertext modifier requests that as well as outputting the sub- + string that matched the entire pattern, pcre2test should in addition + output the remainder of the subject string. This is useful for tests + where the subject contains multiple copies of the same substring. The + allaftertext modifier requests the same action for captured substrings + as well as the main matched substring. In each case the remainder is + output on the following line with a plus character following the cap- ture number. - The allusedtext modifier requests that all the text that was consulted - during a successful pattern match by the interpreter should be shown. - This feature is not supported for JIT matching, and if requested with - JIT it is ignored (with a warning message). Setting this modifier + The allusedtext modifier requests that all the text that was consulted + during a successful pattern match by the interpreter should be shown. + This feature is not supported for JIT matching, and if requested with + JIT it is ignored (with a warning message). Setting this modifier affects the output if there is a lookbehind at the start of a match, or - a lookahead at the end, or if \K is used in the pattern. Characters - that precede or follow the start and end of the actual match are indi- - cated in the output by '<' or '>' characters underneath them. Here is + a lookahead at the end, or if \K is used in the pattern. Characters + that precede or follow the start and end of the actual match are indi- + cated in the output by '<' or '>' characters underneath them. Here is an example: - /(?<=pqr)abc(?=xyz)/ - 123pqrabcxyz456\=allusedtext + re> /(?<=pqr)abc(?=xyz)/ + data> 123pqrabcxyz456\=allusedtext 0: pqrabcxyz <<< >>> - This shows that the matched string is "abc", with the preceding and + This shows that the matched string is "abc", with the preceding and following strings "pqr" and "xyz" also consulted during the match. + The startchar modifier requests that the starting character for the + match be indicated, if it is different to the start of the matched + string. The only time when this occurs is when \K has been processed as + part of the match. In this situation, the output for the matched string + is displayed from the starting character instead of from the match + point, with circumflex characters under the earlier characters. For + example: + + re> /abc\Kxyz/ + data> abcxyz\=startchar + 0: abcxyz + ^^^ + + Unlike allusedtext, the startchar modifier can be used with JIT. How- + ever, these two modifiers are mutually exclusive. + Showing the value of all capture groups The allcaptures modifier requests that the values of all potential cap- @@ -768,66 +796,70 @@ SUBJECT MODIFIERS The jitstack modifier provides a way of setting the maximum stack size that is used by the just-in-time optimization code. It is ignored if - JIT optimization is not being used. Providing a stack that is larger - than the default 32K is necessary only for very complicated patterns. + JIT optimization is not being used. The value is a number of kilobytes. + Providing a stack that is larger than the default 32K is necessary only + for very complicated patterns. Setting match and recursion limits - The match_limit and recursion_limit modifiers set the appropriate lim- + The match_limit and recursion_limit modifiers set the appropriate lim- its in the match context. These values are ignored when the find_limits modifier is specified. Finding minimum limits - If the find_limits modifier is present, pcre2test calls pcre2_match() - several times, setting different values in the match context via - pcre2_set_match_limit() and pcre2_set_recursion_limit() until it finds - the minimum values for each parameter that allow pcre2_match() to com- + If the find_limits modifier is present, pcre2test calls pcre2_match() + several times, setting different values in the match context via + pcre2_set_match_limit() and pcre2_set_recursion_limit() until it finds + the minimum values for each parameter that allow pcre2_match() to com- plete without error. If JIT is being used, only the match limit is relevant. If DFA matching - is being used, neither limit is relevant, and this modifier is ignored + is being used, neither limit is relevant, and this modifier is ignored (with a warning message). - The match_limit number is a measure of the amount of backtracking 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 numbers of matching possibilities, it can become large very - quickly with increasing length of subject string. The - match_limit_recursion number is a measure of how much stack (or, if - PCRE2 is compiled with NO_RECURSE, how much heap) memory is needed to + The match_limit number is a measure of the amount of backtracking 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 numbers of matching possibilities, it can become large very + quickly with increasing length of subject string. The + match_limit_recursion number is a measure of how much stack (or, if + PCRE2 is compiled with NO_RECURSE, how much heap) memory is needed to complete the match attempt. Showing MARK names The mark modifier causes the names from backtracking control verbs that - are returned from calls to pcre2_match() to be displayed. If a mark is - returned for a match, non-match, or partial match, pcre2test shows it. - For a match, it is on a line by itself, tagged with "MK:". Otherwise, + are returned from calls to pcre2_match() to be displayed. If a mark is + returned for a match, non-match, or partial match, pcre2test shows it. + For a match, it is on a line by itself, tagged with "MK:". Otherwise, it is added to the non-match message. Showing memory usage - The memory modifier causes pcre2test to log all memory allocation and + The memory modifier causes pcre2test to log all memory allocation and freeing calls that occur during a match operation. Setting a starting offset - The offset modifier sets an offset in the subject string at which + The offset modifier sets an offset in the subject string at which matching starts. Its value is a number of code units, not characters. Setting the size of the output vector - The ovector modifier applies only to the subject line in which it - appears, though of course it can also be used to set a default in a - #subject command. It specifies the number of pairs of offsets that are + The ovector modifier applies only to the subject line in which it + appears, though of course it can also be used to set a default in a + #subject command. It specifies the number of pairs of offsets that are available for storing matching information. The default is 15. - At least one pair of offsets is always created by pcre2_match_data_cre- - ate(), for matching with PCRE2's native API, so a value of 0 is the - same as 1. However a value of 0 is useful when testing the POSIX API - because it causes regexec() to be called with a NULL capture vector. + A value of zero is useful when testing the POSIX API because it causes + regexec() to be called with a NULL capture vector. When not testing the + POSIX API, a value of zero is used to cause pcre2_match_data_cre- + ate_from_pattern to be called, in order to create a match block of + exactly the right size for the pattern. (It is not possible to create a + match block with a zero-length ovector; there is always one pair of + offsets.) THE ALTERNATIVE MATCHING FUNCTION @@ -1058,8 +1090,8 @@ NON-PRINTING CHARACTERS SEE ALSO - pcre2(3), pcre16(3), pcre32(3), pcre2api(3), pcre2callout(3), pcre2jit, - pcre2matching(3), pcre2partial(d), pcre2pattern(3), pcre2precompile(3). + pcre2(3), pcre2api(3), pcre2callout(3), pcre2jit, pcre2matching(3), + pcre2partial(d), pcre2pattern(3). AUTHOR @@ -1071,5 +1103,5 @@ AUTHOR REVISION - Last updated: 11 October 2014 + Last updated: 02 November 2014 Copyright (c) 1997-2014 University of Cambridge. |