From 1c19b1fe61481390f7c5b33d5a67cd7b9978f4ba Mon Sep 17 00:00:00 2001 From: ph10 Date: Fri, 22 Dec 2017 15:56:27 +0000 Subject: Add callout_flags to callout blocks, and set bits within it from pcre2_match() interpretation. git-svn-id: svn://vcs.exim.org/pcre2/code/trunk@893 6239d852-aaf2-0410-a92c-79f79f948069 --- doc/html/pcre2test.html | 161 ++++++++++++++++++++++++++++++++++-------------- 1 file changed, 115 insertions(+), 46 deletions(-) (limited to 'doc/html/pcre2test.html') diff --git a/doc/html/pcre2test.html b/doc/html/pcre2test.html index 3427787..7d98d90 100644 --- a/doc/html/pcre2test.html +++ b/doc/html/pcre2test.html @@ -159,6 +159,12 @@ Behave as if each pattern has the auto_callout modifier, that is, insert automatic callouts into every pattern that is compiled.

+-AC +As for -ac, but in addition behave as if each subject line has the +callout_extra modifier, that is, show additional information from +callouts. +

+

-b Behave as if each pattern has the fullbincode modifier; the full internal binary form of the pattern is output after compilation. @@ -243,8 +249,8 @@ available, and the use of JIT is verified.

-LM -List modifiers: write a list of available pattern and subject modifiers to the -standard output, then exit with zero exit code. All other options are ignored. +List modifiers: write a list of available pattern and subject modifiers to the +standard output, then exit with zero exit code. All other options are ignored. If both -C and -LM are present, whichever is first is recognized.

@@ -1182,6 +1188,7 @@ pattern. callout_capture show captures at callout time callout_data=<n> set a value to pass via callouts callout_error=<n>[:<m>] control callout error + callout_extra show extra callout information callout_fail=<n>[:<m>] control callout failure callout_no_where do not show position of a callout callout_none do not supply a callout function @@ -1694,49 +1701,10 @@ documentation.
CALLOUTS

If the pattern contains any callout requests, pcre2test's callout -function is called during matching unless callout_none is specified. -This works with both matching functions. -

-

-The callout function in pcre2test returns zero (carry on matching) by -default, but you can use a callout_fail modifier in a subject line to -change this and other parameters of the callout. -

-

-If callout_capture is set, the current captured groups are output when a -callout occurs. By default, the callout function then generates output that -indicates where the current match start and matching points are in the subject, -and what the next pattern item is. This output is suppressed if the -callout_no_where modifier is set. -

-

-The default return from the callout function is zero, which allows matching to -continue. The callout_fail modifier can be given one or two numbers. If -there is only one number, 1 is returned instead of 0 (causing matching to -backtrack) when a callout of that number is reached. If two numbers (<n>:<m>) -are given, 1 is returned when callout <n> is reached and there have been at -least <m> callouts. The callout_error modifier is similar, except that -PCRE2_ERROR_CALLOUT is returned, causing the entire matching process to be -aborted. If both these modifiers are set for the same callout number, -callout_error takes precedence. Note that callouts with string arguments -are always given the number zero. See -

-

-The callout_data modifier can be given an unsigned or a negative number. -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. -

-

-Inserting callouts can be helpful when using pcre2test to check -complicated regular expressions. For further information about callouts, see -the -pcre2callout -documentation. -

-

-The output for callouts with numerical arguments and those with string -arguments is slightly different. +function is called during matching unless callout_none is specified. This +works with both matching functions, and with JIT, though there are some +differences in behaviour. The output for callouts with numerical arguments and +those with string arguments is slightly different.


Callouts with numerical arguments @@ -1811,6 +1779,107 @@ example:

+
+Callout modifiers +
+

+The callout function in pcre2test returns zero (carry on matching) by +default, but you can use a callout_fail modifier in a subject line to +change this and other parameters of the callout (see below). +

+

+If the callout_capture modifier is set, the current captured groups are +output when a callout occurs. This is useful only for non-DFA matching, as +pcre2_dfa_match() does not support capturing, so no captures are ever +shown. +

+

+The normal callout output, showing the callout number or pattern offset (as +described above) is suppressed if the callout_no_where modifier is set. +

+

+When using the interpretive matching function pcre2_match() without JIT, +setting the callout_extra modifier causes additional output from +pcre2test's callout function to be generated. For the first callout in a +match attempt at a new starting position in the subject, "New match attempt" is +output. If there has been a backtrack since the last callout (or start of +matching if this is the first callout), "Backtrack" is output, followed by "No +other matching paths" if the backtrack ended the previous match attempt. For +example: +

+   re> /(a+)b/auto_callout,no_start_optimize,no_auto_possess
+  data> aac\=callout_extra
+  New match attempt
+  --->aac
+   +0 ^       (
+   +1 ^       a+
+   +3 ^ ^     )
+   +4 ^ ^     b
+  Backtrack
+  --->aac
+   +3 ^^      )
+   +4 ^^      b
+  Backtrack
+  No other matching paths
+  New match attempt
+  --->aac
+   +0  ^      (
+   +1  ^      a+
+   +3  ^^     )
+   +4  ^^     b
+  Backtrack
+  No other matching paths
+  New match attempt
+  --->aac
+   +0   ^     (
+   +1   ^     a+
+  Backtrack
+  No other matching paths
+  New match attempt
+  --->aac
+   +0    ^    (
+   +1    ^    a+
+  No match
+
+Notice that various optimizations must be turned off if you want all possible +matching paths to be scanned. If no_start_optimize is not used, there is +an immediate "no match", without any callouts, because the starting +optimization fails to find "b" in the subject, which it knows must be present +for any match. If no_auto_possess is not used, the "a+" item is turned +into "a++", which reduces the number of backtracks. +

+

+The callout_extra modifier has no effect if used with the DFA matching +function, or with JIT. +

+
+Return values from callouts +
+

+The default return from the callout function is zero, which allows matching to +continue. The callout_fail modifier can be given one or two numbers. If +there is only one number, 1 is returned instead of 0 (causing matching to +backtrack) when a callout of that number is reached. If two numbers (<n>:<m>) +are given, 1 is returned when callout <n> is reached and there have been at +least <m> callouts. The callout_error modifier is similar, except that +PCRE2_ERROR_CALLOUT is returned, causing the entire matching process to be +aborted. If both these modifiers are set for the same callout number, +callout_error takes precedence. Note that callouts with string arguments +are always given the number zero. +

+

+The callout_data modifier can be given an unsigned or a negative number. +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. +

+

+Inserting callouts can be helpful when using pcre2test to check +complicated regular expressions. For further information about callouts, see +the +pcre2callout +documentation. +


NON-PRINTING CHARACTERS

When pcre2test is outputting text in the compiled version of a pattern, @@ -1913,7 +1982,7 @@ Cambridge, England.


REVISION

-Last updated: 17 October 2017 +Last updated: 21 December 2017
Copyright © 1997-2017 University of Cambridge.
-- cgit v1.2.1