1PCRE2TEST(1) General Commands Manual PCRE2TEST(1)
2
6 pcre2test - a program for testing Perl-compatible regular expressions.
7
9 pcre2test [options] [input file [output file]]
11 pcre2test is a test program for the PCRE2 regular expression libraries,
13 but it can also be used for experimenting with regular expressions.
14 This document describes the features of the test program; for details
15 of the regular expressions themselves, see the pcre2pattern documenta‐
16 tion. For details of the PCRE2 library function calls and their
17 options, see the pcre2api documentation.
18 The input for pcre2test is a sequence of regular expression patterns
20 and subject strings to be matched. There are also command lines for
21 setting defaults and controlling some special actions. The output shows
22 the result of each match attempt. Modifiers on external or internal
23 command lines, the patterns, and the subject lines specify PCRE2 func‐
24 tion options, control how the subject is processed, and what output is
25 produced.
26 As the original fairly simple PCRE library evolved, it acquired many
28 different features, and as a result, the original pcretest program
29 ended up with a lot of options in a messy, arcane syntax for testing
30 all the features. The move to the new PCRE2 API provided an opportunity
31 to re-implement the test program as pcre2test, with a cleaner modifier
32 syntax. Nevertheless, there are still many obscure modifiers, some of
33 which are specifically designed for use in conjunction with the test
34 script and data files that are distributed as part of PCRE2. All the
35 modifiers are documented here, some without much justification, but
36 many of them are unlikely to be of use except when testing the
37 libraries.
38
40 Different versions of the PCRE2 library can be built to support charac‐
42 ter strings that are encoded in 8-bit, 16-bit, or 32-bit code units.
43 One, two, or all three of these libraries may be simultaneously
44 installed. The pcre2test program can be used to test all the libraries.
45 However, its own input and output are always in 8-bit format. When
46 testing the 16-bit or 32-bit libraries, patterns and subject strings
47 are converted to 16-bit or 32-bit format before being passed to the
48 library functions. Results are converted back to 8-bit code units for
49 output.
50 In the rest of this document, the names of library functions and struc‐
52 tures are given in generic form, for example, pcre_compile(). The
53 actual names used in the libraries have a suffix _8, _16, or _32, as
54 appropriate.
55
57 Input to pcre2test is processed line by line, either by calling the C
59 library's fgets() function, or via the libreadline library. In some
60 Windows environments character 26 (hex 1A) causes an immediate end of
61 file, and no further data is read, so this character should be avoided
62 unless you really want that action.
63 The input is processed using using C's string functions, so must not
65 contain binary zeros, even though in Unix-like environments, fgets()
66 treats any bytes other than newline as data characters. An error is
67 generated if a binary zero is encountered. By default subject lines are
68 processed for backslash escapes, which makes it possible to include any
69 data value in strings that are passed to the library for matching. For
70 patterns, there is a facility for specifying some or all of the 8-bit
71 input characters as hexadecimal pairs, which makes it possible to
72 include binary zeros.
73 Input for the 16-bit and 32-bit libraries
75 When testing the 16-bit or 32-bit libraries, there is a need to be able
77 to generate character code points greater than 255 in the strings that
78 are passed to the library. For subject lines, backslash escapes can be
79 used. In addition, when the utf modifier (see "Setting compilation
80 options" below) is set, the pattern and any following subject lines are
81 interpreted as UTF-8 strings and translated to UTF-16 or UTF-32 as
82 appropriate.
83 For non-UTF testing of wide characters, the utf8_input modifier can be
85 used. This is mutually exclusive with utf, and is allowed only in
86 16-bit or 32-bit mode. It causes the pattern and following subject
87 lines to be treated as UTF-8 according to the original definition (RFC
88 2279), which allows for character values up to 0x7fffffff. Each charac‐
89 ter is placed in one 16-bit or 32-bit code unit (in the 16-bit case,
90 values greater than 0xffff cause an error to occur).
91 UTF-8 (in its original definition) is not capable of encoding values
93 greater than 0x7fffffff, but such values can be handled by the 32-bit
94 library. When testing this library in non-UTF mode with utf8_input set,
95 if any character is preceded by the byte 0xff (which is an invalid byte
96 in UTF-8) 0x80000000 is added to the character's value. This is the
97 only way of passing such code points in a pattern string. For subject
98 strings, using an escape sequence is preferable.
99
101 -8 If the 8-bit library has been built, this option causes it to
103 be used (this is the default). If the 8-bit library has not
104 been built, this option causes an error.
105 -16 If the 16-bit library has been built, this option causes it
107 to be used. If only the 16-bit library has been built, this
108 is the default. If the 16-bit library has not been built,
109 this option causes an error.
110 -32 If the 32-bit library has been built, this option causes it
112 to be used. If only the 32-bit library has been built, this
113 is the default. If the 32-bit library has not been built,
114 this option causes an error.
115 -ac Behave as if each pattern has the auto_callout modifier, that
117 is, insert automatic callouts into every pattern that is com‐
118 piled.
119 -AC As for -ac, but in addition behave as if each subject line
121 has the callout_extra modifier, that is, show additional
122 information from callouts.
123 -b Behave as if each pattern has the fullbincode modifier; the
125 full internal binary form of the pattern is output after com‐
126 pilation.
127 -C Output the version number of the PCRE2 library, and all
129 available information about the optional features that are
130 included, and then exit with zero exit code. All other
131 options are ignored. If both -C and -LM are present, which‐
132 ever is first is recognized.
133 -C option Output information about a specific build-time option, then
135 exit. This functionality is intended for use in scripts such
136 as RunTest. The following options output the value and set
137 the exit code as indicated:
138 ebcdic-nl the code for LF (= NL) in an EBCDIC environment:
140 0x15 or 0x25
141 0 if used in an ASCII environment
142 exit code is always 0
143 linksize the configured internal link size (2, 3, or 4)
144 exit code is set to the link size
145 newline the default newline setting:
146 CR, LF, CRLF, ANYCRLF, ANY, or NUL
147 exit code is always 0
148 bsr the default setting for what \R matches:
149 ANYCRLF or ANY
150 exit code is always 0
151 The following options output 1 for true or 0 for false, and
153 set the exit code to the same value:
154 backslash-C \C is supported (not locked out)
156 ebcdic compiled for an EBCDIC environment
157 jit just-in-time support is available
158 pcre2-16 the 16-bit library was built
159 pcre2-32 the 32-bit library was built
160 pcre2-8 the 8-bit library was built
161 unicode Unicode support is available
162 If an unknown option is given, an error message is output;
164 the exit code is 0.
165 -d Behave as if each pattern has the debug modifier; the inter‐
167 nal form and information about the compiled pattern is output
168 after compilation; -d is equivalent to -b -i.
169 -dfa Behave as if each subject line has the dfa modifier; matching
171 is done using the pcre2_dfa_match() function instead of the
172 default pcre2_match().
173 -error number[,number,...]
175 Call pcre2_get_error_message() for each of the error numbers
176 in the comma-separated list, display the resulting messages
177 on the standard output, then exit with zero exit code. The
178 numbers may be positive or negative. This is a convenience
179 facility for PCRE2 maintainers.
180 -help Output a brief summary these options and then exit.
182 -i Behave as if each pattern has the info modifier; information
184 about the compiled pattern is given after compilation.
185 -jit Behave as if each pattern line has the jit modifier; after
187 successful compilation, each pattern is passed to the just-
188 in-time compiler, if available.
189 -jitfast Behave as if each pattern line has the jitfast modifier;
191 after successful compilation, each pattern is passed to the
192 just-in-time compiler, if available, and each subject line is
193 passed directly to the JIT matcher via its "fast path".
194 -jitverify
196 Behave as if each pattern line has the jitverify modifier;
197 after successful compilation, each pattern is passed to the
198 just-in-time compiler, if available, and the use of JIT for
199 matching is verified.
200 -LM List modifiers: write a list of available pattern and subject
202 modifiers to the standard output, then exit with zero exit
203 code. All other options are ignored. If both -C and -LM are
204 present, whichever is first is recognized.
205 -pattern modifier-list
207 Behave as if each pattern line contains the given modifiers.
208 -q Do not output the version number of pcre2test at the start of
210 execution.
211 -S size On Unix-like systems, set the size of the run-time stack to
213 size mebibytes (units of 1024*1024 bytes).
214 -subject modifier-list
216 Behave as if each subject line contains the given modifiers.
217 -t Run each compile and match many times with a timer, and out‐
219 put the resulting times per compile or match. When JIT is
220 used, separate times are given for the initial compile and
221 the JIT compile. You can control the number of iterations
222 that are used for timing by following -t with a number (as a
223 separate item on the command line). For example, "-t 1000"
224 iterates 1000 times. The default is to iterate 500,000 times.
225 -tm This is like -t except that it times only the matching phase,
227 not the compile phase.
228 -T -TM These behave like -t and -tm, but in addition, at the end of
230 a run, the total times for all compiles and matches are out‐
231 put.
232 -version Output the PCRE2 version number and then exit.
234
236 If pcre2test is given two filename arguments, it reads from the first
238 and writes to the second. If the first name is "-", input is taken from
239 the standard input. If pcre2test is given only one argument, it reads
240 from that file and writes to stdout. Otherwise, it reads from stdin and
241 writes to stdout.
242 When pcre2test is built, a configuration option can specify that it
244 should be linked with the libreadline or libedit library. When this is
245 done, if the input is from a terminal, it is read using the readline()
246 function. This provides line-editing and history facilities. The output
247 from the -help option states whether or not readline() will be used.
248 The program handles any number of tests, each of which consists of a
250 set of input lines. Each set starts with a regular expression pattern,
251 followed by any number of subject lines to be matched against that pat‐
252 tern. In between sets of test data, command lines that begin with # may
253 appear. This file format, with some restrictions, can also be processed
254 by the perltest.sh script that is distributed with PCRE2 as a means of
255 checking that the behaviour of PCRE2 and Perl is the same. For a speci‐
256 fication of perltest.sh, see the comments near its beginning. See also
257 the #perltest command below.
258 When the input is a terminal, pcre2test prompts for each line of input,
260 using "re>" to prompt for regular expression patterns, and "data>" to
261 prompt for subject lines. Command lines starting with # can be entered
262 only in response to the "re>" prompt.
263 Each subject line is matched separately and independently. If you want
265 to do multi-line matches, you have to use the \n escape sequence (or \r
266 or \r\n, etc., depending on the newline setting) in a single line of
267 input to encode the newline sequences. There is no limit on the length
268 of subject lines; the input buffer is automatically extended if it is
269 too small. There are replication features that makes it possible to
270 generate long repetitive pattern or subject lines without having to
271 supply them explicitly.
272 An empty line or the end of the file signals the end of the subject
274 lines for a test, at which point a new pattern or command line is
275 expected if there is still input to be read.
276
278 In between sets of test data, a line that begins with # is interpreted
280 as a command line. If the first character is followed by white space or
281 an exclamation mark, the line is treated as a comment, and ignored.
282 Otherwise, the following commands are recognized:
283 #forbid_utf
285 Subsequent patterns automatically have the PCRE2_NEVER_UTF and
287 PCRE2_NEVER_UCP options set, which locks out the use of the PCRE2_UTF
288 and PCRE2_UCP options and the use of (*UTF) and (*UCP) at the start of
289 patterns. This command also forces an error if a subsequent pattern
290 contains any occurrences of \P, \p, or \X, which are still supported
291 when PCRE2_UTF is not set, but which require Unicode property support
292 to be included in the library.
293 This is a trigger guard that is used in test files to ensure that UTF
295 or Unicode property tests are not accidentally added to files that are
296 used when Unicode support is not included in the library. Setting
297 PCRE2_NEVER_UTF and PCRE2_NEVER_UCP as a default can also be obtained
298 by the use of #pattern; the difference is that #forbid_utf cannot be
299 unset, and the automatic options are not displayed in pattern informa‐
300 tion, to avoid cluttering up test output.
301 #load <filename>
303 This command is used to load a set of precompiled patterns from a file,
305 as described in the section entitled "Saving and restoring compiled
306 patterns" below.
307 #loadtables <filename>
309 This command is used to load a set of binary character tables that can
311 be accessed by the tables=3 qualifier. Such tables can be created by
312 the pcre2_dftables program with the -b option.
313 #newline_default [<newline-list>]
315 When PCRE2 is built, a default newline convention can be specified.
317 This determines which characters and/or character pairs are recognized
318 as indicating a newline in a pattern or subject string. The default can
319 be overridden when a pattern is compiled. The standard test files con‐
320 tain tests of various newline conventions, but the majority of the
321 tests expect a single linefeed to be recognized as a newline by
322 default. Without special action the tests would fail when PCRE2 is com‐
323 piled with either CR or CRLF as the default newline.
324 The #newline_default command specifies a list of newline types that are
326 acceptable as the default. The types must be one of CR, LF, CRLF, ANY‐
327 CRLF, ANY, or NUL (in upper or lower case), for example:
328 #newline_default LF Any anyCRLF
330 If the default newline is in the list, this command has no effect. Oth‐
332 erwise, except when testing the POSIX API, a newline modifier that
333 specifies the first newline convention in the list (LF in the above
334 example) is added to any pattern that does not already have a newline
335 modifier. If the newline list is empty, the feature is turned off. This
336 command is present in a number of the standard test input files.
337 When the POSIX API is being tested there is no way to override the
339 default newline convention, though it is possible to set the newline
340 convention from within the pattern. A warning is given if the posix or
341 posix_nosub modifier is used when #newline_default would set a default
342 for the non-POSIX API.
343 #pattern <modifier-list>
345 This command sets a default modifier list that applies to all subse‐
347 quent patterns. Modifiers on a pattern can change these settings.
348 #perltest
350 This line is used in test files that can also be processed by perl‐
352 test.sh to confirm that Perl gives the same results as PCRE2. Subse‐
353 quent tests are checked for the use of pcre2test features that are
354 incompatible with the perltest.sh script.
355 Patterns must use '/' as their delimiter, and only certain modifiers
357 are supported. Comment lines, #pattern commands, and #subject commands
358 that set or unset "mark" are recognized and acted on. The #perltest,
359 #forbid_utf, and #newline_default commands, which are needed in the
360 relevant pcre2test files, are silently ignored. All other command lines
361 are ignored, but give a warning message. The #perltest command helps
362 detect tests that are accidentally put in the wrong file or use the
363 wrong delimiter. For more details of the perltest.sh script see the
364 comments it contains.
365 #pop [<modifiers>]
367 #popcopy [<modifiers>]
368 These commands are used to manipulate the stack of compiled patterns,
370 as described in the section entitled "Saving and restoring compiled
371 patterns" below.
372 #save <filename>
374 This command is used to save a set of compiled patterns to a file, as
376 described in the section entitled "Saving and restoring compiled pat‐
377 terns" below.
378 #subject <modifier-list>
380 This command sets a default modifier list that applies to all subse‐
382 quent subject lines. Modifiers on a subject line can change these set‐
383 tings.
384
386 Modifier lists are used with both pattern and subject lines. Items in a
388 list are separated by commas followed by optional white space. Trailing
389 whitespace in a modifier list is ignored. Some modifiers may be given
390 for both patterns and subject lines, whereas others are valid only for
391 one or the other. Each modifier has a long name, for example
392 "anchored", and some of them must be followed by an equals sign and a
393 value, for example, "offset=12". Values cannot contain comma charac‐
394 ters, but may contain spaces. Modifiers that do not take values may be
395 preceded by a minus sign to turn off a previous setting.
396 A few of the more common modifiers can also be specified as single let‐
398 ters, for example "i" for "caseless". In documentation, following the
399 Perl convention, these are written with a slash ("the /i modifier") for
400 clarity. Abbreviated modifiers must all be concatenated in the first
401 item of a modifier list. If the first item is not recognized as a long
402 modifier name, it is interpreted as a sequence of these abbreviations.
403 For example:
404 /abc/ig,newline=cr,jit=3
406 This is a pattern line whose modifier list starts with two one-letter
408 modifiers (/i and /g). The lower-case abbreviated modifiers are the
409 same as used in Perl.
410
412 A pattern line must start with one of the following characters (common
414 symbols, excluding pattern meta-characters):
415 / ! " ' ` - = _ : ; , % & @ ~
417 This is interpreted as the pattern's delimiter. A regular expression
419 may be continued over several input lines, in which case the newline
420 characters are included within it. It is possible to include the delim‐
421 iter within the pattern by escaping it with a backslash, for example
422 /abc\/def/
424 If you do this, the escape and the delimiter form part of the pattern,
426 but since the delimiters are all non-alphanumeric, this does not affect
427 its interpretation. If the terminating delimiter is immediately fol‐
428 lowed by a backslash, for example,
429 /abc/\
431 then a backslash is added to the end of the pattern. This is done to
433 provide a way of testing the error condition that arises if a pattern
434 finishes with a backslash, because
435 /abc\/
437 is interpreted as the first line of a pattern that starts with "abc/",
439 causing pcre2test to read the next line as a continuation of the regu‐
440 lar expression.
441 A pattern can be followed by a modifier list (details below).
443
445 Before each subject line is passed to pcre2_match() or
447 pcre2_dfa_match(), leading and trailing white space is removed, and the
448 line is scanned for backslash escapes, unless the subject_literal modi‐
449 fier was set for the pattern. The following provide a means of encoding
450 non-printing characters in a visible way:
451 \a alarm (BEL, \x07)
453 \b backspace (\x08)
454 \e escape (\x27)
455 \f form feed (\x0c)
456 \n newline (\x0a)
457 \r carriage return (\x0d)
458 \t tab (\x09)
459 \v vertical tab (\x0b)
460 \nnn octal character (up to 3 octal digits); always
461 a byte unless > 255 in UTF-8 or 16-bit or 32-bit mode
462 \o{dd...} octal character (any number of octal digits}
463 \xhh hexadecimal byte (up to 2 hex digits)
464 \x{hh...} hexadecimal character (any number of hex digits)
465 The use of \x{hh...} is not dependent on the use of the utf modifier on
467 the pattern. It is recognized always. There may be any number of hexa‐
468 decimal digits inside the braces; invalid values provoke error mes‐
469 sages.
470 Note that \xhh specifies one byte rather than one character in UTF-8
472 mode; this makes it possible to construct invalid UTF-8 sequences for
473 testing purposes. On the other hand, \x{hh} is interpreted as a UTF-8
474 character in UTF-8 mode, generating more than one byte if the value is
475 greater than 127. When testing the 8-bit library not in UTF-8 mode,
476 \x{hh} generates one byte for values less than 256, and causes an error
477 for greater values.
478 In UTF-16 mode, all 4-digit \x{hhhh} values are accepted. This makes it
480 possible to construct invalid UTF-16 sequences for testing purposes.
481 In UTF-32 mode, all 4- to 8-digit \x{...} values are accepted. This
483 makes it possible to construct invalid UTF-32 sequences for testing
484 purposes.
485 There is a special backslash sequence that specifies replication of one
487 or more characters:
488 \[<characters>]{<count>}
490 This makes it possible to test long strings without having to provide
492 them as part of the file. For example:
493 \[abc]{4}
495 is converted to "abcabcabcabc". This feature does not support nesting.
497 To include a closing square bracket in the characters, code it as \x5D.
498 A backslash followed by an equals sign marks the end of the subject
500 string and the start of a modifier list. For example:
501 abc\=notbol,notempty
503 If the subject string is empty and \= is followed by whitespace, the
505 line is treated as a comment line, and is not used for matching. For
506 example:
507 \= This is a comment.
509 abc\= This is an invalid modifier list.
510 A backslash followed by any other non-alphanumeric character just
512 escapes that character. A backslash followed by anything else causes an
513 error. However, if the very last character in the line is a backslash
514 (and there is no modifier list), it is ignored. This gives a way of
515 passing an empty line as data, since a real empty line terminates the
516 data input.
517 If the subject_literal modifier is set for a pattern, all subject lines
519 that follow are treated as literals, with no special treatment of back‐
520 slashes. No replication is possible, and any subject modifiers must be
521 set as defaults by a #subject command.
522
524 There are several types of modifier that can appear in pattern lines.
526 Except where noted below, they may also be used in #pattern commands. A
527 pattern's modifier list can add to or override default modifiers that
528 were set by a previous #pattern command.
529 Setting compilation options
531 The following modifiers set options for pcre2_compile(). Most of them
533 set bits in the options argument of that function, but those whose
534 names start with PCRE2_EXTRA are additional options that are set in the
535 compile context. For the main options, there are some single-letter
536 abbreviations that are the same as Perl options. There is special han‐
537 dling for /x: if a second x is present, PCRE2_EXTENDED is converted
538 into PCRE2_EXTENDED_MORE as in Perl. A third appearance adds
539 PCRE2_EXTENDED as well, though this makes no difference to the way
540 pcre2_compile() behaves. See pcre2api for a description of the effects
541 of these options.
542 allow_empty_class set PCRE2_ALLOW_EMPTY_CLASS
544 allow_surrogate_escapes set PCRE2_EXTRA_ALLOW_SURROGATE_ESCAPES
545 alt_bsux set PCRE2_ALT_BSUX
546 alt_circumflex set PCRE2_ALT_CIRCUMFLEX
547 alt_verbnames set PCRE2_ALT_VERBNAMES
548 anchored set PCRE2_ANCHORED
549 auto_callout set PCRE2_AUTO_CALLOUT
550 bad_escape_is_literal set PCRE2_EXTRA_BAD_ESCAPE_IS_LITERAL
551 /i caseless set PCRE2_CASELESS
552 dollar_endonly set PCRE2_DOLLAR_ENDONLY
553 /s dotall set PCRE2_DOTALL
554 dupnames set PCRE2_DUPNAMES
555 endanchored set PCRE2_ENDANCHORED
556 escaped_cr_is_lf set PCRE2_EXTRA_ESCAPED_CR_IS_LF
557 /x extended set PCRE2_EXTENDED
558 /xx extended_more set PCRE2_EXTENDED_MORE
559 extra_alt_bsux set PCRE2_EXTRA_ALT_BSUX
560 firstline set PCRE2_FIRSTLINE
561 literal set PCRE2_LITERAL
562 match_line set PCRE2_EXTRA_MATCH_LINE
563 match_invalid_utf set PCRE2_MATCH_INVALID_UTF
564 match_unset_backref set PCRE2_MATCH_UNSET_BACKREF
565 match_word set PCRE2_EXTRA_MATCH_WORD
566 /m multiline set PCRE2_MULTILINE
567 never_backslash_c set PCRE2_NEVER_BACKSLASH_C
568 never_ucp set PCRE2_NEVER_UCP
569 never_utf set PCRE2_NEVER_UTF
570 /n no_auto_capture set PCRE2_NO_AUTO_CAPTURE
571 no_auto_possess set PCRE2_NO_AUTO_POSSESS
572 no_dotstar_anchor set PCRE2_NO_DOTSTAR_ANCHOR
573 no_start_optimize set PCRE2_NO_START_OPTIMIZE
574 no_utf_check set PCRE2_NO_UTF_CHECK
575 ucp set PCRE2_UCP
576 ungreedy set PCRE2_UNGREEDY
577 use_offset_limit set PCRE2_USE_OFFSET_LIMIT
578 utf set PCRE2_UTF
579 As well as turning on the PCRE2_UTF option, the utf modifier causes all
581 non-printing characters in output strings to be printed using the
582 \x{hh...} notation. Otherwise, those less than 0x100 are output in hex
583 without the curly brackets. Setting utf in 16-bit or 32-bit mode also
584 causes pattern and subject strings to be translated to UTF-16 or
585 UTF-32, respectively, before being passed to library functions.
586 Setting compilation controls
588 The following modifiers affect the compilation process or request
590 information about the pattern. There are single-letter abbreviations
591 for some that are heavily used in the test files.
592 bsr=[anycrlf|unicode] specify \R handling
594 /B bincode show binary code without lengths
595 callout_info show callout information
596 convert=<options> request foreign pattern conversion
597 convert_glob_escape=c set glob escape character
598 convert_glob_separator=c set glob separator character
599 convert_length set convert buffer length
600 debug same as info,fullbincode
601 framesize show matching frame size
602 fullbincode show binary code with lengths
603 /I info show info about compiled pattern
604 hex unquoted characters are hexadecimal
605 jit[=<number>] use JIT
606 jitfast use JIT fast path
607 jitverify verify JIT use
608 locale=<name> use this locale
609 max_pattern_length=<n> set the maximum pattern length
610 memory show memory used
611 newline=<type> set newline type
612 null_context compile with a NULL context
613 parens_nest_limit=<n> set maximum parentheses depth
614 posix use the POSIX API
615 posix_nosub use the POSIX API with REG_NOSUB
616 push push compiled pattern onto the stack
617 pushcopy push a copy onto the stack
618 stackguard=<number> test the stackguard feature
619 subject_literal treat all subject lines as literal
620 tables=[0|1|2|3] select internal tables
621 use_length do not zero-terminate the pattern
622 utf8_input treat input as UTF-8
623 The effects of these modifiers are described in the following sections.
625 Newline and \R handling
627 The bsr modifier specifies what \R in a pattern should match. If it is
629 set to "anycrlf", \R matches CR, LF, or CRLF only. If it is set to
630 "unicode", \R matches any Unicode newline sequence. The default can be
631 specified when PCRE2 is built; if it is not, the default is set to Uni‐
632 code.
633 The newline modifier specifies which characters are to be interpreted
635 as newlines, both in the pattern and in subject lines. The type must be
636 one of CR, LF, CRLF, ANYCRLF, ANY, or NUL (in upper or lower case).
637 Information about a pattern
639 The debug modifier is a shorthand for info,fullbincode, requesting all
641 available information.
642 The bincode modifier causes a representation of the compiled code to be
644 output after compilation. This information does not contain length and
645 offset values, which ensures that the same output is generated for dif‐
646 ferent internal link sizes and different code unit widths. By using
647 bincode, the same regression tests can be used in different environ‐
648 ments.
649 The fullbincode modifier, by contrast, does include length and offset
651 values. This is used in a few special tests that run only for specific
652 code unit widths and link sizes, and is also useful for one-off tests.
653 The info modifier requests information about the compiled pattern
655 (whether it is anchored, has a fixed first character, and so on). The
656 information is obtained from the pcre2_pattern_info() function. Here
657 are some typical examples:
658 re> /(?i)(^a|^b)/m,info
660 Capture group count = 1
661 Compile options: multiline
662 Overall options: caseless multiline
663 First code unit at start or follows newline
664 Subject length lower bound = 1
665 re> /(?i)abc/info
667 Capture group count = 0
668 Compile options: <none>
669 Overall options: caseless
670 First code unit = 'a' (caseless)
671 Last code unit = 'c' (caseless)
672 Subject length lower bound = 3
673 "Compile options" are those specified by modifiers; "overall options"
675 have added options that are taken or deduced from the pattern. If both
676 sets of options are the same, just a single "options" line is output;
677 if there are no options, the line is omitted. "First code unit" is
678 where any match must start; if there is more than one they are listed
679 as "starting code units". "Last code unit" is the last literal code
680 unit that must be present in any match. This is not necessarily the
681 last character. These lines are omitted if no starting or ending code
682 units are recorded. The subject length line is omitted when
683 no_start_optimize is set because the minimum length is not calculated
684 when it can never be used.
685 The framesize modifier shows the size, in bytes, of the storage frames
687 used by pcre2_match() for handling backtracking. The size depends on
688 the number of capturing parentheses in the pattern.
689 The callout_info modifier requests information about all the callouts
691 in the pattern. A list of them is output at the end of any other infor‐
692 mation that is requested. For each callout, either its number or string
693 is given, followed by the item that follows it in the pattern.
694 Passing a NULL context
696 Normally, pcre2test passes a context block to pcre2_compile(). If the
698 null_context modifier is set, however, NULL is passed. This is for
699 testing that pcre2_compile() behaves correctly in this case (it uses
700 default values).
701 Specifying pattern characters in hexadecimal
703 The hex modifier specifies that the characters of the pattern, except
705 for substrings enclosed in single or double quotes, are to be inter‐
706 preted as pairs of hexadecimal digits. This feature is provided as a
707 way of creating patterns that contain binary zeros and other non-print‐
708 ing characters. White space is permitted between pairs of digits. For
709 example, this pattern contains three characters:
710 /ab 32 59/hex
712 Parts of such a pattern are taken literally if quoted. This pattern
714 contains nine characters, only two of which are specified in hexadeci‐
715 mal:
716 /ab "literal" 32/hex
718 Either single or double quotes may be used. There is no way of includ‐
720 ing the delimiter within a substring. The hex and expand modifiers are
721 mutually exclusive.
722 Specifying the pattern's length
724 By default, patterns are passed to the compiling functions as zero-ter‐
726 minated strings but can be passed by length instead of being zero-ter‐
727 minated. The use_length modifier causes this to happen. Using a length
728 happens automatically (whether or not use_length is set) when hex is
729 set, because patterns specified in hexadecimal may contain binary
730 zeros.
731 If hex or use_length is used with the POSIX wrapper API (see "Using the
733 POSIX wrapper API" below), the REG_PEND extension is used to pass the
734 pattern's length.
735 Specifying wide characters in 16-bit and 32-bit modes
737 In 16-bit and 32-bit modes, all input is automatically treated as UTF-8
739 and translated to UTF-16 or UTF-32 when the utf modifier is set. For
740 testing the 16-bit and 32-bit libraries in non-UTF mode, the utf8_input
741 modifier can be used. It is mutually exclusive with utf. Input lines
742 are interpreted as UTF-8 as a means of specifying wide characters. More
743 details are given in "Input encoding" above.
744 Generating long repetitive patterns
746 Some tests use long patterns that are very repetitive. Instead of cre‐
748 ating a very long input line for such a pattern, you can use a special
749 repetition feature, similar to the one described for subject lines
750 above. If the expand modifier is present on a pattern, parts of the
751 pattern that have the form
752 \[<characters>]{<count>}
754 are expanded before the pattern is passed to pcre2_compile(). For exam‐
756 ple, \[AB]{6000} is expanded to "ABAB..." 6000 times. This construction
757 cannot be nested. An initial "\[" sequence is recognized only if "]{"
758 followed by decimal digits and "}" is found later in the pattern. If
759 not, the characters remain in the pattern unaltered. The expand and hex
760 modifiers are mutually exclusive.
761 If part of an expanded pattern looks like an expansion, but is really
763 part of the actual pattern, unwanted expansion can be avoided by giving
764 two values in the quantifier. For example, \[AB]{6000,6000} is not rec‐
765 ognized as an expansion item.
766 If the info modifier is set on an expanded pattern, the result of the
768 expansion is included in the information that is output.
769 JIT compilation
771 Just-in-time (JIT) compiling is a heavyweight optimization that can
773 greatly speed up pattern matching. See the pcre2jit documentation for
774 details. JIT compiling happens, optionally, after a pattern has been
775 successfully compiled into an internal form. The JIT compiler converts
776 this to optimized machine code. It needs to know whether the match-time
777 options PCRE2_PARTIAL_HARD and PCRE2_PARTIAL_SOFT are going to be used,
778 because different code is generated for the different cases. See the
779 partial modifier in "Subject Modifiers" below for details of how these
780 options are specified for each match attempt.
781 JIT compilation is requested by the jit pattern modifier, which may
783 optionally be followed by an equals sign and a number in the range 0 to
784 7. The three bits that make up the number specify which of the three
785 JIT operating modes are to be compiled:
786 1 compile JIT code for non-partial matching
788 2 compile JIT code for soft partial matching
789 4 compile JIT code for hard partial matching
790 The possible values for the jit modifier are therefore:
792 0 disable JIT
794 1 normal matching only
795 2 soft partial matching only
796 3 normal and soft partial matching
797 4 hard partial matching only
798 6 soft and hard partial matching only
799 7 all three modes
800 If no number is given, 7 is assumed. The phrase "partial matching"
802 means a call to pcre2_match() with either the PCRE2_PARTIAL_SOFT or the
803 PCRE2_PARTIAL_HARD option set. Note that such a call may return a com‐
804 plete match; the options enable the possibility of a partial match, but
805 do not require it. Note also that if you request JIT compilation only
806 for partial matching (for example, jit=2) but do not set the partial
807 modifier on a subject line, that match will not use JIT code because
808 none was compiled for non-partial matching.
809 If JIT compilation is successful, the compiled JIT code will automati‐
811 cally be used when an appropriate type of match is run, except when
812 incompatible run-time options are specified. For more details, see the
813 pcre2jit documentation. See also the jitstack modifier below for a way
814 of setting the size of the JIT stack.
815 If the jitfast modifier is specified, matching is done using the JIT
817 "fast path" interface, pcre2_jit_match(), which skips some of the san‐
818 ity checks that are done by pcre2_match(), and of course does not work
819 when JIT is not supported. If jitfast is specified without jit, jit=7
820 is assumed.
821 If the jitverify modifier is specified, information about the compiled
823 pattern shows whether JIT compilation was or was not successful. If
824 jitverify is specified without jit, jit=7 is assumed. If JIT compila‐
825 tion is successful when jitverify is set, the text "(JIT)" is added to
826 the first output line after a match or non match when JIT-compiled code
827 was actually used in the match.
828 Setting a locale
830 The locale modifier must specify the name of a locale, for example:
832 /pattern/locale=fr_FR
834 The given locale is set, pcre2_maketables() is called to build a set of
836 character tables for the locale, and this is then passed to pcre2_com‐
837 pile() when compiling the regular expression. The same tables are used
838 when matching the following subject lines. The locale modifier applies
839 only to the pattern on which it appears, but can be given in a #pattern
840 command if a default is needed. Setting a locale and alternate charac‐
841 ter tables are mutually exclusive.
842 Showing pattern memory
844 The memory modifier causes the size in bytes of the memory used to hold
846 the compiled pattern to be output. This does not include the size of
847 the pcre2_code block; it is just the actual compiled data. If the pat‐
848 tern is subsequently passed to the JIT compiler, the size of the JIT
849 compiled code is also output. Here is an example:
850 re> /a(b)c/jit,memory
852 Memory allocation (code space): 21
853 Memory allocation (JIT code): 1910
854 Limiting nested parentheses
857 The parens_nest_limit modifier sets a limit on the depth of nested
859 parentheses in a pattern. Breaching the limit causes a compilation
860 error. The default for the library is set when PCRE2 is built, but
861 pcre2test sets its own default of 220, which is required for running
862 the standard test suite.
863 Limiting the pattern length
865 The max_pattern_length modifier sets a limit, in code units, to the
867 length of pattern that pcre2_compile() will accept. Breaching the limit
868 causes a compilation error. The default is the largest number a
869 PCRE2_SIZE variable can hold (essentially unlimited).
870 Using the POSIX wrapper API
872 The posix and posix_nosub modifiers cause pcre2test to call PCRE2 via
874 the POSIX wrapper API rather than its native API. When posix_nosub is
875 used, the POSIX option REG_NOSUB is passed to regcomp(). The POSIX
876 wrapper supports only the 8-bit library. Note that it does not imply
877 POSIX matching semantics; for more detail see the pcre2posix documenta‐
878 tion. The following pattern modifiers set options for the regcomp()
879 function:
880 caseless REG_ICASE
882 multiline REG_NEWLINE
883 dotall REG_DOTALL )
884 ungreedy REG_UNGREEDY ) These options are not part of
885 ucp REG_UCP ) the POSIX standard
886 utf REG_UTF8 )
887 The regerror_buffsize modifier specifies a size for the error buffer
889 that is passed to regerror() in the event of a compilation error. For
890 example:
891 /abc/posix,regerror_buffsize=20
893 This provides a means of testing the behaviour of regerror() when the
895 buffer is too small for the error message. If this modifier has not
896 been set, a large buffer is used.
897 The aftertext and allaftertext subject modifiers work as described
899 below. All other modifiers are either ignored, with a warning message,
900 or cause an error.
901 The pattern is passed to regcomp() as a zero-terminated string by
903 default, but if the use_length or hex modifiers are set, the REG_PEND
904 extension is used to pass it by length.
905 Testing the stack guard feature
907 The stackguard modifier is used to test the use of pcre2_set_com‐
909 pile_recursion_guard(), a function that is provided to enable stack
910 availability to be checked during compilation (see the pcre2api docu‐
911 mentation for details). If the number specified by the modifier is
912 greater than zero, pcre2_set_compile_recursion_guard() is called to set
913 up callback from pcre2_compile() to a local function. The argument it
914 receives is the current nesting parenthesis depth; if this is greater
915 than the value given by the modifier, non-zero is returned, causing the
916 compilation to be aborted.
917 Using alternative character tables
919 The value specified for the tables modifier must be one of the digits
921 0, 1, 2, or 3. It causes a specific set of built-in character tables to
922 be passed to pcre2_compile(). This is used in the PCRE2 tests to check
923 behaviour with different character tables. The digit specifies the
924 tables as follows:
925 0 do not pass any special character tables
927 1 the default ASCII tables, as distributed in
928 pcre2_chartables.c.dist
929 2 a set of tables defining ISO 8859 characters
930 3 a set of tables loaded by the #loadtables command
931 In tables 2, some characters whose codes are greater than 128 are iden‐
933 tified as letters, digits, spaces, etc. Tables 3 can be used only after
934 a #loadtables command has loaded them from a binary file. Setting
935 alternate character tables and a locale are mutually exclusive.
936 Setting certain match controls
938 The following modifiers are really subject modifiers, and are described
940 under "Subject Modifiers" below. However, they may be included in a
941 pattern's modifier list, in which case they are applied to every sub‐
942 ject line that is processed with that pattern. These modifiers do not
943 affect the compilation process.
944 aftertext show text after match
946 allaftertext show text after captures
947 allcaptures show all captures
948 allvector show the entire ovector
949 allusedtext show all consulted text
950 altglobal alternative global matching
951 /g global global matching
952 jitstack=<n> set size of JIT stack
953 mark show mark values
954 replace=<string> specify a replacement string
955 startchar show starting character when relevant
956 substitute_callout use substitution callouts
957 substitute_extended use PCRE2_SUBSTITUTE_EXTENDED
958 substitute_literal use PCRE2_SUBSTITUTE_LITERAL
959 substitute_matched use PCRE2_SUBSTITUTE_MATCHED
960 substitute_overflow_length use PCRE2_SUBSTITUTE_OVERFLOW_LENGTH
961 substitute_replacement_only use PCRE2_SUBSTITUTE_REPLACEMENT_ONLY
962 substitute_skip=<n> skip substitution <n>
963 substitute_stop=<n> skip substitution <n> and following
964 substitute_unknown_unset use PCRE2_SUBSTITUTE_UNKNOWN_UNSET
965 substitute_unset_empty use PCRE2_SUBSTITUTE_UNSET_EMPTY
966 These modifiers may not appear in a #pattern command. If you want them
968 as defaults, set them in a #subject command.
969 Specifying literal subject lines
971 If the subject_literal modifier is present on a pattern, all the sub‐
973 ject lines that it matches are taken as literal strings, with no inter‐
974 pretation of backslashes. It is not possible to set subject modifiers
975 on such lines, but any that are set as defaults by a #subject command
976 are recognized.
977 Saving a compiled pattern
979 When a pattern with the push modifier is successfully compiled, it is
981 pushed onto a stack of compiled patterns, and pcre2test expects the
982 next line to contain a new pattern (or a command) instead of a subject
983 line. This facility is used when saving compiled patterns to a file, as
984 described in the section entitled "Saving and restoring compiled pat‐
985 terns" below. If pushcopy is used instead of push, a copy of the com‐
986 piled pattern is stacked, leaving the original as current, ready to
987 match the following input lines. This provides a way of testing the
988 pcre2_code_copy() function. The push and pushcopy modifiers are
989 incompatible with compilation modifiers such as global that act at
990 match time. Any that are specified are ignored (for the stacked copy),
991 with a warning message, except for replace, which causes an error. Note
992 that jitverify, which is allowed, does not carry through to any subse‐
993 quent matching that uses a stacked pattern.
994 Testing foreign pattern conversion
996 The experimental foreign pattern conversion functions in PCRE2 can be
998 tested by setting the convert modifier. Its argument is a colon-sepa‐
999 rated list of options, which set the equivalent option for the
1000 pcre2_pattern_convert() function:
1001 glob PCRE2_CONVERT_GLOB
1003 glob_no_starstar PCRE2_CONVERT_GLOB_NO_STARSTAR
1004 glob_no_wild_separator PCRE2_CONVERT_GLOB_NO_WILD_SEPARATOR
1005 posix_basic PCRE2_CONVERT_POSIX_BASIC
1006 posix_extended PCRE2_CONVERT_POSIX_EXTENDED
1007 unset Unset all options
1008 The "unset" value is useful for turning off a default that has been set
1010 by a #pattern command. When one of these options is set, the input pat‐
1011 tern is passed to pcre2_pattern_convert(). If the conversion is suc‐
1012 cessful, the result is reflected in the output and then passed to
1013 pcre2_compile(). The normal utf and no_utf_check options, if set, cause
1014 the PCRE2_CONVERT_UTF and PCRE2_CONVERT_NO_UTF_CHECK options to be
1015 passed to pcre2_pattern_convert().
1016 By default, the conversion function is allowed to allocate a buffer for
1018 its output. However, if the convert_length modifier is set to a value
1019 greater than zero, pcre2test passes a buffer of the given length. This
1020 makes it possible to test the length check.
1021 The convert_glob_escape and convert_glob_separator modifiers can be
1023 used to specify the escape and separator characters for glob process‐
1024 ing, overriding the defaults, which are operating-system dependent.
1025
1027 The modifiers that can appear in subject lines and the #subject command
1029 are of two types.
1030 Setting match options
1032 The following modifiers set options for pcre2_match() or
1034 pcre2_dfa_match(). See pcreapi for a description of their effects.
1035 anchored set PCRE2_ANCHORED
1037 endanchored set PCRE2_ENDANCHORED
1038 dfa_restart set PCRE2_DFA_RESTART
1039 dfa_shortest set PCRE2_DFA_SHORTEST
1040 no_jit set PCRE2_NO_JIT
1041 no_utf_check set PCRE2_NO_UTF_CHECK
1042 notbol set PCRE2_NOTBOL
1043 notempty set PCRE2_NOTEMPTY
1044 notempty_atstart set PCRE2_NOTEMPTY_ATSTART
1045 noteol set PCRE2_NOTEOL
1046 partial_hard (or ph) set PCRE2_PARTIAL_HARD
1047 partial_soft (or ps) set PCRE2_PARTIAL_SOFT
1048 The partial matching modifiers are provided with abbreviations because
1050 they appear frequently in tests.
1051 If the posix or posix_nosub modifier was present on the pattern, caus‐
1053 ing the POSIX wrapper API to be used, the only option-setting modifiers
1054 that have any effect are notbol, notempty, and noteol, causing REG_NOT‐
1055 BOL, REG_NOTEMPTY, and REG_NOTEOL, respectively, to be passed to
1056 regexec(). The other modifiers are ignored, with a warning message.
1057 There is one additional modifier that can be used with the POSIX wrap‐
1059 per. It is ignored (with a warning) if used for non-POSIX matching.
1060 posix_startend=<n>[:<m>]
1062 This causes the subject string to be passed to regexec() using the
1064 REG_STARTEND option, which uses offsets to specify which part of the
1065 string is searched. If only one number is given, the end offset is
1066 passed as the end of the subject string. For more detail of REG_STAR‐
1067 TEND, see the pcre2posix documentation. If the subject string contains
1068 binary zeros (coded as escapes such as \x{00} because pcre2test does
1069 not support actual binary zeros in its input), you must use posix_star‐
1070 tend to specify its length.
1071 Setting match controls
1073 The following modifiers affect the matching process or request addi‐
1075 tional information. Some of them may also be specified on a pattern
1076 line (see above), in which case they apply to every subject line that
1077 is matched against that pattern.
1078 aftertext show text after match
1080 allaftertext show text after captures
1081 allcaptures show all captures
1082 allvector show the entire ovector
1083 allusedtext show all consulted text (non-JIT only)
1084 altglobal alternative global matching
1085 callout_capture show captures at callout time
1086 callout_data=<n> set a value to pass via callouts
1087 callout_error=<n>[:<m>] control callout error
1088 callout_extra show extra callout information
1089 callout_fail=<n>[:<m>] control callout failure
1090 callout_no_where do not show position of a callout
1091 callout_none do not supply a callout function
1092 copy=<number or name> copy captured substring
1093 depth_limit=<n> set a depth limit
1094 dfa use pcre2_dfa_match()
1095 find_limits find match and depth limits
1096 get=<number or name> extract captured substring
1097 getall extract all captured substrings
1098 /g global global matching
1099 heap_limit=<n> set a limit on heap memory (Kbytes)
1100 jitstack=<n> set size of JIT stack
1101 mark show mark values
1102 match_limit=<n> set a match limit
1103 memory show heap memory usage
1104 null_context match with a NULL context
1105 offset=<n> set starting offset
1106 offset_limit=<n> set offset limit
1107 ovector=<n> set size of output vector
1108 recursion_limit=<n> obsolete synonym for depth_limit
1109 replace=<string> specify a replacement string
1110 startchar show startchar when relevant
1111 startoffset=<n> same as offset=<n>
1112 substitute_callout use substitution callouts
1113 substitute_extedded use PCRE2_SUBSTITUTE_EXTENDED
1114 substitute_literal use PCRE2_SUBSTITUTE_LITERAL
1115 substitute_matched use PCRE2_SUBSTITUTE_MATCHED
1116 substitute_overflow_length use PCRE2_SUBSTITUTE_OVERFLOW_LENGTH
1117 substitute_replacement_only use PCRE2_SUBSTITUTE_REPLACEMENT_ONLY
1118 substitute_skip=<n> skip substitution number n
1119 substitute_stop=<n> skip substitution number n and greater
1120 substitute_unknown_unset use PCRE2_SUBSTITUTE_UNKNOWN_UNSET
1121 substitute_unset_empty use PCRE2_SUBSTITUTE_UNSET_EMPTY
1122 zero_terminate pass the subject as zero-terminated
1123 The effects of these modifiers are described in the following sections.
1125 When matching via the POSIX wrapper API, the aftertext, allaftertext,
1126 and ovector subject modifiers work as described below. All other modi‐
1127 fiers are either ignored, with a warning message, or cause an error.
1128 Showing more text
1130 The aftertext modifier requests that as well as outputting the part of
1132 the subject string that matched the entire pattern, pcre2test should in
1133 addition output the remainder of the subject string. This is useful for
1134 tests where the subject contains multiple copies of the same substring.
1135 The allaftertext modifier requests the same action for captured sub‐
1136 strings as well as the main matched substring. In each case the remain‐
1137 der is output on the following line with a plus character following the
1138 capture number.
1139 The allusedtext modifier requests that all the text that was consulted
1141 during a successful pattern match by the interpreter should be shown,
1142 for both full and partial matches. This feature is not supported for
1143 JIT matching, and if requested with JIT it is ignored (with a warning
1144 message). Setting this modifier affects the output if there is a look‐
1145 behind at the start of a match, or, for a complete match, a lookahead
1146 at the end, or if \K is used in the pattern. Characters that precede or
1147 follow the start and end of the actual match are indicated in the out‐
1148 put by '<' or '>' characters underneath them. Here is an example:
1149 re> /(?<=pqr)abc(?=xyz)/
1151 data> 123pqrabcxyz456\=allusedtext
1152 0: pqrabcxyz
1153 <<< >>>
1154 data> 123pqrabcxy\=ph,allusedtext
1155 Partial match: pqrabcxy
1156 <<<
1157 The first, complete match shows that the matched string is "abc", with
1159 the preceding and following strings "pqr" and "xyz" having been con‐
1160 sulted during the match (when processing the assertions). The partial
1161 match can indicate only the preceding string.
1162 The startchar modifier requests that the starting character for the
1164 match be indicated, if it is different to the start of the matched
1165 string. The only time when this occurs is when \K has been processed as
1166 part of the match. In this situation, the output for the matched string
1167 is displayed from the starting character instead of from the match
1168 point, with circumflex characters under the earlier characters. For
1169 example:
1170 re> /abc\Kxyz/
1172 data> abcxyz\=startchar
1173 0: abcxyz
1174 ^^^
1175 Unlike allusedtext, the startchar modifier can be used with JIT. How‐
1177 ever, these two modifiers are mutually exclusive.
1178 Showing the value of all capture groups
1180 The allcaptures modifier requests that the values of all potential cap‐
1182 tured parentheses be output after a match. By default, only those up to
1183 the highest one actually used in the match are output (corresponding to
1184 the return code from pcre2_match()). Groups that did not take part in
1185 the match are output as "<unset>". This modifier is not relevant for
1186 DFA matching (which does no capturing) and does not apply when replace
1187 is specified; it is ignored, with a warning message, if present.
1188 Showing the entire ovector, for all outcomes
1190 The allvector modifier requests that the entire ovector be shown, what‐
1192 ever the outcome of the match. Compare allcaptures, which shows only up
1193 to the maximum number of capture groups for the pattern, and then only
1194 for a successful complete non-DFA match. This modifier, which acts
1195 after any match result, and also for DFA matching, provides a means of
1196 checking that there are no unexpected modifications to ovector fields.
1197 Before each match attempt, the ovector is filled with a special value,
1198 and if this is found in both elements of a capturing pair,
1199 "<unchanged>" is output. After a successful match, this applies to all
1200 groups after the maximum capture group for the pattern. In other cases
1201 it applies to the entire ovector. After a partial match, the first two
1202 elements are the only ones that should be set. After a DFA match, the
1203 amount of ovector that is used depends on the number of matches that
1204 were found.
1205 Testing pattern callouts
1207 A callout function is supplied when pcre2test calls the library match‐
1209 ing functions, unless callout_none is specified. Its behaviour can be
1210 controlled by various modifiers listed above whose names begin with
1211 callout_. Details are given in the section entitled "Callouts" below.
1212 Testing callouts from pcre2_substitute() is decribed separately in
1213 "Testing the substitution function" below.
1214 Finding all matches in a string
1216 Searching for all possible matches within a subject can be requested by
1218 the global or altglobal modifier. After finding a match, the matching
1219 function is called again to search the remainder of the subject. The
1220 difference between global and altglobal is that the former uses the
1221 start_offset argument to pcre2_match() or pcre2_dfa_match() to start
1222 searching at a new point within the entire string (which is what Perl
1223 does), whereas the latter passes over a shortened subject. This makes a
1224 difference to the matching process if the pattern begins with a lookbe‐
1225 hind assertion (including \b or \B).
1226 If an empty string is matched, the next match is done with the
1228 PCRE2_NOTEMPTY_ATSTART and PCRE2_ANCHORED flags set, in order to search
1229 for another, non-empty, match at the same point in the subject. If this
1230 match fails, the start offset is advanced, and the normal match is
1231 retried. This imitates the way Perl handles such cases when using the
1232 /g modifier or the split() function. Normally, the start offset is
1233 advanced by one character, but if the newline convention recognizes
1234 CRLF as a newline, and the current character is CR followed by LF, an
1235 advance of two characters occurs.
1236 Testing substring extraction functions
1238 The copy and get modifiers can be used to test the pcre2_sub‐
1240 string_copy_xxx() and pcre2_substring_get_xxx() functions. They can be
1241 given more than once, and each can specify a capture group name or num‐
1242 ber, for example:
1243 abcd\=copy=1,copy=3,get=G1
1245 If the #subject command is used to set default copy and/or get lists,
1247 these can be unset by specifying a negative number to cancel all num‐
1248 bered groups and an empty name to cancel all named groups.
1249 The getall modifier tests pcre2_substring_list_get(), which extracts
1251 all captured substrings.
1252 If the subject line is successfully matched, the substrings extracted
1254 by the convenience functions are output with C, G, or L after the
1255 string number instead of a colon. This is in addition to the normal
1256 full list. The string length (that is, the return from the extraction
1257 function) is given in parentheses after each substring, followed by the
1258 name when the extraction was by name.
1259 Testing the substitution function
1261 If the replace modifier is set, the pcre2_substitute() function is
1263 called instead of one of the matching functions (or after one call of
1264 pcre2_match() in the case of PCRE2_SUBSTITUTE_MATCHED). Note that
1265 replacement strings cannot contain commas, because a comma signifies
1266 the end of a modifier. This is not thought to be an issue in a test
1267 program.
1268 Unlike subject strings, pcre2test does not process replacement strings
1270 for escape sequences. In UTF mode, a replacement string is checked to
1271 see if it is a valid UTF-8 string. If so, it is correctly converted to
1272 a UTF string of the appropriate code unit width. If it is not a valid
1273 UTF-8 string, the individual code units are copied directly. This pro‐
1274 vides a means of passing an invalid UTF-8 string for testing purposes.
1275 The following modifiers set options (in additional to the normal match
1277 options) for pcre2_substitute():
1278 global PCRE2_SUBSTITUTE_GLOBAL
1280 substitute_extended PCRE2_SUBSTITUTE_EXTENDED
1281 substitute_literal PCRE2_SUBSTITUTE_LITERAL
1282 substitute_matched PCRE2_SUBSTITUTE_MATCHED
1283 substitute_overflow_length PCRE2_SUBSTITUTE_OVERFLOW_LENGTH
1284 substitute_replacement_only PCRE2_SUBSTITUTE_REPLACEMENT_ONLY
1285 substitute_unknown_unset PCRE2_SUBSTITUTE_UNKNOWN_UNSET
1286 substitute_unset_empty PCRE2_SUBSTITUTE_UNSET_EMPTY
1287 See the pcre2api documentation for details of these options.
1289 After a successful substitution, the modified string is output, pre‐
1291 ceded by the number of replacements. This may be zero if there were no
1292 matches. Here is a simple example of a substitution test:
1293 /abc/replace=xxx
1295 =abc=abc=
1296 1: =xxx=abc=
1297 =abc=abc=\=global
1298 2: =xxx=xxx=
1299 Subject and replacement strings should be kept relatively short (fewer
1301 than 256 characters) for substitution tests, as fixed-size buffers are
1302 used. To make it easy to test for buffer overflow, if the replacement
1303 string starts with a number in square brackets, that number is passed
1304 to pcre2_substitute() as the size of the output buffer, with the
1305 replacement string starting at the next character. Here is an example
1306 that tests the edge case:
1307 /abc/
1309 123abc123\=replace=[10]XYZ
1310 1: 123XYZ123
1311 123abc123\=replace=[9]XYZ
1312 Failed: error -47: no more memory
1313 The default action of pcre2_substitute() is to return
1315 PCRE2_ERROR_NOMEMORY when the output buffer is too small. However, if
1316 the PCRE2_SUBSTITUTE_OVERFLOW_LENGTH option is set (by using the sub‐
1317 stitute_overflow_length modifier), pcre2_substitute() continues to go
1318 through the motions of matching and substituting (but not doing any
1319 callouts), in order to compute the size of buffer that is required.
1320 When this happens, pcre2test shows the required buffer length (which
1321 includes space for the trailing zero) as part of the error message. For
1322 example:
1323 /abc/substitute_overflow_length
1325 123abc123\=replace=[9]XYZ
1326 Failed: error -47: no more memory: 10 code units are needed
1327 A replacement string is ignored with POSIX and DFA matching. Specifying
1329 partial matching provokes an error return ("bad option value") from
1330 pcre2_substitute().
1331 Testing substitute callouts
1333 If the substitute_callout modifier is set, a substitution callout func‐
1335 tion is set up. The null_context modifier must not be set, because the
1336 address of the callout function is passed in a match context. When the
1337 callout function is called (after each substitution), details of the
1338 the input and output strings are output. For example:
1339 /abc/g,replace=<$0>,substitute_callout
1341 abcdefabcpqr
1342 1(1) Old 0 3 "abc" New 0 5 "<abc>"
1343 2(1) Old 6 9 "abc" New 8 13 "<abc>"
1344 2: <abc>def<abc>pqr
1345 The first number on each callout line is the count of matches. The
1347 parenthesized number is the number of pairs that are set in the ovector
1348 (that is, one more than the number of capturing groups that were set).
1349 Then are listed the offsets of the old substring, its contents, and the
1350 same for the replacement.
1351 By default, the substitution callout function returns zero, which
1353 accepts the replacement and causes matching to continue if /g was used.
1354 Two further modifiers can be used to test other return values. If sub‐
1355 stitute_skip is set to a value greater than zero the callout function
1356 returns +1 for the match of that number, and similarly substitute_stop
1357 returns -1. These cause the replacement to be rejected, and -1 causes
1358 no further matching to take place. If either of them are set, substi‐
1359 tute_callout is assumed. For example:
1360 /abc/g,replace=<$0>,substitute_skip=1
1362 abcdefabcpqr
1363 1(1) Old 0 3 "abc" New 0 5 "<abc> SKIPPED"
1364 2(1) Old 6 9 "abc" New 6 11 "<abc>"
1365 2: abcdef<abc>pqr
1366 abcdefabcpqr\=substitute_stop=1
1367 1(1) Old 0 3 "abc" New 0 5 "<abc> STOPPED"
1368 1: abcdefabcpqr
1369 If both are set for the same number, stop takes precedence. Only a sin‐
1371 gle skip or stop is supported, which is sufficient for testing that the
1372 feature works.
1373 Setting the JIT stack size
1375 The jitstack modifier provides a way of setting the maximum stack size
1377 that is used by the just-in-time optimization code. It is ignored if
1378 JIT optimization is not being used. The value is a number of kibibytes
1379 (units of 1024 bytes). Setting zero reverts to the default of 32KiB.
1380 Providing a stack that is larger than the default is necessary only for
1381 very complicated patterns. If jitstack is set non-zero on a subject
1382 line it overrides any value that was set on the pattern.
1383 Setting heap, match, and depth limits
1385 The heap_limit, match_limit, and depth_limit modifiers set the appro‐
1387 priate limits in the match context. These values are ignored when the
1388 find_limits modifier is specified.
1389 Finding minimum limits
1391 If the find_limits modifier is present on a subject line, pcre2test
1393 calls the relevant matching function several times, setting different
1394 values in the match context via pcre2_set_heap_limit(),
1395 pcre2_set_match_limit(), or pcre2_set_depth_limit() until it finds the
1396 minimum values for each parameter that allows the match to complete
1397 without error. If JIT is being used, only the match limit is relevant.
1398 When using this modifier, the pattern should not contain any limit set‐
1400 tings such as (*LIMIT_MATCH=...) within it. If such a setting is
1401 present and is lower than the minimum matching value, the minimum value
1402 cannot be found because pcre2_set_match_limit() etc. are only able to
1403 reduce the value of an in-pattern limit; they cannot increase it.
1404 For non-DFA matching, the minimum depth_limit number is a measure of
1406 how much nested backtracking happens (that is, how deeply the pattern's
1407 tree is searched). In the case of DFA matching, depth_limit controls
1408 the depth of recursive calls of the internal function that is used for
1409 handling pattern recursion, lookaround assertions, and atomic groups.
1410 For non-DFA matching, the match_limit number is a measure of the amount
1412 of backtracking that takes place, and learning the minimum value can be
1413 instructive. For most simple matches, the number is quite small, but
1414 for patterns with very large numbers of matching possibilities, it can
1415 become large very quickly with increasing length of subject string. In
1416 the case of DFA matching, match_limit controls the total number of
1417 calls, both recursive and non-recursive, to the internal matching func‐
1418 tion, thus controlling the overall amount of computing resource that is
1419 used.
1420 For both kinds of matching, the heap_limit number, which is in
1422 kibibytes (units of 1024 bytes), limits the amount of heap memory used
1423 for matching. A value of zero disables the use of any heap memory; many
1424 simple pattern matches can be done without using the heap, so zero is
1425 not an unreasonable setting.
1426 Showing MARK names
1428 The mark modifier causes the names from backtracking control verbs that
1431 are returned from calls to pcre2_match() to be displayed. If a mark is
1432 returned for a match, non-match, or partial match, pcre2test shows it.
1433 For a match, it is on a line by itself, tagged with "MK:". Otherwise,
1434 it is added to the non-match message.
1435 Showing memory usage
1437 The memory modifier causes pcre2test to log the sizes of all heap mem‐
1439 ory allocation and freeing calls that occur during a call to
1440 pcre2_match() or pcre2_dfa_match(). These occur only when a match
1441 requires a bigger vector than the default for remembering backtracking
1442 points (pcre2_match()) or for internal workspace (pcre2_dfa_match()).
1443 In many cases there will be no heap memory used and therefore no addi‐
1444 tional output. No heap memory is allocated during matching with JIT, so
1445 in that case the memory modifier never has any effect. For this modi‐
1446 fier to work, the null_context modifier must not be set on both the
1447 pattern and the subject, though it can be set on one or the other.
1448 Setting a starting offset
1450 The offset modifier sets an offset in the subject string at which
1452 matching starts. Its value is a number of code units, not characters.
1453 Setting an offset limit
1455 The offset_limit modifier sets a limit for unanchored matches. If a
1457 match cannot be found starting at or before this offset in the subject,
1458 a "no match" return is given. The data value is a number of code units,
1459 not characters. When this modifier is used, the use_offset_limit modi‐
1460 fier must have been set for the pattern; if not, an error is generated.
1461 Setting the size of the output vector
1463 The ovector modifier applies only to the subject line in which it
1465 appears, though of course it can also be used to set a default in a
1466 #subject command. It specifies the number of pairs of offsets that are
1467 available for storing matching information. The default is 15.
1468 A value of zero is useful when testing the POSIX API because it causes
1470 regexec() to be called with a NULL capture vector. When not testing the
1471 POSIX API, a value of zero is used to cause pcre2_match_data_cre‐
1472 ate_from_pattern() to be called, in order to create a match block of
1473 exactly the right size for the pattern. (It is not possible to create a
1474 match block with a zero-length ovector; there is always at least one
1475 pair of offsets.)
1476 Passing the subject as zero-terminated
1478 By default, the subject string is passed to a native API matching func‐
1480 tion with its correct length. In order to test the facility for passing
1481 a zero-terminated string, the zero_terminate modifier is provided. It
1482 causes the length to be passed as PCRE2_ZERO_TERMINATED. When matching
1483 via the POSIX interface, this modifier is ignored, with a warning.
1484 When testing pcre2_substitute(), this modifier also has the effect of
1486 passing the replacement string as zero-terminated.
1487 Passing a NULL context
1489 Normally, pcre2test passes a context block to pcre2_match(),
1491 pcre2_dfa_match(), pcre2_jit_match() or pcre2_substitute(). If the
1492 null_context modifier is set, however, NULL is passed. This is for
1493 testing that the matching and substitution functions behave correctly
1494 in this case (they use default values). This modifier cannot be used
1495 with the find_limits or substitute_callout modifiers.
1496
1498 By default, pcre2test uses the standard PCRE2 matching function,
1500 pcre2_match() to match each subject line. PCRE2 also supports an alter‐
1501 native matching function, pcre2_dfa_match(), which operates in a dif‐
1502 ferent way, and has some restrictions. The differences between the two
1503 functions are described in the pcre2matching documentation.
1504 If the dfa modifier is set, the alternative matching function is used.
1506 This function finds all possible matches at a given point in the sub‐
1507 ject. If, however, the dfa_shortest modifier is set, processing stops
1508 after the first match is found. This is always the shortest possible
1509 match.
1510
1512 This section describes the output when the normal matching function,
1514 pcre2_match(), is being used.
1515 When a match succeeds, pcre2test outputs the list of captured sub‐
1517 strings, starting with number 0 for the string that matched the whole
1518 pattern. Otherwise, it outputs "No match" when the return is
1519 PCRE2_ERROR_NOMATCH, or "Partial match:" followed by the partially
1520 matching substring when the return is PCRE2_ERROR_PARTIAL. (Note that
1521 this is the entire substring that was inspected during the partial
1522 match; it may include characters before the actual match start if a
1523 lookbehind assertion, \K, \b, or \B was involved.)
1524 For any other return, pcre2test outputs the PCRE2 negative error number
1526 and a short descriptive phrase. If the error is a failed UTF string
1527 check, the code unit offset of the start of the failing character is
1528 also output. Here is an example of an interactive pcre2test run.
1529 $ pcre2test
1531 PCRE2 version 10.22 2016-07-29
1532 re> /^abc(\d+)/
1534 data> abc123
1535 0: abc123
1536 1: 123
1537 data> xyz
1538 No match
1539 Unset capturing substrings that are not followed by one that is set are
1541 not shown by pcre2test unless the allcaptures modifier is specified. In
1542 the following example, there are two capturing substrings, but when the
1543 first data line is matched, the second, unset substring is not shown.
1544 An "internal" unset substring is shown as "<unset>", as for the second
1545 data line.
1546 re> /(a)|(b)/
1548 data> a
1549 0: a
1550 1: a
1551 data> b
1552 0: b
1553 1: <unset>
1554 2: b
1555 If the strings contain any non-printing characters, they are output as
1557 \xhh escapes if the value is less than 256 and UTF mode is not set.
1558 Otherwise they are output as \x{hh...} escapes. See below for the defi‐
1559 nition of non-printing characters. If the aftertext modifier is set,
1560 the output for substring 0 is followed by the the rest of the subject
1561 string, identified by "0+" like this:
1562 re> /cat/aftertext
1564 data> cataract
1565 0: cat
1566 0+ aract
1567 If global matching is requested, the results of successive matching
1569 attempts are output in sequence, like this:
1570 re> /\Bi(\w\w)/g
1572 data> Mississippi
1573 0: iss
1574 1: ss
1575 0: iss
1576 1: ss
1577 0: ipp
1578 1: pp
1579 "No match" is output only if the first match attempt fails. Here is an
1581 example of a failure message (the offset 4 that is specified by the
1582 offset modifier is past the end of the subject string):
1583 re> /xyz/
1585 data> xyz\=offset=4
1586 Error -24 (bad offset value)
1587 Note that whereas patterns can be continued over several lines (a plain
1589 ">" prompt is used for continuations), subject lines may not. However
1590 newlines can be included in a subject by means of the \n escape (or \r,
1591 \r\n, etc., depending on the newline sequence setting).
1592
1594 When the alternative matching function, pcre2_dfa_match(), is used, the
1596 output consists of a list of all the matches that start at the first
1597 point in the subject where there is at least one match. For example:
1598 re> /(tang|tangerine|tan)/
1600 data> yellow tangerine\=dfa
1601 0: tangerine
1602 1: tang
1603 2: tan
1604 Using the normal matching function on this data finds only "tang". The
1606 longest matching string is always given first (and numbered zero).
1607 After a PCRE2_ERROR_PARTIAL return, the output is "Partial match:",
1608 followed by the partially matching substring. Note that this is the
1609 entire substring that was inspected during the partial match; it may
1610 include characters before the actual match start if a lookbehind asser‐
1611 tion, \b, or \B was involved. (\K is not supported for DFA matching.)
1612 If global matching is requested, the search for further matches resumes
1614 at the end of the longest match. For example:
1615 re> /(tang|tangerine|tan)/g
1617 data> yellow tangerine and tangy sultana\=dfa
1618 0: tangerine
1619 1: tang
1620 2: tan
1621 0: tang
1622 1: tan
1623 0: tan
1624 The alternative matching function does not support substring capture,
1626 so the modifiers that are concerned with captured substrings are not
1627 relevant.
1628
1630 When the alternative matching function has given the PCRE2_ERROR_PAR‐
1632 TIAL return, indicating that the subject partially matched the pattern,
1633 you can restart the match with additional subject data by means of the
1634 dfa_restart modifier. For example:
1635 re> /^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$/
1637 data> 23ja\=ps,dfa
1638 Partial match: 23ja
1639 data> n05\=dfa,dfa_restart
1640 0: n05
1641 For further information about partial matching, see the pcre2partial
1643 documentation.
1644
1646 If the pattern contains any callout requests, pcre2test's callout func‐
1648 tion is called during matching unless callout_none is specified. This
1649 works with both matching functions, and with JIT, though there are some
1650 differences in behaviour. The output for callouts with numerical argu‐
1651 ments and those with string arguments is slightly different.
1652 Callouts with numerical arguments
1654 By default, the callout function displays the callout number, the start
1656 and current positions in the subject text at the callout time, and the
1657 next pattern item to be tested. For example:
1658 --->pqrabcdef
1660 0 ^ ^ \d
1661 This output indicates that callout number 0 occurred for a match
1663 attempt starting at the fourth character of the subject string, when
1664 the pointer was at the seventh character, and when the next pattern
1665 item was \d. Just one circumflex is output if the start and current
1666 positions are the same, or if the current position precedes the start
1667 position, which can happen if the callout is in a lookbehind assertion.
1668 Callouts numbered 255 are assumed to be automatic callouts, inserted as
1670 a result of the auto_callout pattern modifier. In this case, instead of
1671 showing the callout number, the offset in the pattern, preceded by a
1672 plus, is output. For example:
1673 re> /\d?[A-E]\*/auto_callout
1675 data> E*
1676 --->E*
1677 +0 ^ \d?
1678 +3 ^ [A-E]
1679 +8 ^^ \*
1680 +10 ^ ^
1681 0: E*
1682 If a pattern contains (*MARK) items, an additional line is output when‐
1684 ever a change of latest mark is passed to the callout function. For
1685 example:
1686 re> /a(*MARK:X)bc/auto_callout
1688 data> abc
1689 --->abc
1690 +0 ^ a
1691 +1 ^^ (*MARK:X)
1692 +10 ^^ b
1693 Latest Mark: X
1694 +11 ^ ^ c
1695 +12 ^ ^
1696 0: abc
1697 The mark changes between matching "a" and "b", but stays the same for
1699 the rest of the match, so nothing more is output. If, as a result of
1700 backtracking, the mark reverts to being unset, the text "<unset>" is
1701 output.
1702 Callouts with string arguments
1704 The output for a callout with a string argument is similar, except that
1706 instead of outputting a callout number before the position indicators,
1707 the callout string and its offset in the pattern string are output
1708 before the reflection of the subject string, and the subject string is
1709 reflected for each callout. For example:
1710 re> /^ab(?C'first')cd(?C"second")ef/
1712 data> abcdefg
1713 Callout (7): 'first'
1714 --->abcdefg
1715 ^ ^ c
1716 Callout (20): "second"
1717 --->abcdefg
1718 ^ ^ e
1719 0: abcdef
1720 Callout modifiers
1723 The callout function in pcre2test returns zero (carry on matching) by
1725 default, but you can use a callout_fail modifier in a subject line to
1726 change this and other parameters of the callout (see below).
1727 If the callout_capture modifier is set, the current captured groups are
1729 output when a callout occurs. This is useful only for non-DFA matching,
1730 as pcre2_dfa_match() does not support capturing, so no captures are
1731 ever shown.
1732 The normal callout output, showing the callout number or pattern offset
1734 (as described above) is suppressed if the callout_no_where modifier is
1735 set.
1736 When using the interpretive matching function pcre2_match() without
1738 JIT, setting the callout_extra modifier causes additional output from
1739 pcre2test's callout function to be generated. For the first callout in
1740 a match attempt at a new starting position in the subject, "New match
1741 attempt" is output. If there has been a backtrack since the last call‐
1742 out (or start of matching if this is the first callout), "Backtrack" is
1743 output, followed by "No other matching paths" if the backtrack ended
1744 the previous match attempt. For example:
1745 re> /(a+)b/auto_callout,no_start_optimize,no_auto_possess
1747 data> aac\=callout_extra
1748 New match attempt
1749 --->aac
1750 +0 ^ (
1751 +1 ^ a+
1752 +3 ^ ^ )
1753 +4 ^ ^ b
1754 Backtrack
1755 --->aac
1756 +3 ^^ )
1757 +4 ^^ b
1758 Backtrack
1759 No other matching paths
1760 New match attempt
1761 --->aac
1762 +0 ^ (
1763 +1 ^ a+
1764 +3 ^^ )
1765 +4 ^^ b
1766 Backtrack
1767 No other matching paths
1768 New match attempt
1769 --->aac
1770 +0 ^ (
1771 +1 ^ a+
1772 Backtrack
1773 No other matching paths
1774 New match attempt
1775 --->aac
1776 +0 ^ (
1777 +1 ^ a+
1778 No match
1779 Notice that various optimizations must be turned off if you want all
1781 possible matching paths to be scanned. If no_start_optimize is not
1782 used, there is an immediate "no match", without any callouts, because
1783 the starting optimization fails to find "b" in the subject, which it
1784 knows must be present for any match. If no_auto_possess is not used,
1785 the "a+" item is turned into "a++", which reduces the number of back‐
1786 tracks.
1787 The callout_extra modifier has no effect if used with the DFA matching
1789 function, or with JIT.
1790 Return values from callouts
1792 The default return from the callout function is zero, which allows
1794 matching to continue. The callout_fail modifier can be given one or two
1795 numbers. If there is only one number, 1 is returned instead of 0 (caus‐
1796 ing matching to backtrack) when a callout of that number is reached. If
1797 two numbers (<n>:<m>) are given, 1 is returned when callout <n> is
1798 reached and there have been at least <m> callouts. The callout_error
1799 modifier is similar, except that PCRE2_ERROR_CALLOUT is returned, caus‐
1800 ing the entire matching process to be aborted. If both these modifiers
1801 are set for the same callout number, callout_error takes precedence.
1802 Note that callouts with string arguments are always given the number
1803 zero.
1804 The callout_data modifier can be given an unsigned or a negative num‐
1806 ber. This is set as the "user data" that is passed to the matching
1807 function, and passed back when the callout function is invoked. Any
1808 value other than zero is used as a return from pcre2test's callout
1809 function.
1810 Inserting callouts can be helpful when using pcre2test to check compli‐
1812 cated regular expressions. For further information about callouts, see
1813 the pcre2callout documentation.
1814
1816 When pcre2test is outputting text in the compiled version of a pattern,
1818 bytes other than 32-126 are always treated as non-printing characters
1819 and are therefore shown as hex escapes.
1820 When pcre2test is outputting text that is a matched part of a subject
1822 string, it behaves in the same way, unless a different locale has been
1823 set for the pattern (using the locale modifier). In this case, the
1824 isprint() function is used to distinguish printing and non-printing
1825 characters.
1826
1828 It is possible to save compiled patterns on disc or elsewhere, and
1830 reload them later, subject to a number of restrictions. JIT data cannot
1831 be saved. The host on which the patterns are reloaded must be running
1832 the same version of PCRE2, with the same code unit width, and must also
1833 have the same endianness, pointer width and PCRE2_SIZE type. Before
1834 compiled patterns can be saved they must be serialized, that is, con‐
1835 verted to a stream of bytes. A single byte stream may contain any num‐
1836 ber of compiled patterns, but they must all use the same character
1837 tables. A single copy of the tables is included in the byte stream (its
1838 size is 1088 bytes).
1839 The functions whose names begin with pcre2_serialize_ are used for
1841 serializing and de-serializing. They are described in the pcre2serial‐
1842 ize documentation. In this section we describe the features of
1843 pcre2test that can be used to test these functions.
1844 Note that "serialization" in PCRE2 does not convert compiled patterns
1846 to an abstract format like Java or .NET. It just makes a reloadable
1847 byte code stream. Hence the restrictions on reloading mentioned above.
1848 In pcre2test, when a pattern with push modifier is successfully com‐
1850 piled, it is pushed onto a stack of compiled patterns, and pcre2test
1851 expects the next line to contain a new pattern (or command) instead of
1852 a subject line. By contrast, the pushcopy modifier causes a copy of the
1853 compiled pattern to be stacked, leaving the original available for
1854 immediate matching. By using push and/or pushcopy, a number of patterns
1855 can be compiled and retained. These modifiers are incompatible with
1856 posix, and control modifiers that act at match time are ignored (with a
1857 message) for the stacked patterns. The jitverify modifier applies only
1858 at compile time.
1859 The command
1861 #save <filename>
1863 causes all the stacked patterns to be serialized and the result written
1865 to the named file. Afterwards, all the stacked patterns are freed. The
1866 command
1867 #load <filename>
1869 reads the data in the file, and then arranges for it to be de-serial‐
1871 ized, with the resulting compiled patterns added to the pattern stack.
1872 The pattern on the top of the stack can be retrieved by the #pop com‐
1873 mand, which must be followed by lines of subjects that are to be
1874 matched with the pattern, terminated as usual by an empty line or end
1875 of file. This command may be followed by a modifier list containing
1876 only control modifiers that act after a pattern has been compiled. In
1877 particular, hex, posix, posix_nosub, push, and pushcopy are not
1878 allowed, nor are any option-setting modifiers. The JIT modifiers are,
1879 however permitted. Here is an example that saves and reloads two pat‐
1880 terns.
1881 /abc/push
1883 /xyz/push
1884 #save tempfile
1885 #load tempfile
1886 #pop info
1887 xyz
1888 #pop jit,bincode
1890 abc
1891 If jitverify is used with #pop, it does not automatically imply jit,
1893 which is different behaviour from when it is used on a pattern.
1894 The #popcopy command is analagous to the pushcopy modifier in that it
1896 makes current a copy of the topmost stack pattern, leaving the original
1897 still on the stack.
1898
1900 pcre2(3), pcre2api(3), pcre2callout(3), pcre2jit, pcre2matching(3),
1902 pcre2partial(d), pcre2pattern(3), pcre2serialize(3).
1903
1905 Philip Hazel
1907 University Computing Service
1908 Cambridge, England.
1909
1911 Last updated: 14 September 2020
1913 Copyright (c) 1997-2020 University of Cambridge.
1914PCRE 10.36 14 September 2020 PCRE2TEST(1)