version 1.1.1.1, 2012/02/21 23:05:52
|
version 1.1.1.2, 2012/02/21 23:50:25
|
Line 14 SYNOPSIS
|
Line 14 SYNOPSIS
|
expressions. This document describes the features of the test program; |
expressions. This document describes the features of the test program; |
for details of the regular expressions themselves, see the pcrepattern |
for details of the regular expressions themselves, see the pcrepattern |
documentation. For details of the PCRE library function calls and their |
documentation. For details of the PCRE library function calls and their |
options, see the pcreapi documentation. The input for pcretest is a | options, see the pcreapi and pcre16 documentation. The input for |
sequence of regular expression patterns and strings to be matched, as | pcretest is a sequence of regular expression patterns and strings to be |
described below. The output shows the result of each match. Options on | matched, as described below. The output shows the result of each match. |
the command line and the patterns control PCRE options and exactly what | Options on the command line and the patterns control PCRE options and |
is output. | exactly what is output. |
|
|
|
|
|
PCRE's 8-BIT and 16-BIT LIBRARIES |
|
|
|
From release 8.30, two separate PCRE libraries can be built. The origi- |
|
nal one supports 8-bit character strings, whereas the newer 16-bit |
|
library supports character strings encoded in 16-bit units. The |
|
pcretest program can be used to test both libraries. However, it is |
|
itself still an 8-bit program, reading 8-bit input and writing 8-bit |
|
output. When testing the 16-bit library, the patterns and data strings |
|
are converted to 16-bit format before being passed to the PCRE library |
|
functions. Results are converted to 8-bit for output. |
|
|
|
References to functions and structures of the form pcre[16]_xx below |
|
mean "pcre_xx when using the 8-bit library or pcre16_xx when using the |
|
16-bit library". |
|
|
|
|
COMMAND LINE OPTIONS |
COMMAND LINE OPTIONS |
|
|
-b Behave as if each pattern has the /B (show byte code) modi- | -16 If both the 8-bit and the 16-bit libraries have been built, |
| this option causes the 16-bit library to be used. If only the |
| 16-bit library has been built, this is the default (so has no |
| effect). If only the 8-bit library has been built, this |
| option causes an error. |
| |
| -b Behave as if each pattern has the /B (show byte code) modi- |
fier; the internal form is output after compilation. |
fier; the internal form is output after compilation. |
|
|
-C Output the version number of the PCRE library, and all avail- |
-C Output the version number of the PCRE library, and all avail- |
able information about the optional features that are | able information about the optional features that are |
included, and then exit. | included, and then exit. All other options are ignored. |
|
|
-d Behave as if each pattern has the /D (debug) modifier; the | -C option Output information about a specific build-time option, then |
internal form and information about the compiled pattern is | exit. This functionality is intended for use in scripts such |
| as RunTest. The following options output the value indicated: |
| |
| linksize the internal link size (2, 3, or 4) |
| newline the default newline setting: |
| CR, LF, CRLF, ANYCRLF, or ANY |
| |
| The following options output 1 for true or zero for false: |
| |
| jit just-in-time support is available |
| pcre16 the 16-bit library was built |
| pcre8 the 8-bit library was built |
| ucp Unicode property support is available |
| utf UTF-8 and/or UTF-16 support is available |
| |
| -d Behave as if each pattern has the /D (debug) modifier; the |
| internal form and information about the compiled pattern is |
output after compilation; -d is equivalent to -b -i. |
output after compilation; -d is equivalent to -b -i. |
|
|
-dfa Behave as if each data line contains the \D escape sequence; | -dfa Behave as if each data line contains the \D escape sequence; |
this causes the alternative matching function, |
this causes the alternative matching function, |
pcre_dfa_exec(), to be used instead of the standard | pcre[16]_dfa_exec(), to be used instead of the standard |
pcre_exec() function (more detail is given below). | pcre[16]_exec() function (more detail is given below). |
|
|
-help Output a brief summary these options and then exit. |
-help Output a brief summary these options and then exit. |
|
|
-i Behave as if each pattern has the /I modifier; information | -i Behave as if each pattern has the /I modifier; information |
about the compiled pattern is given after compilation. |
about the compiled pattern is given after compilation. |
|
|
-M Behave as if each data line contains the \M escape sequence; | -M Behave as if each data line contains the \M escape sequence; |
this causes PCRE to discover the minimum MATCH_LIMIT and | this causes PCRE to discover the minimum MATCH_LIMIT and |
MATCH_LIMIT_RECURSION settings by calling pcre_exec() repeat- | MATCH_LIMIT_RECURSION settings by calling pcre[16]_exec() |
edly with different limits. | repeatedly with different limits. |
|
|
-m Output the size of each compiled pattern after it has been | -m Output the size of each compiled pattern after it has been |
compiled. This is equivalent to adding /M to each regular | compiled. This is equivalent to adding /M to each regular |
expression. | expression. The size is given in bytes for both libraries. |
|
|
-o osize Set the number of elements in the output vector that is used | -o osize Set the number of elements in the output vector that is used |
when calling pcre_exec() or pcre_dfa_exec() to be osize. The | when calling pcre[16]_exec() or pcre[16]_dfa_exec() to be |
default value is 45, which is enough for 14 capturing subex- | osize. The default value is 45, which is enough for 14 cap- |
pressions for pcre_exec() or 22 different matches for | turing subexpressions for pcre[16]_exec() or 22 different |
pcre_dfa_exec(). The vector size can be changed for individ- | matches for pcre[16]_dfa_exec(). The vector size can be |
ual matching calls by including \O in the data line (see | changed for individual matching calls by including \O in the |
below). | data line (see below). |
|
|
-p Behave as if each pattern has the /P modifier; the POSIX | -p Behave as if each pattern has the /P modifier; the POSIX |
wrapper API is used to call PCRE. None of the other options | wrapper API is used to call PCRE. None of the other options |
has any effect when -p is set. | has any effect when -p is set. This option can be used only |
| with the 8-bit library. |
|
|
-q Do not output the version number of pcretest at the start of |
-q Do not output the version number of pcretest at the start of |
execution. |
execution. |
Line 73 COMMAND LINE OPTIONS
|
Line 112 COMMAND LINE OPTIONS
|
|
|
-s or -s+ Behave as if each pattern has the /S modifier; in other |
-s or -s+ Behave as if each pattern has the /S modifier; in other |
words, force each pattern to be studied. If -s+ is used, the |
words, force each pattern to be studied. If -s+ is used, the |
PCRE_STUDY_JIT_COMPILE flag is passed to pcre_study(), caus- | PCRE_STUDY_JIT_COMPILE flag is passed to pcre[16]_study(), |
ing just-in-time optimization to be set up if it is avail- | causing just-in-time optimization to be set up if it is |
able. If the /I or /D option is present on a pattern | available. If the /I or /D option is present on a pattern |
(requesting output about the compiled pattern), information |
(requesting output about the compiled pattern), information |
about the result of studying is not included when studying is |
about the result of studying is not included when studying is |
caused only by -s and neither -i nor -d is present on the |
caused only by -s and neither -i nor -d is present on the |
command line. This behaviour means that the output from tests |
command line. This behaviour means that the output from tests |
that are run with and without -s should be identical, except |
that are run with and without -s should be identical, except |
when options that output information about the actual running |
when options that output information about the actual running |
of a match are set. The -M, -t, and -tm options, which give | of a match are set. |
information about resources used, are likely to produce dif- | |
ferent output with and without -s. Output may also differ if | |
the /C option is present on an individual pattern. This uses | |
callouts to trace the the matching process, and this may be | |
different between studied and non-studied patterns. If the | |
pattern contains (*MARK) items there may also be differences, | |
for the same reason. The -s command line option can be over- | |
ridden for specific patterns that should never be studied | |
(see the /S pattern modifier below). | |
|
|
|
The -M, -t, and -tm options, which give information about |
|
resources used, are likely to produce different output with |
|
and without -s. Output may also differ if the /C option is |
|
present on an individual pattern. This uses callouts to trace |
|
the the matching process, and this may be different between |
|
studied and non-studied patterns. If the pattern contains |
|
(*MARK) items there may also be differences, for the same |
|
reason. The -s command line option can be overridden for spe- |
|
cific patterns that should never be studied (see the /S pat- |
|
tern modifier below). |
|
|
-t Run each compile, study, and match many times with a timer, |
-t Run each compile, study, and match many times with a timer, |
and output resulting time per compile or match (in millisec- |
and output resulting time per compile or match (in millisec- |
onds). Do not set -m with -t, because you will then get the |
onds). Do not set -m with -t, because you will then get the |
Line 173 PATTERN MODIFIERS
|
Line 214 PATTERN MODIFIERS
|
and the first modifier, and between the modifiers themselves. |
and the first modifier, and between the modifiers themselves. |
|
|
The /i, /m, /s, and /x modifiers set the PCRE_CASELESS, PCRE_MULTILINE, |
The /i, /m, /s, and /x modifiers set the PCRE_CASELESS, PCRE_MULTILINE, |
PCRE_DOTALL, or PCRE_EXTENDED options, respectively, when pcre_com- | PCRE_DOTALL, or PCRE_EXTENDED options, respectively, when pcre[16]_com- |
pile() is called. These four modifier letters have the same effect as |
pile() is called. These four modifier letters have the same effect as |
they do in Perl. For example: |
they do in Perl. For example: |
|
|
Line 182 PATTERN MODIFIERS
|
Line 223 PATTERN MODIFIERS
|
The following table shows additional modifiers for setting PCRE com- |
The following table shows additional modifiers for setting PCRE com- |
pile-time options that do not correspond to anything in Perl: |
pile-time options that do not correspond to anything in Perl: |
|
|
/8 PCRE_UTF8 | /8 PCRE_UTF8 ) when using the 8-bit |
/? PCRE_NO_UTF8_CHECK | /? PCRE_NO_UTF8_CHECK ) library |
| |
| /8 PCRE_UTF16 ) when using the 16-bit |
| /? PCRE_NO_UTF16_CHECK ) library |
| |
/A PCRE_ANCHORED |
/A PCRE_ANCHORED |
/C PCRE_AUTO_CALLOUT |
/C PCRE_AUTO_CALLOUT |
/E PCRE_DOLLAR_ENDONLY |
/E PCRE_DOLLAR_ENDONLY |
Line 210 PATTERN MODIFIERS
|
Line 255 PATTERN MODIFIERS
|
|
|
/^abc/m<CRLF> |
/^abc/m<CRLF> |
|
|
As well as turning on the PCRE_UTF8 option, the /8 modifier also causes | As well as turning on the PCRE_UTF8/16 option, the /8 modifier causes |
any non-printing characters in output strings to be printed using the | all non-printing characters in output strings to be printed using the |
\x{hh...} notation if they are valid UTF-8 sequences. Full details of | \x{hh...} notation. Otherwise, those less than 0x100 are output in hex |
the PCRE options are given in the pcreapi documentation. | without the curly brackets. |
|
|
|
Full details of the PCRE options are given in the pcreapi documenta- |
|
tion. |
|
|
Finding all matches in a string |
Finding all matches in a string |
|
|
Searching for all possible matches within each subject string can be | Searching for all possible matches within each subject string can be |
requested by the /g or /G modifier. After finding a match, PCRE is | requested by the /g or /G modifier. After finding a match, PCRE is |
called again to search the remainder of the subject string. The differ- |
called again to search the remainder of the subject string. The differ- |
ence between /g and /G is that the former uses the startoffset argument |
ence between /g and /G is that the former uses the startoffset argument |
to pcre_exec() to start searching at a new point within the entire | to pcre[16]_exec() to start searching at a new point within the entire |
string (which is in effect what Perl does), whereas the latter passes | string (which is in effect what Perl does), whereas the latter passes |
over a shortened substring. This makes a difference to the matching | over a shortened substring. This makes a difference to the matching |
process if the pattern begins with a lookbehind assertion (including \b |
process if the pattern begins with a lookbehind assertion (including \b |
or \B). |
or \B). |
|
|
If any call to pcre_exec() in a /g or /G sequence matches an empty | If any call to pcre[16]_exec() in a /g or /G sequence matches an empty |
string, the next call is done with the PCRE_NOTEMPTY_ATSTART and | string, the next call is done with the PCRE_NOTEMPTY_ATSTART and |
PCRE_ANCHORED flags set in order to search for another, non-empty, | PCRE_ANCHORED flags set in order to search for another, non-empty, |
match at the same point. If this second match fails, the start offset | match at the same point. If this second match fails, the start offset |
is advanced, and the normal match is retried. This imitates the way | is advanced, and the normal match is retried. This imitates the way |
Perl handles such cases when using the /g modifier or the split() func- |
Perl handles such cases when using the /g modifier or the split() func- |
tion. Normally, the start offset is advanced by one character, but if | tion. Normally, the start offset is advanced by one character, but if |
the newline convention recognizes CRLF as a newline, and the current | the newline convention recognizes CRLF as a newline, and the current |
character is CR followed by LF, an advance of two is used. |
character is CR followed by LF, an advance of two is used. |
|
|
Other modifiers |
Other modifiers |
|
|
There are yet more modifiers for controlling the way pcretest operates. |
There are yet more modifiers for controlling the way pcretest operates. |
|
|
The /+ modifier requests that as well as outputting the substring that | The /+ modifier requests that as well as outputting the substring that |
matched the entire pattern, pcretest should in addition output the | matched the entire pattern, pcretest should in addition output the |
remainder of the subject string. This is useful for tests where the | remainder of the subject string. This is useful for tests where the |
subject contains multiple copies of the same substring. If the + modi- | subject contains multiple copies of the same substring. If the + modi- |
fier appears twice, the same action is taken for captured substrings. | fier appears twice, the same action is taken for captured substrings. |
In each case the remainder is output on the following line with a plus | In each case the remainder is output on the following line with a plus |
character following the capture number. Note that this modifier must | character following the capture number. Note that this modifier must |
not immediately follow the /S modifier because /S+ has another meaning. |
not immediately follow the /S modifier because /S+ has another meaning. |
|
|
The /= modifier requests that the values of all potential captured | The /= modifier requests that the values of all potential captured |
parentheses be output after a match by pcre_exec(). By default, only | parentheses be output after a match. By default, only those up to the |
those up to the highest one actually used in the match are output (cor- | highest one actually used in the match are output (corresponding to the |
responding to the return code from pcre_exec()). Values in the offsets | return code from pcre[16]_exec()). Values in the offsets vector corre- |
vector corresponding to higher numbers should be set to -1, and these | sponding to higher numbers should be set to -1, and these are output as |
are output as "<unset>". This modifier gives a way of checking that | "<unset>". This modifier gives a way of checking that this is happen- |
this is happening. | ing. |
|
|
The /B modifier is a debugging feature. It requests that pcretest out- | The /B modifier is a debugging feature. It requests that pcretest out- |
put a representation of the compiled byte code after compilation. Nor- | put a representation of the compiled code after compilation. Normally |
mally this information contains length and offset values; however, if | this information contains length and offset values; however, if /Z is |
/Z is also present, this data is replaced by spaces. This is a special | also present, this data is replaced by spaces. This is a special fea- |
feature for use in the automatic test scripts; it ensures that the same | ture for use in the automatic test scripts; it ensures that the same |
output is generated for different internal link sizes. |
output is generated for different internal link sizes. |
|
|
The /D modifier is a PCRE debugging feature, and is equivalent to /BI, | The /D modifier is a PCRE debugging feature, and is equivalent to /BI, |
that is, both the /B and the /I modifiers. |
that is, both the /B and the /I modifiers. |
|
|
The /F modifier causes pcretest to flip the byte order of the fields in | The /F modifier causes pcretest to flip the byte order of the 2-byte |
the compiled pattern that contain 2-byte and 4-byte numbers. This | and 4-byte fields in the compiled pattern. This facility is for testing |
facility is for testing the feature in PCRE that allows it to execute | the feature in PCRE that allows it to execute patterns that were com- |
patterns that were compiled on a host with a different endianness. This | piled on a host with a different endianness. This feature is not avail- |
feature is not available when the POSIX interface to PCRE is being | able when the POSIX interface to PCRE is being used, that is, when the |
used, that is, when the /P pattern modifier is specified. See also the | /P pattern modifier is specified. See also the section about saving and |
section about saving and reloading compiled patterns below. | reloading compiled patterns below. |
|
|
The /I modifier requests that pcretest output information about the | The /I modifier requests that pcretest output information about the |
compiled pattern (whether it is anchored, has a fixed first character, | compiled pattern (whether it is anchored, has a fixed first character, |
and so on). It does this by calling pcre_fullinfo() after compiling a | and so on). It does this by calling pcre[16]_fullinfo() after compiling |
pattern. If the pattern is studied, the results of that are also out- | a pattern. If the pattern is studied, the results of that are also out- |
put. |
put. |
|
|
The /K modifier requests pcretest to show names from backtracking con- | The /K modifier requests pcretest to show names from backtracking con- |
trol verbs that are returned from calls to pcre_exec(). It causes | trol verbs that are returned from calls to pcre[16]_exec(). It causes |
pcretest to create a pcre_extra block if one has not already been cre- | pcretest to create a pcre[16]_extra block if one has not already been |
ated by a call to pcre_study(), and to set the PCRE_EXTRA_MARK flag and | created by a call to pcre[16]_study(), and to set the PCRE_EXTRA_MARK |
the mark field within it, every time that pcre_exec() is called. If the | flag and the mark field within it, every time that pcre[16]_exec() is |
variable that the mark field points to is non-NULL for a match, non- | called. If the variable that the mark field points to is non-NULL for a |
match, or partial match, pcretest prints the string to which it points. | match, non-match, or partial match, pcretest prints the string to which |
For a match, this is shown on a line by itself, tagged with "MK:". For | it points. For a match, this is shown on a line by itself, tagged with |
a non-match it is added to the message. | "MK:". For a non-match it is added to the message. |
|
|
The /L modifier must be followed directly by the name of a locale, for | The /L modifier must be followed directly by the name of a locale, for |
example, |
example, |
|
|
/pattern/Lfr_FR |
/pattern/Lfr_FR |
|
|
For this reason, it must be the last modifier. The given locale is set, |
For this reason, it must be the last modifier. The given locale is set, |
pcre_maketables() is called to build a set of character tables for the | pcre[16]_maketables() is called to build a set of character tables for |
locale, and this is then passed to pcre_compile() when compiling the | the locale, and this is then passed to pcre[16]_compile() when compil- |
regular expression. Without an /L (or /T) modifier, NULL is passed as | ing the regular expression. Without an /L (or /T) modifier, NULL is |
the tables pointer; that is, /L applies only to the expression on which | passed as the tables pointer; that is, /L applies only to the expres- |
it appears. | sion on which it appears. |
|
|
The /M modifier causes the size of memory block used to hold the com- | The /M modifier causes the size in bytes of the memory block used to |
piled pattern to be output. This does not include the size of the pcre | hold the compiled pattern to be output. This does not include the size |
block; it is just the actual compiled data. If the pattern is success- | of the pcre[16] block; it is just the actual compiled data. If the pat- |
fully studied with the PCRE_STUDY_JIT_COMPILE option, the size of the | tern is successfully studied with the PCRE_STUDY_JIT_COMPILE option, |
JIT compiled code is also output. | the size of the JIT compiled code is also output. |
|
|
If the /S modifier appears once, it causes pcre_study() to be called | If the /S modifier appears once, it causes pcre[16]_study() to be |
after the expression has been compiled, and the results used when the | called after the expression has been compiled, and the results used |
expression is matched. If /S appears twice, it suppresses studying, | when the expression is matched. If /S appears twice, it suppresses |
even if it was requested externally by the -s command line option. This | studying, even if it was requested externally by the -s command line |
makes it possible to specify that certain patterns are always studied, | option. This makes it possible to specify that certain patterns are |
and others are never studied, independently of -s. This feature is used | always studied, and others are never studied, independently of -s. This |
in the test files in a few cases where the output is different when the | feature is used in the test files in a few cases where the output is |
pattern is studied. | different when the pattern is studied. |
|
|
If the /S modifier is immediately followed by a + character, the call | If the /S modifier is immediately followed by a + character, the call |
to pcre_study() is made with the PCRE_STUDY_JIT_COMPILE option, | to pcre[16]_study() is made with the PCRE_STUDY_JIT_COMPILE option, |
requesting just-in-time optimization support if it is available. Note | requesting just-in-time optimization support if it is available. Note |
that there is also a /+ modifier; it must not be given immediately | that there is also a /+ modifier; it must not be given immediately |
after /S because this will be misinterpreted. If JIT studying is suc- | after /S because this will be misinterpreted. If JIT studying is suc- |
cessful, it will automatically be used when pcre_exec() is run, except | cessful, it will automatically be used when pcre[16]_exec() is run, |
when incompatible run-time options are specified. These include the | except when incompatible run-time options are specified. These include |
partial matching options; a complete list is given in the pcrejit docu- | the partial matching options; a complete list is given in the pcrejit |
mentation. See also the \J escape sequence below for a way of setting | documentation. See also the \J escape sequence below for a way of set- |
the size of the JIT stack. | ting the size of the JIT stack. |
|
|
The /T modifier must be followed by a single digit. It causes a spe- | The /T modifier must be followed by a single digit. It causes a spe- |
cific set of built-in character tables to be passed to pcre_compile(). | cific set of built-in character tables to be passed to pcre[16]_com- |
It is used in the standard PCRE tests to check behaviour with different | pile(). It is used in the standard PCRE tests to check behaviour with |
character tables. The digit specifies the tables as follows: | different character tables. The digit specifies the tables as follows: |
|
|
0 the default ASCII tables, as distributed in |
0 the default ASCII tables, as distributed in |
pcre_chartables.c.dist |
pcre_chartables.c.dist |
1 a set of tables defining ISO 8859 characters |
1 a set of tables defining ISO 8859 characters |
|
|
In table 1, some characters whose codes are greater than 128 are iden- | In table 1, some characters whose codes are greater than 128 are iden- |
tified as letters, digits, spaces, etc. |
tified as letters, digits, spaces, etc. |
|
|
Using the POSIX wrapper API |
Using the POSIX wrapper API |
|
|
The /P modifier causes pcretest to call PCRE via the POSIX wrapper API | The /P modifier causes pcretest to call PCRE via the POSIX wrapper API |
rather than its native API. When /P is set, the following modifiers set | rather than its native API. This supports only the 8-bit library. When |
options for the regcomp() function: | /P is set, the following modifiers set options for the regcomp() func- |
| tion: |
|
|
/i REG_ICASE |
/i REG_ICASE |
/m REG_NEWLINE |
/m REG_NEWLINE |
Line 362 PATTERN MODIFIERS
|
Line 411 PATTERN MODIFIERS
|
|
|
DATA LINES |
DATA LINES |
|
|
Before each data line is passed to pcre_exec(), leading and trailing | Before each data line is passed to pcre[16]_exec(), leading and trail- |
white space is removed, and it is then scanned for \ escapes. Some of | ing white space is removed, and it is then scanned for \ escapes. Some |
these are pretty esoteric features, intended for checking out some of | of these are pretty esoteric features, intended for checking out some |
the more complicated features of PCRE. If you are just testing "ordi- | of the more complicated features of PCRE. If you are just testing |
nary" regular expressions, you probably don't need any of these. The | "ordinary" regular expressions, you probably don't need any of these. |
following escapes are recognized: | The following escapes are recognized: |
|
|
\a alarm (BEL, \x07) |
\a alarm (BEL, \x07) |
\b backspace (\x08) |
\b backspace (\x08) |
Line 379 DATA LINES
|
Line 428 DATA LINES
|
\r carriage return (\x0d) |
\r carriage return (\x0d) |
\t tab (\x09) |
\t tab (\x09) |
\v vertical tab (\x0b) |
\v vertical tab (\x0b) |
\nnn octal character (up to 3 octal digits) | \nnn octal character (up to 3 octal digits); always |
always a byte unless > 255 in UTF-8 mode | a byte unless > 255 in UTF-8 or 16-bit mode |
\xhh hexadecimal byte (up to 2 hex digits) |
\xhh hexadecimal byte (up to 2 hex digits) |
\x{hh...} hexadecimal character, any number of digits | \x{hh...} hexadecimal character (any number of hex digits) |
in UTF-8 mode | \A pass the PCRE_ANCHORED option to pcre[16]_exec() |
\A pass the PCRE_ANCHORED option to pcre_exec() | or pcre[16]_dfa_exec() |
or pcre_dfa_exec() | \B pass the PCRE_NOTBOL option to pcre[16]_exec() |
\B pass the PCRE_NOTBOL option to pcre_exec() | or pcre[16]_dfa_exec() |
or pcre_dfa_exec() | \Cdd call pcre[16]_copy_substring() for substring dd |
\Cdd call pcre_copy_substring() for substring dd | |
after a successful match (number less than 32) |
after a successful match (number less than 32) |
\Cname call pcre_copy_named_substring() for substring | \Cname call pcre[16]_copy_named_substring() for substring |
"name" after a successful match (name termin- |
"name" after a successful match (name termin- |
ated by next non alphanumeric character) |
ated by next non alphanumeric character) |
\C+ show the current captured substrings at callout |
\C+ show the current captured substrings at callout |
Line 402 DATA LINES
|
Line 450 DATA LINES
|
reached for the nth time |
reached for the nth time |
\C*n pass the number n (may be negative) as callout |
\C*n pass the number n (may be negative) as callout |
data; this is used as the callout return value |
data; this is used as the callout return value |
\D use the pcre_dfa_exec() match function | \D use the pcre[16]_dfa_exec() match function |
\F only shortest match for pcre_dfa_exec() | \F only shortest match for pcre[16]_dfa_exec() |
\Gdd call pcre_get_substring() for substring dd | \Gdd call pcre[16]_get_substring() for substring dd |
after a successful match (number less than 32) |
after a successful match (number less than 32) |
\Gname call pcre_get_named_substring() for substring | \Gname call pcre[16]_get_named_substring() for substring |
"name" after a successful match (name termin- |
"name" after a successful match (name termin- |
ated by next non-alphanumeric character) |
ated by next non-alphanumeric character) |
\Jdd set up a JIT stack of dd kilobytes maximum (any |
\Jdd set up a JIT stack of dd kilobytes maximum (any |
number of digits) |
number of digits) |
\L call pcre_get_substringlist() after a | \L call pcre[16]_get_substringlist() after a |
successful match |
successful match |
\M discover the minimum MATCH_LIMIT and |
\M discover the minimum MATCH_LIMIT and |
MATCH_LIMIT_RECURSION settings |
MATCH_LIMIT_RECURSION settings |
\N pass the PCRE_NOTEMPTY option to pcre_exec() | \N pass the PCRE_NOTEMPTY option to pcre[16]_exec() |
or pcre_dfa_exec(); if used twice, pass the | or pcre[16]_dfa_exec(); if used twice, pass the |
PCRE_NOTEMPTY_ATSTART option |
PCRE_NOTEMPTY_ATSTART option |
\Odd set the size of the output vector passed to |
\Odd set the size of the output vector passed to |
pcre_exec() to dd (any number of digits) | pcre[16]_exec() to dd (any number of digits) |
\P pass the PCRE_PARTIAL_SOFT option to pcre_exec() | \P pass the PCRE_PARTIAL_SOFT option to pcre[16]_exec() |
or pcre_dfa_exec(); if used twice, pass the | or pcre[16]_dfa_exec(); if used twice, pass the |
PCRE_PARTIAL_HARD option |
PCRE_PARTIAL_HARD option |
\Qdd set the PCRE_MATCH_LIMIT_RECURSION limit to dd |
\Qdd set the PCRE_MATCH_LIMIT_RECURSION limit to dd |
(any number of digits) |
(any number of digits) |
\R pass the PCRE_DFA_RESTART option to pcre_dfa_exec() | \R pass the PCRE_DFA_RESTART option to pcre[16]_dfa_exec() |
\S output details of memory get/free calls during matching |
\S output details of memory get/free calls during matching |
\Y pass the PCRE_NO_START_OPTIMIZE option to pcre_exec() | \Y pass the PCRE_NO_START_OPTIMIZE option to pcre[16]_exec() |
or pcre_dfa_exec() | or pcre[16]_dfa_exec() |
\Z pass the PCRE_NOTEOL option to pcre_exec() | \Z pass the PCRE_NOTEOL option to pcre[16]_exec() |
or pcre_dfa_exec() | or pcre[16]_dfa_exec() |
\? pass the PCRE_NO_UTF8_CHECK option to | \? pass the PCRE_NO_UTF[8|16]_CHECK option to |
pcre_exec() or pcre_dfa_exec() | pcre[16]_exec() or pcre[16]_dfa_exec() |
\>dd start the match at offset dd (optional "-"; then |
\>dd start the match at offset dd (optional "-"; then |
any number of digits); this sets the startoffset |
any number of digits); this sets the startoffset |
argument for pcre_exec() or pcre_dfa_exec() | argument for pcre[16]_exec() or pcre[16]_dfa_exec() |
\<cr> pass the PCRE_NEWLINE_CR option to pcre_exec() | \<cr> pass the PCRE_NEWLINE_CR option to pcre[16]_exec() |
or pcre_dfa_exec() | or pcre[16]_dfa_exec() |
\<lf> pass the PCRE_NEWLINE_LF option to pcre_exec() | \<lf> pass the PCRE_NEWLINE_LF option to pcre[16]_exec() |
or pcre_dfa_exec() | or pcre[16]_dfa_exec() |
\<crlf> pass the PCRE_NEWLINE_CRLF option to pcre_exec() | \<crlf> pass the PCRE_NEWLINE_CRLF option to pcre[16]_exec() |
or pcre_dfa_exec() | or pcre[16]_dfa_exec() |
\<anycrlf> pass the PCRE_NEWLINE_ANYCRLF option to pcre_exec() | \<anycrlf> pass the PCRE_NEWLINE_ANYCRLF option to pcre[16]_exec() |
or pcre_dfa_exec() | or pcre[16]_dfa_exec() |
\<any> pass the PCRE_NEWLINE_ANY option to pcre_exec() | \<any> pass the PCRE_NEWLINE_ANY option to pcre[16]_exec() |
or pcre_dfa_exec() | or pcre[16]_dfa_exec() |
|
|
Note that \xhh always specifies one byte, even in UTF-8 mode; this | The use of \x{hh...} is not dependent on the use of the /8 modifier on |
makes it possible to construct invalid UTF-8 sequences for testing pur- | the pattern. It is recognized always. There may be any number of hexa- |
poses. On the other hand, \x{hh} is interpreted as a UTF-8 character in | decimal digits inside the braces; invalid values provoke error mes- |
UTF-8 mode, generating more than one byte if the value is greater than | sages. |
127. When not in UTF-8 mode, it generates one byte for values less than | |
256, and causes an error for greater values. | |
|
|
The escapes that specify line ending sequences are literal strings, | 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. |
| |
| The escapes that specify line ending sequences are literal strings, |
exactly as shown. No more than one newline setting should be present in |
exactly as shown. No more than one newline setting should be present in |
any data line. |
any data line. |
|
|
A backslash followed by anything else just escapes the anything else. | A backslash followed by anything else just escapes the anything else. |
If the very last character is a backslash, it is ignored. This gives a | If the very last character is a backslash, it is ignored. This gives a |
way of passing an empty line as data, since a real empty line termi- | way of passing an empty line as data, since a real empty line termi- |
nates the data input. |
nates the data input. |
|
|
The \J escape provides a way of setting the maximum stack size that is | The \J escape provides a way of setting the maximum stack size that is |
used by the just-in-time optimization code. It is ignored if JIT opti- | used by the just-in-time optimization code. It is ignored if JIT opti- |
mization is not being used. Providing a stack that is larger than the | mization is not being used. Providing a stack that is larger than the |
default 32K is necessary only for very complicated patterns. |
default 32K is necessary only for very complicated patterns. |
|
|
If \M is present, pcretest calls pcre_exec() several times, with dif- | If \M is present, pcretest calls pcre[16]_exec() several times, with |
ferent values in the match_limit and match_limit_recursion fields of | different values in the match_limit and match_limit_recursion fields of |
the pcre_extra data structure, until it finds the minimum numbers for | the pcre[16]_extra data structure, until it finds the minimum numbers |
each parameter that allow pcre_exec() to complete without error. | for each parameter that allow pcre[16]_exec() to complete without |
Because this is testing a specific feature of the normal interpretive | error. Because this is testing a specific feature of the normal inter- |
pcre_exec() execution, the use of any JIT optimization that might have | pretive pcre[16]_exec() execution, the use of any JIT optimization that |
been set up by the /S+ qualifier of -s+ option is disabled. | might have been set up by the /S+ qualifier of -s+ option is disabled. |
|
|
The match_limit number is a measure of the amount of backtracking that | The match_limit number is a measure of the amount of backtracking that |
takes place, and checking it out can be instructive. For most simple | takes place, and checking it out can be instructive. For most simple |
matches, the number is quite small, but for patterns with very large | matches, the number is quite small, but for patterns with very large |
numbers of matching possibilities, it can become large very quickly | numbers of matching possibilities, it can become large very quickly |
with increasing length of subject string. The match_limit_recursion | with increasing length of subject string. The match_limit_recursion |
number is a measure of how much stack (or, if PCRE is compiled with | number is a measure of how much stack (or, if PCRE is compiled with |
NO_RECURSE, how much heap) memory is needed to complete the match | NO_RECURSE, how much heap) memory is needed to complete the match |
attempt. |
attempt. |
|
|
When \O is used, the value specified may be higher or lower than the | When \O is used, the value specified may be higher or lower than the |
size set by the -O command line option (or defaulted to 45); \O applies |
size set by the -O command line option (or defaulted to 45); \O applies |
only to the call of pcre_exec() for the line in which it appears. | only to the call of pcre[16]_exec() for the line in which it appears. |
|
|
If the /P modifier was present on the pattern, causing the POSIX wrap- | If the /P modifier was present on the pattern, causing the POSIX wrap- |
per API to be used, the only option-setting sequences that have any | per API to be used, the only option-setting sequences that have any |
effect are \B, \N, and \Z, causing REG_NOTBOL, REG_NOTEMPTY, and | effect are \B, \N, and \Z, causing REG_NOTBOL, REG_NOTEMPTY, and |
REG_NOTEOL, respectively, to be passed to regexec(). |
REG_NOTEOL, respectively, to be passed to regexec(). |
|
|
The use of \x{hh...} to represent UTF-8 characters is not dependent on |
|
the use of the /8 modifier on the pattern. It is recognized always. |
|
There may be any number of hexadecimal digits inside the braces. The |
|
result is from one to six bytes, encoded according to the original |
|
UTF-8 rules of RFC 2279. This allows for values in the range 0 to |
|
0x7FFFFFFF. Note that not all of those are valid Unicode code points, |
|
or indeed valid UTF-8 characters according to the later rules in RFC |
|
3629. |
|
|
|
|
|
THE ALTERNATIVE MATCHING FUNCTION |
THE ALTERNATIVE MATCHING FUNCTION |
|
|
By default, pcretest uses the standard PCRE matching function, |
By default, pcretest uses the standard PCRE matching function, |
pcre_exec() to match each data line. From release 6.0, PCRE supports an | pcre[16]_exec() to match each data line. PCRE also supports an alterna- |
alternative matching function, pcre_dfa_test(), which operates in a | tive matching function, pcre[16]_dfa_test(), which operates in a dif- |
different way, and has some restrictions. The differences between the | ferent way, and has some restrictions. The differences between the two |
two functions are described in the pcrematching documentation. | functions are described in the pcrematching documentation. |
|
|
If a data line contains the \D escape sequence, or if the command line |
If a data line contains the \D escape sequence, or if the command line |
contains the -dfa option, the alternative matching function is called. | contains the -dfa option, the alternative matching function is used. |
This function finds all possible matches at a given point. If, however, |
This function finds all possible matches at a given point. If, however, |
the \F escape sequence is present in the data line, it stops after the |
the \F escape sequence is present in the data line, it stops after the |
first match is found. This is always the shortest possible match. |
first match is found. This is always the shortest possible match. |
Line 522 THE ALTERNATIVE MATCHING FUNCTION
|
Line 570 THE ALTERNATIVE MATCHING FUNCTION
|
DEFAULT OUTPUT FROM PCRETEST |
DEFAULT OUTPUT FROM PCRETEST |
|
|
This section describes the output when the normal matching function, |
This section describes the output when the normal matching function, |
pcre_exec(), is being used. | pcre[16]_exec(), is being used. |
|
|
When a match succeeds, pcretest outputs the list of captured substrings |
When a match succeeds, pcretest outputs the list of captured substrings |
that pcre_exec() returns, starting with number 0 for the string that | that pcre[16]_exec() returns, starting with number 0 for the string |
matched the whole pattern. Otherwise, it outputs "No match" when the | that matched the whole pattern. Otherwise, it outputs "No match" when |
return is PCRE_ERROR_NOMATCH, and "Partial match:" followed by the par- | the return is PCRE_ERROR_NOMATCH, and "Partial match:" followed by the |
tially matching substring when pcre_exec() returns PCRE_ERROR_PARTIAL. | partially matching substring when pcre[16]_exec() returns |
(Note that this is the entire substring that was inspected during the | PCRE_ERROR_PARTIAL. (Note that this is the entire substring that was |
partial match; it may include characters before the actual match start | inspected during the partial match; it may include characters before |
if a lookbehind assertion, \K, \b, or \B was involved.) For any other | the actual match start if a lookbehind assertion, \K, \b, or \B was |
return, pcretest outputs the PCRE negative error number and a short | involved.) For any other return, pcretest outputs the PCRE negative |
descriptive phrase. If the error is a failed UTF-8 string check, the | error number and a short descriptive phrase. If the error is a failed |
byte offset of the start of the failing character and the reason code | UTF string check, the offset of the start of the failing character and |
are also output, provided that the size of the output vector is at | the reason code are also output, provided that the size of the output |
least two. Here is an example of an interactive pcretest run. | vector is at least two. Here is an example of an interactive pcretest |
| run. |
|
|
$ pcretest |
$ pcretest |
PCRE version 8.13 2011-04-30 |
PCRE version 8.13 2011-04-30 |
Line 549 DEFAULT OUTPUT FROM PCRETEST
|
Line 598 DEFAULT OUTPUT FROM PCRETEST
|
No match |
No match |
|
|
Unset capturing substrings that are not followed by one that is set are |
Unset capturing substrings that are not followed by one that is set are |
not returned by pcre_exec(), and are not shown by pcretest. In the fol- | not returned by pcre[16]_exec(), and are not shown by pcretest. In the |
lowing example, there are two capturing substrings, but when the first | following example, there are two capturing substrings, but when the |
data line is matched, the second, unset substring is not shown. An | first data line is matched, the second, unset substring is not shown. |
"internal" unset substring is shown as "<unset>", as for the second | An "internal" unset substring is shown as "<unset>", as for the second |
data line. |
data line. |
|
|
re> /(a)|(b)/ |
re> /(a)|(b)/ |
Line 564 DEFAULT OUTPUT FROM PCRETEST
|
Line 613 DEFAULT OUTPUT FROM PCRETEST
|
1: <unset> |
1: <unset> |
2: b |
2: b |
|
|
If the strings contain any non-printing characters, they are output as | If the strings contain any non-printing characters, they are output as |
\0x escapes, or as \x{...} escapes if the /8 modifier was present on | \xhh escapes if the value is less than 256 and UTF mode is not set. |
the pattern. See below for the definition of non-printing characters. | Otherwise they are output as \x{hh...} escapes. See below for the defi- |
If the pattern has the /+ modifier, the output for substring 0 is fol- | nition of non-printing characters. If the pattern has the /+ modifier, |
lowed by the the rest of the subject string, identified by "0+" like | the output for substring 0 is followed by the the rest of the subject |
this: | string, identified by "0+" like this: |
|
|
re> /cat/+ |
re> /cat/+ |
data> cataract |
data> cataract |
0: cat |
0: cat |
0+ aract |
0+ aract |
|
|
If the pattern has the /g or /G modifier, the results of successive | If the pattern has the /g or /G modifier, the results of successive |
matching attempts are output in sequence, like this: |
matching attempts are output in sequence, like this: |
|
|
re> /\Bi(\w\w)/g |
re> /\Bi(\w\w)/g |
Line 588 DEFAULT OUTPUT FROM PCRETEST
|
Line 637 DEFAULT OUTPUT FROM PCRETEST
|
0: ipp |
0: ipp |
1: pp |
1: pp |
|
|
"No match" is output only if the first match attempt fails. Here is an | "No match" is output only if the first match attempt fails. Here is an |
example of a failure message (the offset 4 that is specified by \>4 is | example of a failure message (the offset 4 that is specified by \>4 is |
past the end of the subject string): |
past the end of the subject string): |
|
|
re> /xyz/ |
re> /xyz/ |
data> xyz\>4 |
data> xyz\>4 |
Error -24 (bad offset value) |
Error -24 (bad offset value) |
|
|
If any of the sequences \C, \G, or \L are present in a data line that | If any of the sequences \C, \G, or \L are present in a data line that |
is successfully matched, the substrings extracted by the convenience | is successfully matched, the substrings extracted by the convenience |
functions are output with C, G, or L after the string number instead of |
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 |
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 paren- | (that is, the return from the extraction function) is given in paren- |
theses after each string for \C and \G. |
theses after each string for \C and \G. |
|
|
Note that whereas patterns can be continued over several lines (a plain |
Note that whereas patterns can be continued over several lines (a plain |
">" prompt is used for continuations), data lines may not. However new- |
">" prompt is used for continuations), data lines may not. However new- |
lines can be included in data by means of the \n escape (or \r, \r\n, | lines can be included in data by means of the \n escape (or \r, \r\n, |
etc., depending on the newline sequence setting). |
etc., depending on the newline sequence setting). |
|
|
|
|
OUTPUT FROM THE ALTERNATIVE MATCHING FUNCTION |
OUTPUT FROM THE ALTERNATIVE MATCHING FUNCTION |
|
|
When the alternative matching function, pcre_dfa_exec(), is used (by | When the alternative matching function, pcre[16]_dfa_exec(), is used |
means of the \D escape sequence or the -dfa command line option), the | (by means of the \D escape sequence or the -dfa command line option), |
output consists of a list of all the matches that start at the first | the output consists of a list of all the matches that start at the |
point in the subject where there is at least one match. For example: | first point in the subject where there is at least one match. For exam- |
| ple: |
|
|
re> /(tang|tangerine|tan)/ |
re> /(tang|tangerine|tan)/ |
data> yellow tangerine\D |
data> yellow tangerine\D |
Line 670 CALLOUTS
|
Line 720 CALLOUTS
|
tion is called during matching. This works with both matching func- |
tion is called during matching. This works with both matching func- |
tions. By default, the called function displays the callout number, the |
tions. By default, the called function displays the callout number, the |
start and current positions in the text at the callout time, and the |
start and current positions in the text at the callout time, and the |
next pattern item to be tested. For example, the output | next pattern item to be tested. For example: |
|
|
--->pqrabcdef |
--->pqrabcdef |
0 ^ ^ \d |
0 ^ ^ \d |
|
|
indicates that callout number 0 occurred for a match attempt starting | This output indicates that callout number 0 occurred for a match |
at the fourth character of the subject string, when the pointer was at | attempt starting at the fourth character of the subject string, when |
the seventh character of the data, and when the next pattern item was | the pointer was at the seventh character of the data, and when the next |
\d. Just one circumflex is output if the start and current positions | pattern item was \d. Just one circumflex is output if the start and |
are the same. | current positions are the same. |
|
|
Callouts numbered 255 are assumed to be automatic callouts, inserted as |
Callouts numbered 255 are assumed to be automatic callouts, inserted as |
a result of the /C pattern modifier. In this case, instead of showing |
a result of the /C pattern modifier. In this case, instead of showing |
Line 779 SAVING AND RELOADING COMPILED PATTERNS
|
Line 829 SAVING AND RELOADING COMPILED PATTERNS
|
You can copy a file written by pcretest to a different host and reload |
You can copy a file written by pcretest to a different host and reload |
it there, even if the new host has opposite endianness to the one on |
it there, even if the new host has opposite endianness to the one on |
which the pattern was compiled. For example, you can compile on an i86 |
which the pattern was compiled. For example, you can compile on an i86 |
machine and run on a SPARC machine. | machine and run on a SPARC machine. When a pattern is reloaded on a |
| host with different endianness, the confirmation message is changed to: |
|
|
File names for saving and reloading can be absolute or relative, but | Compiled pattern (byte-inverted) loaded from /some/file |
note that the shell facility of expanding a file name that starts with | |
| The test suite contains some saved pre-compiled patterns with different |
| endianness. These are reloaded using "<!" instead of just "<". This |
| suppresses the "(byte-inverted)" text so that the output is the same on |
| all hosts. It also forces debugging output once the pattern has been |
| reloaded. |
| |
| File names for saving and reloading can be absolute or relative, but |
| note that the shell facility of expanding a file name that starts with |
a tilde (~) is not available. |
a tilde (~) is not available. |
|
|
The ability to save and reload files in pcretest is intended for test- | The ability to save and reload files in pcretest is intended for test- |
ing and experimentation. It is not intended for production use because | ing and experimentation. It is not intended for production use because |
only a single pattern can be written to a file. Furthermore, there is | only a single pattern can be written to a file. Furthermore, there is |
no facility for supplying custom character tables for use with a | no facility for supplying custom character tables for use with a |
reloaded pattern. If the original pattern was compiled with custom | reloaded pattern. If the original pattern was compiled with custom |
tables, an attempt to match a subject string using a reloaded pattern | tables, an attempt to match a subject string using a reloaded pattern |
is likely to cause pcretest to crash. Finally, if you attempt to load | is likely to cause pcretest to crash. Finally, if you attempt to load |
a file that is not in the correct format, the result is undefined. |
a file that is not in the correct format, the result is undefined. |
|
|
|
|
SEE ALSO |
SEE ALSO |
|
|
pcre(3), pcreapi(3), pcrecallout(3), pcrejit, pcrematching(3), pcrepar- | pcre(3), pcre16(3), pcreapi(3), pcrecallout(3), pcrejit, pcrematch- |
tial(d), pcrepattern(3), pcreprecompile(3). | ing(3), pcrepartial(d), pcrepattern(3), pcreprecompile(3). |
|
|
|
|
AUTHOR |
AUTHOR |
Line 810 AUTHOR
|
Line 869 AUTHOR
|
|
|
REVISION |
REVISION |
|
|
Last updated: 02 December 2011 | Last updated: 14 January 2012 |
Copyright (c) 1997-2011 University of Cambridge. | Copyright (c) 1997-2012 University of Cambridge. |