From deee8d934595c4b856361955aaf4dd26995d203a Mon Sep 17 00:00:00 2001 From: ph10 Date: Sat, 17 Oct 2015 13:50:56 +0000 Subject: Implement --never-backslash-C git-svn-id: svn://vcs.exim.org/pcre2/code/trunk@386 6239d852-aaf2-0410-a92c-79f79f948069 --- doc/pcre2test.txt | 367 +++++++++++++++++++++++++++++------------------------- 1 file changed, 198 insertions(+), 169 deletions(-) (limited to 'doc/pcre2test.txt') diff --git a/doc/pcre2test.txt b/doc/pcre2test.txt index 3dd4f2c..562a859 100644 --- a/doc/pcre2test.txt +++ b/doc/pcre2test.txt @@ -119,12 +119,13 @@ COMMAND LINE OPTIONS The following options output 1 for true or 0 for false, and set the exit code to the same value: - ebcdic compiled for an EBCDIC environment - jit just-in-time support is available - pcre2-16 the 16-bit library was built - pcre2-32 the 32-bit library was built - pcre2-8 the 8-bit library was built - unicode Unicode support is available + backslash-C \C is supported (not locked out) + ebcdic compiled for an EBCDIC environment + jit just-in-time support is available + pcre2-16 the 16-bit library was built + pcre2-32 the 32-bit library was built + pcre2-8 the 8-bit library was built + unicode Unicode support is available If an unknown option is given, an error message is output; the exit code is 0. @@ -457,7 +458,7 @@ PATTERN MODIFIERS 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- + mon ones have single-letter abbreviations. See pcre2api for a descrip- tion of their effects. allow_empty_class set PCRE2_ALLOW_EMPTY_CLASS @@ -484,6 +485,7 @@ PATTERN MODIFIERS no_utf_check set PCRE2_NO_UTF_CHECK ucp set PCRE2_UCP ungreedy set PCRE2_UNGREEDY + use_offset_limit set PCRE2_USE_OFFSET_LIMIT utf set PCRE2_UTF As well as turning on the PCRE2_UTF option, the utf modifier causes all @@ -509,6 +511,7 @@ PATTERN MODIFIERS locale= use this locale memory show memory used newline= set newline type + null_context compile with a NULL context parens_nest_limit= set maximum parentheses depth posix use the POSIX API push push compiled pattern onto the stack @@ -579,35 +582,42 @@ PATTERN MODIFIERS mation that is requested. For each callout, either its number or string is given, followed by the item that follows it in the pattern. + Passing a NULL context + + Normally, pcre2test passes a context block to pcre2_compile(). If the + null_context modifier is set, however, NULL is passed. This is for + testing that pcre2_compile() behaves correctly in this case (it uses + default values). + 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 - binary zero and other non-printing characters. By default, pcre2test - passes patterns as zero-terminated strings to pcre2_compile(), giving + This feature is provided as a way of creating patterns that contain + binary zero and other non-printing characters. By default, pcre2test + passes patterns as zero-terminated strings to pcre2_compile(), giving the length as PCRE2_ZERO_TERMINATED. However, for patterns specified in hexadecimal, the actual length of the pattern is passed. JIT compilation - Just-in-time (JIT) compiling is a heavyweight optimization that can - greatly speed up pattern matching. See the pcre2jit documentation for - details. JIT compiling happens, optionally, after a pattern has been - successfully compiled into an internal form. The JIT compiler converts + Just-in-time (JIT) compiling is a heavyweight optimization that can + greatly speed up pattern matching. See the pcre2jit documentation for + details. JIT compiling happens, optionally, after a pattern has been + successfully compiled into an internal form. The JIT compiler converts this to optimized machine code. It needs to know whether the match-time options PCRE2_PARTIAL_HARD and PCRE2_PARTIAL_SOFT are going to be used, - because different code is generated for the different cases. See the - partial modifier in "Subject Modifiers" below for details of how these + because different code is generated for the different cases. See the + partial modifier in "Subject Modifiers" below for details of how these options are specified for each match attempt. - JIT compilation is requested by the /jit pattern modifier, which may + JIT compilation is requested by the /jit pattern modifier, which may optionally be followed by an equals sign and a number in the range 0 to - 7. The three bits that make up the number specify which of the three + 7. The three bits that make up the number specify which of the three JIT operating modes are to be compiled: 1 compile JIT code for non-partial matching @@ -624,31 +634,31 @@ PATTERN MODIFIERS 6 soft and hard partial matching only 7 all three modes - If no number is given, 7 is assumed. The phrase "partial matching" + If no number is given, 7 is assumed. The phrase "partial matching" means a call to pcre2_match() with either the PCRE2_PARTIAL_SOFT or the - PCRE2_PARTIAL_HARD option set. Note that such a call may return a com- + PCRE2_PARTIAL_HARD option set. Note that such a call may return a com- plete match; the options enable the possibility of a partial match, but - do not require it. Note also that if you request JIT compilation only - for partial matching (for example, /jit=2) but do not set the partial - modifier on a subject line, that match will not use JIT code because + do not require it. Note also that if you request JIT compilation only + for partial matching (for example, /jit=2) but do not set the partial + modifier on a subject line, that match will not use JIT code because none was compiled for non-partial matching. - If JIT compilation is successful, the compiled JIT code will automati- - cally be used when an appropriate type of match is run, except when - incompatible run-time options are specified. For more details, see the - pcre2jit documentation. See also the jitstack modifier below for a way + If JIT compilation is successful, the compiled JIT code will automati- + cally be used when an appropriate type of match is run, except when + incompatible run-time options are specified. For more details, see the + pcre2jit documentation. See also the jitstack modifier below for a way of setting the size of the JIT stack. - 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 + 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 + 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 in the match. @@ -659,18 +669,18 @@ 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 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 + The /memory modifier causes the size in bytes of the memory 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. Here is an example: @@ -681,19 +691,19 @@ PATTERN MODIFIERS 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 default for the library is set when PCRE2 is built, but - pcre2test sets its own default of 220, which is required for running + 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 - library. Note that it does not imply POSIX matching semantics; for - more detail see the pcre2posix documentation. When the POSIX API is - being used, the following pattern modifiers set options for the reg- + 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. Note that it does not imply POSIX matching semantics; for + more detail see the pcre2posix documentation. When the POSIX API is + being used, the following pattern modifiers set options for the reg- comp() function: caseless REG_ICASE @@ -704,24 +714,24 @@ 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 - receives is the current nesting parenthesis depth; if this is greater + up callback from pcre2_compile() to a local function. The argument it + receives 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 value specified for the /tables modifier must be one of the digits + The value specified for the /tables modifier must be one of the digits 0, 1, or 2. It causes a specific set of built-in character tables to be passed to pcre2_compile(). This is used in the PCRE2 tests to check be- haviour with different character tables. The digit specifies the tables @@ -732,15 +742,15 @@ 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 @@ -752,20 +762,20 @@ PATTERN MODIFIERS replace= specify a replacement string 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. Saving a compiled pattern - When a pattern with the push modifier is successfully compiled, it is - pushed onto a stack of compiled patterns, and pcre2test expects the - next line to contain a new pattern (or a command) instead of a subject + When a pattern with the push modifier is successfully compiled, it is + pushed onto a stack of compiled patterns, and pcre2test expects the + next line to contain a new pattern (or a command) instead of a subject line. This facility is used when saving compiled patterns to a file, as - described in the section entitled "Saving and restoring compiled pat- + described in the section entitled "Saving and restoring compiled pat- terns" below. The push modifier is incompatible with compilation modi- fiers such as global that act at match time. Any that are specified are - ignored, with a warning message, except for replace, which causes an - error. Note that, jitverify, which is allowed, does not carry through + ignored, with a warning message, except for replace, which causes an + error. Note that, jitverify, which is allowed, does not carry through to any subsequent matching that uses this pattern. @@ -776,7 +786,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 @@ -790,20 +800,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 @@ -823,9 +833,11 @@ SUBJECT MODIFIERS /g global global matching jitstack= set size of JIT stack mark show mark values - match_limit=>n> set a match limit + match_limit= set a match limit memory show memory usage + null_context match with a NULL context offset= set starting offset + offset_limit= set offset limit ovector= set size of output vector recursion_limit= set a recursion limit replace= specify a replacement string @@ -836,23 +848,23 @@ SUBJECT MODIFIERS Showing more text - The aftertext modifier requests that as well as outputting the part of + The aftertext modifier requests that as well as outputting the part of the subject 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 sub- + The allaftertext modifier requests the same action for captured sub- strings as well as the main matched substring. In each case the remain- der is output on the following line with a plus character following the capture 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: re> /(?<=pqr)abc(?=xyz)/ @@ -860,16 +872,16 @@ SUBJECT MODIFIERS 0: pqrabcxyz <<< >>> - This shows that the matched string is "abc", with the preceding and - following strings "pqr" and "xyz" having been consulted during the + This shows that the matched string is "abc", with the preceding and + following strings "pqr" and "xyz" having been consulted during the match (when processing the assertions). - The startchar modifier requests that the starting character for the - match be indicated, if it is different to the start of the matched + 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 + is displayed from the starting character instead of from the match + point, with circumflex characters under the earlier characters. For example: re> /abc\Kxyz/ @@ -877,7 +889,7 @@ SUBJECT MODIFIERS 0: abcxyz ^^^ - Unlike allusedtext, the startchar modifier can be used with JIT. How- + 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 @@ -885,88 +897,88 @@ SUBJECT MODIFIERS The allcaptures modifier requests that the values of all potential cap- tured 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 pcre2_match()). Groups that did not take part in + the return code from pcre2_match()). Groups that did not take part in the match are output as "". Testing callouts - A callout function is supplied when pcre2test calls the library match- - ing functions, unless callout_none is specified. If callout_capture is + A callout function is supplied when pcre2test calls the library match- + ing functions, unless callout_none is specified. If callout_capture is set, the current captured groups are output when a callout occurs. - The callout_fail modifier can be given one or two numbers. If there is + The callout_fail modifier can be given one or two numbers. If there is only one number, 1 is returned instead of 0 when a callout of that num- - ber is reached. If two numbers are given, 1 is returned when callout + ber is reached. If two numbers are given, 1 is returned when callout is reached for the th time. Note that callouts with string argu- - ments are always given the number zero. See "Callouts" below for a + ments are always given the number zero. See "Callouts" below for a description of the output when a callout it taken. - The callout_data modifier can be given an unsigned or a negative num- - ber. This is set as the "user data" that is passed to the matching - function, and passed back when the callout function is invoked. Any - value other than zero is used as a return from pcre2test's callout + The callout_data modifier can be given an unsigned or a negative num- + ber. This is set as the "user data" that is passed to the matching + function, and passed back when the callout function is invoked. Any + value other than zero is used as a return from pcre2test's callout function. Finding all matches in a string Searching for all possible matches within a subject can be requested by - the global or /altglobal modifier. After finding a match, the matching - function is called again to search the remainder of the subject. The - difference between global and altglobal is that the former uses the - start_offset argument to pcre2_match() or pcre2_dfa_match() to start - searching at a new point within the entire string (which is what Perl + the global or /altglobal modifier. After finding a match, the matching + function is called again to search the remainder of the subject. The + difference between global and altglobal is that the former uses the + start_offset argument to pcre2_match() or pcre2_dfa_match() to start + searching at a new point within the entire string (which is what Perl does), whereas the latter passes over a shortened subject. This makes a difference to the matching process if the pattern begins with a lookbe- hind assertion (including \b or \B). - If an empty string is matched, the next match is done with the + If an empty string is matched, the next match is done with the PCRE2_NOTEMPTY_ATSTART and PCRE2_ANCHORED flags set, in order to search for another, non-empty, match at the same point in the subject. If this - match fails, the start offset is advanced, and the normal match is - retried. This imitates the way Perl handles such cases when using the - /g modifier or the split() function. Normally, the start offset is - advanced by one character, but if the newline convention recognizes - CRLF as a newline, and the current character is CR followed by LF, an + match fails, the start offset is advanced, and the normal match is + retried. This imitates the way Perl handles such cases when using the + /g modifier or the split() function. Normally, the start offset is + advanced by one character, but if the newline convention recognizes + CRLF as a newline, and the current character is CR followed by LF, an advance of two characters occurs. Testing substring extraction functions - The copy and get modifiers can be used to test the pcre2_sub- + The copy and get modifiers can be used to test the pcre2_sub- string_copy_xxx() and pcre2_substring_get_xxx() functions. They can be - given more than once, and each can specify a group name or number, for + given more than once, and each can specify a group name or number, for example: abcd\=copy=1,copy=3,get=G1 - If the #subject command is used to set default copy and/or get lists, - these can be unset by specifying a negative number to cancel all num- + If the #subject command is used to set default copy and/or get lists, + these can be unset by specifying a negative number to cancel all num- bered groups and an empty name to cancel all named groups. - The getall modifier tests pcre2_substring_list_get(), which extracts + The getall modifier tests pcre2_substring_list_get(), which extracts all captured substrings. - If the subject line is successfully matched, the substrings extracted - by the convenience functions are output with C, G, or L after the - string number instead of a colon. This is in addition to the normal - full list. The string length (that is, the return from the extraction + If the subject line is successfully matched, the substrings extracted + by the convenience functions are output with C, G, or L after the + string number instead of a colon. This is in addition to the normal + full list. The string length (that is, the return from the extraction function) is given in parentheses after each substring, followed by the name when the extraction was by name. Testing the substitution function - If the replace modifier is set, the pcre2_substitute() function is - called instead of one of the matching functions. Unlike subject - strings, pcre2test does not process replacement strings for escape + If the replace modifier is set, the pcre2_substitute() function is + called instead of one of the matching functions. Unlike subject + strings, pcre2test does not process replacement strings for escape sequences. In UTF mode, a replacement string is checked to see if it is a valid UTF-8 string. If so, it is correctly converted to a UTF string - of the appropriate code unit width. If it is not a valid UTF-8 string, + of the appropriate code unit width. If it is not a valid UTF-8 string, the individual code units are copied directly. This provides a means of passing an invalid UTF-8 string for testing purposes. - If the global modifier is set, PCRE2_SUBSTITUTE_GLOBAL is passed to + If the global modifier is set, PCRE2_SUBSTITUTE_GLOBAL is passed to pcre2_substitute(). After a successful substitution, the modified - string is output, preceded by the number of replacements. This may be - zero if there were no matches. Here is a simple example of a substitu- + string is output, preceded by the number of replacements. This may be + zero if there were no matches. Here is a simple example of a substitu- tion test: /abc/replace=xxx @@ -975,11 +987,11 @@ SUBJECT MODIFIERS =abc=abc=\=global 2: =xxx=xxx= - Subject and replacement strings should be kept relatively short for - substitution tests, as fixed-size buffers are used. To make it easy to - test for buffer overflow, if the replacement string starts with a num- - ber in square brackets, that number is passed to pcre2_substitute() as - the size of the output buffer, with the replacement string starting at + Subject and replacement strings should be kept relatively short for + substitution tests, as fixed-size buffers are used. To make it easy to + test for buffer overflow, if the replacement string starts with a num- + ber in square brackets, that number is passed to pcre2_substitute() as + the size of the output buffer, with the replacement string starting at the next character. Here is an example that tests the edge case: /abc/ @@ -989,90 +1001,107 @@ SUBJECT MODIFIERS Failed: error -47: no more memory A replacement string is ignored with POSIX and DFA matching. Specifying - partial matching provokes an error return ("bad option value") from + partial matching provokes an error return ("bad option value") from pcre2_substitute(). Setting the JIT stack size - 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 + 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. 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 an offset limit + + The offset_limit modifier sets a limit for unanchored matches. If a + match cannot be found starting at or before this offset in the subject, + a "no match" return is given. The data value is a number of code units, + not characters. When this modifier is used, the use_offset_limit modi- + fier must have been set for the pattern; if not, an error is generated. + 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. - A value of zero is useful when testing the POSIX API because it causes + 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 + 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 at least one + match block with a zero-length ovector; there is always at least one pair of offsets.) Passing the subject as zero-terminated By default, the subject string is passed to a native API matching func- tion with its correct length. In order to test the facility for passing - a zero-terminated string, the zero_terminate modifier is provided. It + a zero-terminated string, the zero_terminate modifier is provided. It causes the length to be passed as PCRE2_ZERO_TERMINATED. (When matching - via the POSIX interface, this modifier has no effect, as there is no + via the POSIX interface, this modifier has no effect, as there is no facility for passing a length.) - When testing pcre2_substitute(), this modifier also has the effect of + When testing pcre2_substitute(), this modifier also has the effect of passing the replacement string as zero-terminated. + Passing a NULL context + + Normally, pcre2test passes a context block to pcre2_match(), + pcre2_dfa_match() or pcre2_jit_match(). If the null_context 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 find_limits modifier or when testing + the substitution function. + THE ALTERNATIVE MATCHING FUNCTION @@ -1398,5 +1427,5 @@ AUTHOR REVISION - Last updated: 14 September 2015 + Last updated: 17 October 2015 Copyright (c) 1997-2015 University of Cambridge. -- cgit v1.2.1