| <!DOCTYPE html><html lang="en"><head><meta charset="UTF-8"><meta http-equiv="X-UA-Compatible" content="IE=edge"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="Asciidoctor 2.0.26"><meta name="description" content="The `pcre2test` command for testing PCRE2"><title>pcre2test(1)</title><link rel="stylesheet" href="./css/document.css"><link rel="stylesheet" href="./css/standalone.css"><meta name="color-scheme" content="light dark"><meta name="theme-color" media="(prefers-color-scheme: light)" content="#0085cc"><meta name="theme-color" media="(prefers-color-scheme: dark)" content="#33b8ff"></head><body class="manpage toc2 toc-right offline-manual"><header class="offline-nav"><nav><a class="offline-index" href="./index.html">Index</a><a class="offline-home" href="https://www.pcre2.org/"><span aria-hidden="true">🌐︎</span> PCRE2 homepage</a></nav></header><main class="document-page"><header class="document-title"><h1>pcre2test(1)</h1><p class="document-meta">PCRE2 10.50-DEV manual; updated <time datetime="2026-08-22">22 Aug 2026</time></p></header><div class="document-layout"><nav id="toc" class="toc2" role="doc-toc"><h2 id="toc-title">Contents</h2><ol class="toc-list level-1"><li><a href="#_synopsis" title="Synopsis">Synopsis</a></li><li><a href="#_pcre2s_8_bit_16_bit_and_32_bit_libraries" title="PCRE2’s 8-bit, 16-bit and 32-bit libraries">PCRE2’s 8-bit, 16-bit and 32-bit libraries</a></li><li><a href="#_input_encoding" title="Input encoding">Input encoding</a><ol class="toc-list level-2"><li><a href="#_input_for_the_16_bit_and_32_bit_libraries" title="Input for the 16-bit and 32-bit libraries">Input for the 16-bit and 32-bit libraries</a></li></ol></li><li><a href="#_command_line_options" title="Command line options">Command line options</a></li><li><a href="#_description" title="Description">Description</a></li><li><a href="#_command_lines" title="Command lines">Command lines</a></li><li><a href="#_modifier_syntax" title="Modifier syntax">Modifier syntax</a></li><li><a href="#_pattern_syntax" title="Pattern syntax">Pattern syntax</a></li><li><a href="#_subject_line_syntax" title="Subject line syntax">Subject line syntax</a></li><li><a href="#_pattern_modifiers" title="Pattern modifiers">Pattern modifiers</a><ol class="toc-list level-2"><li><a href="#_setting_compilation_options" title="Setting compilation options">Setting compilation options</a></li><li><a href="#_setting_compilation_controls" title="Setting compilation controls">Setting compilation controls</a></li><li><a href="#_newline_and_r_handling" title="Newline and \R handling">Newline and \R handling</a></li><li><a href="#_information_about_a_pattern" title="Information about a pattern">Information about a pattern</a></li><li><a href="#_passing_a_null_context" title="Passing a NULL context">Passing a <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> context</a></li><li><a href="#_passing_a_null_pattern" title="Passing a NULL pattern">Passing a <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> pattern</a></li><li><a href="#_specifying_pattern_characters_in_hexadecimal" title="Specifying pattern characters in hexadecimal">Specifying pattern characters in hexadecimal</a></li><li><a href="#_specifying_the_patterns_length" title="Specifying the pattern’s length">Specifying the pattern’s length</a></li><li><a href="#_specifying_a_maximum_for_variable_lookbehinds" title="Specifying a maximum for variable lookbehinds">Specifying a maximum for variable lookbehinds</a></li><li><a href="#_specifying_wide_characters_in_16_bit_and_32_bit_modes" title="Specifying wide characters in 16-bit and 32-bit modes">Specifying wide characters in 16-bit and 32-bit modes</a></li><li><a href="#_generating_long_repetitive_patterns" title="Generating long repetitive patterns">Generating long repetitive patterns</a></li><li><a href="#_jit_compilation" title="JIT compilation">JIT compilation</a></li><li><a href="#_setting_a_locale" title="Setting a locale">Setting a locale</a></li><li><a href="#_showing_pattern_memory" title="Showing pattern memory">Showing pattern memory</a></li><li><a href="#_limiting_nested_parentheses" title="Limiting nested parentheses">Limiting nested parentheses</a></li><li><a href="#_limiting_the_pattern_length" title="Limiting the pattern length">Limiting the pattern length</a></li><li><a href="#_limiting_the_size_of_a_compiled_pattern" title="Limiting the size of a compiled pattern">Limiting the size of a compiled pattern</a></li><li><a href="#_using_the_posix_wrapper_api" title="Using the POSIX wrapper API">Using the POSIX wrapper API</a></li><li><a href="#_testing_the_stack_guard_feature" title="Testing the stack guard feature">Testing the stack guard feature</a></li><li><a href="#_using_alternative_character_tables" title="Using alternative character tables">Using alternative character tables</a></li><li><a href="#_setting_certain_match_controls" title="Setting certain match controls">Setting certain match controls</a></li><li><a href="#_specifying_literal_subject_lines" title="Specifying literal subject lines">Specifying literal subject lines</a></li><li><a href="#_saving_a_compiled_pattern" title="Saving a compiled pattern">Saving a compiled pattern</a></li><li><a href="#_testing_foreign_pattern_conversion" title="Testing foreign pattern conversion">Testing foreign pattern conversion</a></li></ol></li><li><a href="#_subject_modifiers" title="Subject modifiers">Subject modifiers</a><ol class="toc-list level-2"><li><a href="#_setting_match_options" title="Setting match options">Setting match options</a></li><li><a href="#_setting_match_controls" title="Setting match controls">Setting match controls</a></li><li><a href="#_showing_more_text" title="Showing more text">Showing more text</a></li><li><a href="#_showing_the_value_of_all_capture_groups" title="Showing the value of all capture groups">Showing the value of all capture groups</a></li><li><a href="#_showing_the_entire_ovector_for_all_outcomes" title="Showing the entire ovector, for all outcomes">Showing the entire ovector, for all outcomes</a></li><li><a href="#_testing_pattern_callouts" title="Testing pattern callouts">Testing pattern callouts</a></li><li><a href="#_finding_all_matches_in_a_string" title="Finding all matches in a string">Finding all matches in a string</a></li><li><a href="#_testing_substring_extraction_functions" title="Testing substring extraction functions">Testing substring extraction functions</a></li><li><a href="#_testing_the_substitution_function" title="Testing the substitution function">Testing the substitution function</a></li><li><a href="#_testing_substitute_callouts" title="Testing substitute callouts">Testing substitute callouts</a></li><li><a href="#_testing_substitute_case_callouts" title="Testing substitute case callouts">Testing substitute case callouts</a></li><li><a href="#_setting_the_jit_stack_size" title="Setting the JIT stack size">Setting the JIT stack size</a></li><li><a href="#_setting_heap_match_and_depth_limits" title="Setting heap, match, and depth limits">Setting heap, match, and depth limits</a></li><li><a href="#_finding_minimum_limits" title="Finding minimum limits">Finding minimum limits</a></li><li><a href="#_showing_mark_names" title="Showing MARK names">Showing MARK names</a></li><li><a href="#_showing_memory_usage" title="Showing memory usage">Showing memory usage</a></li><li><a href="#_showing_the_heap_frame_overall_vector_size" title="Showing the heap frame overall vector size">Showing the heap frame overall vector size</a></li><li><a href="#_setting_a_starting_offset" title="Setting a starting offset">Setting a starting offset</a></li><li><a href="#_setting_an_offset_limit" title="Setting an offset limit">Setting an offset limit</a></li><li><a href="#_setting_the_size_of_the_output_vector" title="Setting the size of the output vector">Setting the size of the output vector</a></li><li><a href="#_passing_the_subject_as_zero_terminated" title="Passing the subject as zero-terminated">Passing the subject as zero-terminated</a></li><li><a href="#_passing_a_null_context_subject_replacement_or_substitute_buffer" title="Passing a NULL context, subject, replacement, or substitute buffer">Passing a <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> context, subject, replacement, or substitute buffer</a></li></ol></li><li><a href="#_the_alternative_matching_function" title="The alternative matching function">The alternative matching function</a></li><li><a href="#_default_output_from_pcre2test" title="Default output from pcre2test">Default output from pcre2test</a></li><li><a href="#_output_from_the_alternative_matching_function" title="Output from the alternative matching function">Output from the alternative matching function</a></li><li><a href="#_restarting_after_a_partial_match" title="Restarting after a partial match">Restarting after a partial match</a></li><li><a href="#callouts" title="Callouts">Callouts</a><ol class="toc-list level-2"><li><a href="#_callouts_with_numerical_arguments" title="Callouts with numerical arguments">Callouts with numerical arguments</a></li><li><a href="#_callouts_with_string_arguments" title="Callouts with string arguments">Callouts with string arguments</a></li><li><a href="#_callout_modifiers" title="Callout modifiers">Callout modifiers</a></li><li><a href="#_return_values_from_callouts" title="Return values from callouts">Return values from callouts</a></li></ol></li><li><a href="#_non_printing_characters" title="Non-printing characters">Non-printing characters</a></li><li><a href="#saving-restoring-patterns" title="Saving and restoring compiled patterns">Saving and restoring compiled patterns</a></li><li><a href="#_see_also" title="See also">See also</a></li></ol></nav><article class="prose" id="content"><section class="doc-section level-1"><h2 id="_synopsis">Synopsis</h2><div class="listing-block synopsis"><pre class="rouge highlight"><code data-lang="shell">pcre2test <span class="o">[</span>options] <span class="o">[</span>input file <span class="o">[</span>output file]]</code></pre></div> | |
| <p><code>pcre2test</code> is a test program for the PCRE2 regular expression libraries, | |
| but it can also be used for experimenting with regular expressions. This | |
| document describes the features of the test program; for details of the regular | |
| expressions themselves, see the | |
| <a href="./pcre2pattern.html"><code>pcre2pattern</code></a> | |
| documentation. For details of the PCRE2 library function calls and their | |
| options, see the | |
| <a href="./pcre2api.html"><code>pcre2api</code></a> | |
| documentation.</p> | |
| <p>The input for <code>pcre2test</code> is a sequence of regular expression patterns and | |
| subject strings to be matched. There are also command lines for setting | |
| defaults and controlling some special actions. The output shows the result of | |
| each match attempt. Modifiers on external or internal command lines, the | |
| patterns, and the subject lines specify PCRE2 function options, control how the | |
| subject is processed, and what output is produced.</p> | |
| <p>There are many obscure modifiers, some of which are specifically designed for | |
| use in conjunction with the test script and data files that are distributed as | |
| part of PCRE2. All the modifiers are documented here, some without much | |
| justification, but many of them are unlikely to be of use except when testing | |
| the libraries.</p></section> | |
| <section class="doc-section level-1"><h2 id="_pcre2s_8_bit_16_bit_and_32_bit_libraries">PCRE2’s 8-bit, 16-bit and 32-bit libraries</h2><p>Different versions of the PCRE2 library can be built to support character | |
| strings that are encoded in 8-bit, 16-bit, or 32-bit code units. One, two, or | |
| all three of these libraries may be simultaneously installed. The | |
| <code>pcre2test</code> program can be used to test all the libraries. However, its own | |
| input and output are always in 8-bit format. When testing the 16-bit or 32-bit | |
| libraries, patterns and subject strings are converted to 16-bit or 32-bit | |
| format before being passed to the library functions. Results are converted back | |
| to 8-bit code units for output.</p> | |
| <p>In the rest of this document, the names of library functions and structures | |
| are given in generic form, for example, <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code>. The actual | |
| names used in the libraries have a suffix <code>_8</code>, <code>_16</code>, or <code>_32</code>, as appropriate.</p></section> | |
| <section class="doc-section level-1"><h2 id="_input_encoding">Input encoding</h2><p>Input to <code>pcre2test</code> is processed line by line, either by calling the C | |
| library’s <code class="c rouge" data-lang="c"><span class="nf">fgets</span><span class="p">()</span></code> function, or via the <code>libreadline</code> or <code>libedit</code> | |
| library. In some Windows environments character 26 (<span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-1"><code class="character pcre2-api rouge"><span class="sc">0x1A</span></code><span class="character-card" id="pcre2-character-1" role="tooltip" aria-label="SUBSTITUTE (U+001A)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="SUBSTITUTE"></span><span class="character-codepoint" data-codepoint="U+001A"></span></span></span>) causes an immediate | |
| end of file, and no further data is read, so this character should be avoided | |
| unless you really want that action.</p> | |
| <p>The input is processed using C’s string functions, so must not contain binary | |
| zeros, even though in Unix-like environments, <code class="c rouge" data-lang="c"><span class="nf">fgets</span><span class="p">()</span></code> treats any bytes | |
| other than newline as data characters. An error is generated if a binary zero | |
| is encountered. By default subject lines are processed for backslash escapes, | |
| which makes it possible to include any data value in strings that are passed to | |
| the library for matching. For patterns, there is a facility for specifying some | |
| or all of the 8-bit input characters as hexadecimal pairs, which makes it | |
| possible to include binary zeros.</p> | |
| <section class="doc-section level-2"><h3 id="_input_for_the_16_bit_and_32_bit_libraries">Input for the 16-bit and 32-bit libraries</h3><p>When testing the 16-bit or 32-bit libraries, there is a need to be able to | |
| generate character code points greater than 255 in the strings that are passed | |
| to the library. For subject lines and some patterns, backslash escapes can be | |
| used. In addition, when the <code>utf</code> modifier (see | |
| "Setting compilation options" | |
| below) is set, the pattern and any following subject lines are interpreted as | |
| UTF-8 strings and translated to UTF-16 or UTF-32 as appropriate.</p> | |
| <p>For non-UTF testing of wide characters, the <code>utf8_input</code> modifier can be | |
| used. This is mutually exclusive with <code>utf</code>, and is allowed only in 16-bit | |
| or 32-bit mode. It causes the pattern and following subject lines to be treated | |
| as UTF-8 according to the original definition (RFC 2279), which allows for | |
| character values up to <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-2"><code class="character pcre2-api rouge"><span class="sc">0x7fffffff</span></code><span class="character-card" id="pcre2-character-2" role="tooltip" aria-label="Outside Unicode range (0x7fffffff)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="Outside Unicode range"></span><span class="character-codepoint" data-codepoint="0x7fffffff"></span></span></span>. Each character is placed in one 16-bit or | |
| 32-bit code unit (in the 16-bit case, values greater than <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-3"><code class="character pcre2-api rouge"><span class="sc">0xffff</span></code><span class="character-card" id="pcre2-character-3" role="tooltip" aria-label="<noncharacter-FFFF> (U+FFFF)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="<noncharacter-FFFF>"></span><span class="character-codepoint" data-codepoint="U+FFFF"></span></span></span> cause an error | |
| to occur).</p> | |
| <p>UTF-8 (in its original definition) is not capable of encoding values greater | |
| than <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-4"><code class="character pcre2-api rouge"><span class="sc">0x7fffffff</span></code><span class="character-card" id="pcre2-character-4" role="tooltip" aria-label="Outside Unicode range (0x7fffffff)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="Outside Unicode range"></span><span class="character-codepoint" data-codepoint="0x7fffffff"></span></span></span>, but such values can be handled by the 32-bit library. When | |
| testing this library in non-UTF mode with <code>utf8_input</code> set, if any | |
| character is preceded by the byte <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-5"><code class="character pcre2-api rouge"><span class="sc">0xff</span></code><span class="character-card" id="pcre2-character-5" role="tooltip" aria-label="LATIN SMALL LETTER Y WITH DIAERESIS (U+00FF)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character="ÿ"></span><span class="character-name" data-character-name="LATIN SMALL LETTER Y WITH DIAERESIS"></span><span class="character-codepoint" data-codepoint="U+00FF"></span></span></span> (which is an invalid byte in UTF-8) | |
| <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-6"><code class="character pcre2-api rouge"><span class="sc">0x80000000</span></code><span class="character-card" id="pcre2-character-6" role="tooltip" aria-label="Outside Unicode range (0x80000000)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="Outside Unicode range"></span><span class="character-codepoint" data-codepoint="0x80000000"></span></span></span> is added to the character’s value. For subject strings, using an | |
| escape sequence is preferable.</p></section></section> | |
| <section class="doc-section level-1"><h2 id="_command_line_options">Command line options</h2><dl class="options spaced" style="--tab-width: 12"><div class="dlist-item"><dt><span><code>-8</code></span></dt><dd>If the 8-bit library has been built, this option causes it to be used (this is | |
| the default). If the 8-bit library has not been built, this option causes an | |
| error.</dd></div><div class="dlist-item"><dt><span><code>-16</code></span></dt><dd>If the 16-bit library has been built, this option causes it to be used. If the | |
| 8-bit library has not been built, this is the default. If the 16-bit library | |
| has not been built, this option causes an error.</dd></div><div class="dlist-item"><dt><span><code>-32</code></span></dt><dd>If the 32-bit library has been built, this option causes it to be used. If no | |
| other library has been built, this is the default. If the 32-bit library has | |
| not been built, this option causes an error.</dd></div><div class="dlist-item"><dt><span><code>-ac</code></span></dt><dd>Behave as if each pattern has the <code>auto_callout</code> modifier, that is, insert | |
| automatic callouts into every pattern that is compiled.</dd></div><div class="dlist-item"><dt><span><code>-AC</code></span></dt><dd>As for <code>-ac</code>, but in addition behave as if each subject line has the | |
| <code>callout_extra</code> modifier, that is, show additional information from | |
| callouts.</dd></div><div class="dlist-item"><dt><span><code>-b</code></span></dt><dd>Behave as if each pattern has the <code>fullbincode</code> modifier; the full | |
| internal binary form of the pattern is output after compilation.</dd></div><div class="dlist-item"><dt><span><code>-C</code></span></dt><dd>Output the version number of the PCRE2 library, and all available information | |
| about the optional features that are included, and then exit with zero exit | |
| code. All other options are ignored. If both -C and -LM are present, whichever | |
| is first is recognized.</dd></div><div class="dlist-item"><dt><span><code>-C <em>option</em></code></span></dt><dd><p>Output information about a specific build-time option, then exit. This | |
| functionality is intended for use in scripts such as <code>RunTest</code>. The | |
| following options output the value and set the exit code as indicated:</p><div class="open-block"><div class="content"><dl class="compact" style="--tab-width: 6"><div class="dlist-item"><dt><span><code>linksize</code> </span></dt><dd>Output the configured internal link size (2, 3, or 4). | |
| The exit code is set to the link size.</dd></div><div class="dlist-item"><dt><span><code>newline</code> </span></dt><dd>Output the default newline setting: | |
| CR, LF, CRLF, ANYCRLF, ANY, or NUL. | |
| The exit code is always 0.</dd></div><div class="dlist-item"><dt><span><code>bsr</code> </span></dt><dd>Output the default setting for what <code class="regex rouge"><span class="pcre2-semantic">\R</span></code> matches: | |
| ANYCRLF or ANY. The exit code is always 0.</dd></div></dl></div></div> | |
| <p>The following options output 1 for true or 0 for false, and set the exit code | |
| to the same value:</p> | |
| <div class="open-block"><div class="content"><dl class="compact" style="--tab-width: 8"><div class="dlist-item"><dt><span><code>backslash-C</code> </span></dt><dd><code class="regex rouge"><span class="pcre2-semantic">\C</span></code> is supported (not locked out)</dd></div><div class="dlist-item"><dt><span><code>ebcdic</code> </span></dt><dd>compiled for an EBCDIC environment</dd></div><div class="dlist-item"><dt><span><code>ebcdic-io</code> </span></dt><dd>if PCRE2 is compiled for EBCDIC, whether <code>pcre2test</code>'s input and | |
| output is EBCDIC or ASCII</dd></div><div class="dlist-item"><dt><span><code>ebcdic-nl25</code> </span></dt><dd>if PCRE2 is compiled for EBCDIC, whether NL (= LF) is <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-7"><code class="character pcre2-api rouge"><span class="sc">0x25</span></code><span class="character-card" id="pcre2-character-7" role="tooltip" aria-label="PERCENT SIGN (U+0025)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character="%"></span><span class="character-name" data-character-name="PERCENT SIGN"></span><span class="character-codepoint" data-codepoint="U+0025"></span></span></span> | |
| (otherwise it is <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-8"><code class="character pcre2-api rouge"><span class="sc">0x15</span></code><span class="character-card" id="pcre2-character-8" role="tooltip" aria-label="NEGATIVE ACKNOWLEDGE (U+0015)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="NEGATIVE ACKNOWLEDGE"></span><span class="character-codepoint" data-codepoint="U+0015"></span></span></span>, the default)</dd></div><div class="dlist-item"><dt><span><code>jit</code> </span></dt><dd>just-in-time support is available</dd></div><div class="dlist-item"><dt><span><code>pcre2-16</code> </span></dt><dd>the 16-bit library was built</dd></div><div class="dlist-item"><dt><span><code>pcre2-32</code> </span></dt><dd>the 32-bit library was built</dd></div><div class="dlist-item"><dt><span><code>pcre2-8</code> </span></dt><dd>the 8-bit library was built</dd></div><div class="dlist-item"><dt><span><code>unicode</code> </span></dt><dd>Unicode support is available</dd></div></dl></div></div> | |
| <p>Note that the availability of JIT support in the library does not guarantee | |
| that it can actually be used because in some environments it is unable to | |
| allocate executable memory. The option "jitusable" gives more detailed | |
| information. It returns one of the following values:</p> | |
| <div class="open-block"><div class="content"><dl class="compact" style="--tab-width: 4"><div class="dlist-item"><dt><span>0</span></dt><dd>JIT is available and usable</dd></div><div class="dlist-item"><dt><span>1</span></dt><dd>JIT is available but cannot allocate executable memory</dd></div><div class="dlist-item"><dt><span>2</span></dt><dd>JIT is not available</dd></div><div class="dlist-item"><dt><span>3</span></dt><dd>Unexpected return from test call to <code class="function pcre2-api rouge"><span class="nf">pcre2_jit_compile()</span></code></dd></div></dl></div></div> | |
| <p>If an unknown option is given, an error message is output; the exit code is 0.</p></dd></div><div class="dlist-item"><dt><span><code>--colo[u]r[=<always,auto,never>]</code></span></dt><dd>With <code>auto</code>, the output is coloured if the output is to a terminal. Force or | |
| suppress output of ANSI colour escapes with <code>always</code> (or no specifier | |
| provided) and <code>never</code> respectively. If no colour option is provided, the | |
| default is <code>auto</code>, unless the NO_COLOR environment variable is defined and | |
| non-empty.</dd></div><div class="dlist-item"><dt><span><code>-d</code></span></dt><dd>Behave as if each pattern has the <code>debug</code> modifier; the internal | |
| form and information about the compiled pattern is output after compilation; | |
| <code>-d</code> is equivalent to <code>-b -i</code>.</dd></div><div class="dlist-item"><dt><span><code>-dfa</code></span></dt><dd>Behave as if each subject line has the <code>dfa</code> modifier; matching is done | |
| using the <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code> function instead of the default | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code>.</dd></div><div class="dlist-item"><dt><span><code>-E</code></span></dt><dd>Run in "preprocess only" mode (similar to <code>gcc -E</code>). The <code>#if ... #endif</code> | |
| commands are processed, and all other lines are printed verbatim.</dd></div><div class="dlist-item"><dt><span><code>-error <em>number</em>[,<em>number</em>,...]</code></span></dt><dd>Call <code class="function pcre2-api rouge"><span class="nf">pcre2_get_error_message()</span></code> for each of the error numbers in the | |
| comma-separated list, display the resulting messages on the standard output, | |
| then exit with zero exit code. The numbers may be positive or negative. This is | |
| a convenience facility for PCRE2 maintainers.</dd></div><div class="dlist-item"><dt><span><code>-help</code></span></dt><dd>Output a brief summary these options and then exit.</dd></div><div class="dlist-item"><dt><span><code>-i</code></span></dt><dd>Behave as if each pattern has the <code>info</code> modifier; information about the | |
| compiled pattern is given after compilation.</dd></div><div class="dlist-item"><dt><span><code>-jit</code></span></dt><dd>Behave as if each pattern line has the <code>jit</code> modifier; after successful | |
| compilation, each pattern is passed to the just-in-time compiler, if available.</dd></div><div class="dlist-item"><dt><span><code>-jitfast</code></span></dt><dd>Behave as if each pattern line has the <code>jitfast</code> modifier; after | |
| successful compilation, each pattern is passed to the just-in-time compiler, if | |
| available, and each subject line is passed directly to the JIT matcher via its | |
| "fast path".</dd></div><div class="dlist-item"><dt><span><code>-jitverify</code></span></dt><dd>Behave as if each pattern line has the <code>jitverify</code> modifier; after | |
| successful compilation, each pattern is passed to the just-in-time compiler, if | |
| available, and the use of JIT for matching is verified.</dd></div><div class="dlist-item"><dt><span><code>-LM</code></span></dt><dd>List modifiers: write a list of available pattern and subject modifiers to the | |
| standard output, then exit with zero exit code. All other options are ignored. | |
| If both -C and any -Lx options are present, whichever is first is recognized.</dd></div><div class="dlist-item"><dt><span><code>-LP</code></span></dt><dd>List properties: write a list of recognized Unicode properties to the standard | |
| output, then exit with zero exit code. All other options are ignored. If both | |
| -C and any -Lx options are present, whichever is first is recognized.</dd></div><div class="dlist-item"><dt><span><code>-LS</code></span></dt><dd>List scripts: write a list of recognized Unicode script names to the standard | |
| output, then exit with zero exit code. All other options are ignored. If both | |
| -C and any -Lx options are present, whichever is first is recognized.</dd></div><div class="dlist-item"><dt><span><code>-malloc</code></span></dt><dd>Exercise <code class="c rouge" data-lang="c"><span class="nf">malloc</span><span class="p">()</span></code> failures, by first counting the number of calls made to malloc | |
| during pattern compilation and matching, then re-running the compilation and | |
| matching that many times, exercising a failure of each malloc() call.</dd></div><div class="dlist-item"><dt><span><code>-pattern <em>modifier-list</em></code></span></dt><dd>Behave as if each pattern line contains the given modifiers.</dd></div><div class="dlist-item"><dt><span><code>-q</code></span></dt><dd>Do not output the version number of <code>pcre2test</code> at the start of execution.</dd></div><div class="dlist-item"><dt><span><code>-S <em>size</em></code></span></dt><dd>On Unix-like systems, set the size of the run-time stack to <em>size</em> | |
| mebibytes (units of 1024*1024 bytes).</dd></div><div class="dlist-item"><dt><span><code>-subject <em>modifier-list</em></code></span></dt><dd>Behave as if each subject line contains the given modifiers.</dd></div><div class="dlist-item"><dt><span><code>-t</code></span></dt><dd>Run each compile and match many times with a timer, and output the resulting | |
| times per compile or match. When JIT is used, separate times are given for the | |
| initial compile and the JIT compile. You can control the number of iterations | |
| that are used for timing by following <code>-t</code> with a number (as a separate | |
| item on the command line). For example, "-t 1000" iterates 1000 times. The | |
| default is to iterate 500,000 times.</dd></div><div class="dlist-item"><dt><span><code>-tm</code></span></dt><dd>This is like <code>-t</code> except that it times only the matching phase, not the | |
| compile phase.</dd></div><div class="dlist-item"><dt><span><code>-T</code>, <code>-TM</code></span></dt><dd>These behave like <code>-t</code> and <code>-tm</code>, but in addition, at the end of a run, | |
| the total times for all compiles and matches are output.</dd></div><div class="dlist-item"><dt><span><code>-unittest</code></span></dt><dd>Run a fixed set of additional tests of the PCRE2 API which are not driven by | |
| the test input files, and then exit.</dd></div><div class="dlist-item"><dt><span><code>-version</code></span></dt><dd>Output the PCRE2 version number and then exit.</dd></div></dl></section> | |
| <section class="doc-section level-1"><h2 id="_description">Description</h2><p>If <code>pcre2test</code> is given two filename arguments, it reads from the first and | |
| writes to the second. If the first name is "-", input is taken from the | |
| standard input. If <code>pcre2test</code> is given only one argument, it reads from | |
| that file and writes to stdout. Otherwise, it reads from stdin and writes to | |
| stdout.</p> | |
| <p>When <code>pcre2test</code> is built, a configuration option can specify that it | |
| should be linked with the <code>libreadline</code> or <code>libedit</code> library. When this | |
| is done, if the input is from a terminal, it is read using the <code class="c rouge" data-lang="c"><span class="nf">readline</span><span class="p">()</span></code> | |
| function. This provides line-editing and history facilities. The output from | |
| the <code>-help</code> option states whether or not <code class="c rouge" data-lang="c"><span class="nf">readline</span><span class="p">()</span></code> will be used.</p> | |
| <p>The program handles any number of tests, each of which consists of a set of | |
| input lines. Each set starts with a regular expression pattern, followed by any | |
| number of subject lines to be matched against that pattern. In between sets of | |
| test data, command lines that begin with # may appear. This file format, with | |
| some restrictions, can also be processed by the <code>PerlTest.sh</code> script that | |
| is distributed with PCRE2 as a means of checking that the behaviour of PCRE2 | |
| and Perl is the same. For a specification of <code>PerlTest.sh</code>, see the | |
| comments near its beginning. See also the #perltest command below.</p> | |
| <p>When the input is a terminal, <code>pcre2test</code> prompts for each line of input, | |
| using "re>" to prompt for regular expression patterns, and "data>" to prompt | |
| for subject lines. Command lines starting with # can be entered only in | |
| response to the "re>" prompt.</p> | |
| <p>Each subject line is matched separately and independently. If you want to do | |
| multi-line matches, you have to use the \n escape sequence (or \r or \r\n, | |
| etc., depending on the newline setting) in a single line of input to encode the | |
| newline sequences. There is no limit on the length of subject lines; the input | |
| buffer is automatically extended if it is too small. There are replication | |
| features that makes it possible to generate long repetitive pattern or subject | |
| lines without having to supply them explicitly.</p> | |
| <p>An empty line or the end of the file signals the end of the subject lines for a | |
| test, at which point a new pattern or command line is expected if there is | |
| still input to be read.</p></section> | |
| <section class="doc-section level-1"><h2 id="_command_lines">Command lines</h2><p>In between sets of test data, a line that begins with # is interpreted as a | |
| command line. If the first character is followed by white space or an | |
| exclamation mark, the line is treated as a comment, and ignored. Otherwise, the | |
| following commands are recognized:</p> | |
| <div class="literal-block"><pre>#forbid_utf</pre></div> | |
| <p>Subsequent patterns automatically have the <code class="constant pcre2-api rouge"><span class="no">PCRE2_NEVER_UTF</span></code> and <code class="constant pcre2-api rouge"><span class="no">PCRE2_NEVER_UCP</span></code> | |
| options set, which locks out the use of the <code class="constant pcre2-api rouge"><span class="no">PCRE2_UTF</span></code> and <code class="constant pcre2-api rouge"><span class="no">PCRE2_UCP</span></code> options and | |
| the use of (<code class="regex rouge"><span class="pcre2-semantic">*UTF</span></code>) and (<code class="regex rouge"><span class="pcre2-semantic">*UCP</span></code>) at the start of patterns. This command also forces | |
| an error if a subsequent pattern contains any occurrences of <code class="regex rouge"><span class="pcre2-semantic">\P</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\p</span></code>, or <code class="regex rouge"><span class="pcre2-semantic">\X</span></code>, | |
| which are still supported when <code class="constant pcre2-api rouge"><span class="no">PCRE2_UTF</span></code> is not set, but which require Unicode | |
| property support to be included in the library.</p> | |
| <p>This is a trigger guard that is used in test files to ensure that UTF or | |
| Unicode property tests are not accidentally added to files that are used when | |
| Unicode support is not included in the library. Setting <code class="constant pcre2-api rouge"><span class="no">PCRE2_NEVER_UTF</span></code> and | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_NEVER_UCP</span></code> as a default can also be obtained by the use of <code>#pattern</code>; | |
| the difference is that <code>#forbid_utf</code> cannot be unset, and the automatic | |
| options are not displayed in pattern information, to avoid cluttering up test | |
| output.</p> | |
| <div class="literal-block"><pre>#load <filename></pre></div> | |
| <p>This command is used to load a set of precompiled patterns from a file, as | |
| described in the section <a href="#saving-restoring-patterns">Saving and restoring compiled patterns</a> | |
| below.</p> | |
| <div class="literal-block"><pre>#loadtables <filename></pre></div> | |
| <p>This command is used to load a set of binary character tables that can be | |
| accessed by the <code>tables=3</code> qualifier. Such tables can be created by the | |
| <code>pcre2_dftables</code> program with the -b option.</p> | |
| <div class="literal-block"><pre>#newline_default [<newline-list>]</pre></div> | |
| <p>When PCRE2 is built, a default newline convention can be specified. This | |
| determines which characters and/or character pairs are recognized as indicating | |
| a newline in a pattern or subject string. The default can be overridden when a | |
| pattern is compiled. The standard test files contain tests of various newline | |
| conventions, but the majority of the tests expect a single linefeed to be | |
| recognized as a newline by default. Without special action the tests would fail | |
| when PCRE2 is compiled with either CR or CRLF as the default newline.</p> | |
| <p>The #newline_default command specifies a list of newline types that are | |
| acceptable as the default. The types must be one of CR, LF, CRLF, ANYCRLF, | |
| ANY, or NUL (in upper or lower case), for example:</p> | |
| <div class="literal-block"><pre>#newline_default LF Any anyCRLF</pre></div> | |
| <p>If the default newline is in the list, this command has no effect. Otherwise, | |
| except when testing the POSIX API, a <code>newline</code> modifier that specifies the | |
| first newline convention in the list (LF in the above example) is added to any | |
| pattern that does not already have a <code>newline</code> modifier. If the newline | |
| list is empty, the feature is turned off. This command is present in a number | |
| of the standard test input files.</p> | |
| <p>When the POSIX API is being tested there is no way to override the default | |
| newline convention, though it is possible to set the newline convention from | |
| within the pattern. A warning is given if the <code>posix</code> or <code>posix_nosub</code> | |
| modifier is used when <code>#newline_default</code> would set a default for the | |
| non-POSIX API.</p> | |
| <div class="literal-block"><pre>#pattern <modifier-list></pre></div> | |
| <p>This command sets a default modifier list that applies to all subsequent | |
| patterns. Modifiers on a pattern can change these settings.</p> | |
| <div class="literal-block"><pre>#perltest</pre></div> | |
| <p>This line is used in test files that can also be processed by <code>PerlTest.sh</code> | |
| to confirm that Perl gives the same results as PCRE2. Subsequent tests are | |
| checked for the use of <code>pcre2test</code> features that are incompatible with the | |
| <code>PerlTest.sh</code> script.</p> | |
| <p>Patterns must use '/' as their delimiter, and only certain modifiers are | |
| supported. Comment lines, #pattern commands, and #subject commands that set or | |
| unset "mark" are recognized and acted on. The #perltest, #forbid_utf, and | |
| #newline_default commands, which are needed in the relevant pcre2test files, | |
| are silently ignored. All other command lines are ignored, but give a warning | |
| message. The <code>#perltest</code> command helps detect tests that are accidentally | |
| put in the wrong file or use the wrong delimiter. For more details of the | |
| <code>PerlTest.sh</code> script see the comments it contains.</p> | |
| <div class="literal-block"><pre>#pop [<modifiers>] | |
| #popcopy [<modifiers>]</pre></div> | |
| <p>These commands are used to manipulate the stack of compiled patterns, as | |
| described in the section <a href="#saving-restoring-patterns">Saving and restoring compiled patterns</a> | |
| below.</p> | |
| <div class="literal-block"><pre>#save <filename></pre></div> | |
| <p>This command is used to save a set of compiled patterns to a file, as described | |
| in the section <a href="#saving-restoring-patterns">Saving and restoring compiled patterns</a> | |
| below.</p> | |
| <div class="literal-block"><pre>#subject <modifier-list></pre></div> | |
| <p>This command sets a default modifier list that applies to all subsequent | |
| subject lines. Modifiers on a subject line can change these settings.</p> | |
| <div class="literal-block"><pre>#if CONDITION | |
| ... | |
| #endif</pre></div> | |
| <p>If CONDITION is true, then the command is printed, and its contents are | |
| processed as normal, including printing the commandlines to the output. If | |
| CONDITION is false, then all lines between the "#if" and "#endif" are skipped | |
| and not printed. The CONDITION can be any of the conditions which are tested by | |
| the "-C" commandline option and which set pcre2test’s exit code to a boolean | |
| value. The CONDITION may also be preceded by "!".</p></section> | |
| <section class="doc-section level-1"><h2 id="_modifier_syntax">Modifier syntax</h2><p>Modifier lists are used with both pattern and subject lines. Items in a list | |
| are separated by commas followed by optional white space. Trailing white space | |
| in a modifier list is ignored. Some modifiers may be given for both patterns | |
| and subject lines, whereas others are valid only for one or the other. Each | |
| modifier has a long name, for example "anchored", and some of them must be | |
| followed by an equals sign and a value, for example, "offset=12". Values cannot | |
| contain comma characters, but may contain spaces. Modifiers that do not take | |
| values may be preceded by a minus sign to turn off a previous setting.</p> | |
| <p>A few of the more common modifiers can also be specified as single letters, for | |
| example "i" for "caseless". In documentation, following the Perl convention, | |
| these are written with a slash ("the /i modifier") for clarity. Abbreviated | |
| modifiers must all be concatenated in the first item of a modifier list. If the | |
| first item is not recognized as a long modifier name, it is interpreted as a | |
| sequence of these abbreviations. For example:</p> | |
| <div class="literal-block"><pre>/abc/ig,newline=cr,jit=3</pre></div> | |
| <p>This is a pattern line whose modifier list starts with two one-letter modifiers | |
| (/i and /g). The lower-case abbreviated modifiers are the same as used in Perl.</p></section> | |
| <section class="doc-section level-1"><h2 id="_pattern_syntax">Pattern syntax</h2><p>A pattern line must start with one of the following characters (common symbols, | |
| excluding pattern meta-characters):</p> | |
| <div class="literal-block"><pre>/ ! " ' ` - = _ : ; , % & @ ~</pre></div> | |
| <p>This is interpreted as the pattern’s delimiter. A regular expression may be | |
| continued over several input lines, in which case the newline characters are | |
| included within it. It is possible to include the delimiter as a literal within | |
| the pattern by escaping it with a backslash, for example</p> | |
| <div class="literal-block"><pre>/abc\/def/</pre></div> | |
| <p>If you do this, the escape and the delimiter form part of the pattern, but | |
| since the delimiters are all non-alphanumeric, the inclusion of the backslash | |
| does not affect the pattern’s interpretation. Note, however, that this trick | |
| does not work within <code class="regex rouge"><span class="pcre2-semantic">\Q...\E</span></code> literal bracketing because the backslash will | |
| itself be interpreted as a literal. If the terminating delimiter is immediately | |
| followed by a backslash, for example,</p> | |
| <div class="literal-block"><pre>/abc/\</pre></div> | |
| <p>a backslash is added to the end of the pattern. This is done to provide a way | |
| of testing the error condition that arises if a pattern finishes with a | |
| backslash, because</p> | |
| <div class="literal-block"><pre>/abc\/</pre></div> | |
| <p>is interpreted as the first line of a pattern that starts with "abc/", causing | |
| pcre2test to read the next line as a continuation of the regular expression.</p> | |
| <p>A pattern can be followed by a modifier list (details below).</p></section> | |
| <section class="doc-section level-1"><h2 id="_subject_line_syntax">Subject line syntax</h2><p>Before each subject line is passed to <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code>, | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code>, or <code class="function pcre2-api rouge"><span class="nf">pcre2_jit_match()</span></code>, leading and trailing white | |
| space is removed, and the line is scanned for backslash escapes, unless the | |
| <code>subject_literal</code> modifier was set for the pattern. The following provide a | |
| means of encoding non-printing characters in a visible way:</p> | |
| <dl class="compact" style="--tab-width: 10"><div class="dlist-item"><dt><span><code>\a</code> </span></dt><dd>alarm (BEL, <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-9"><code class="character pcre2-api rouge"><span class="sc">0x07</span></code><span class="character-card" id="pcre2-character-9" role="tooltip" aria-label="ALERT (U+0007)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="ALERT"></span><span class="character-codepoint" data-codepoint="U+0007"></span></span></span>)</dd></div><div class="dlist-item"><dt><span><code>\b</code> </span></dt><dd>backspace (<span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-10"><code class="character pcre2-api rouge"><span class="sc">0x08</span></code><span class="character-card" id="pcre2-character-10" role="tooltip" aria-label="BACKSPACE (U+0008)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="BACKSPACE"></span><span class="character-codepoint" data-codepoint="U+0008"></span></span></span>)</dd></div><div class="dlist-item"><dt><span><code>\e</code> </span></dt><dd>escape (<span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-11"><code class="character pcre2-api rouge"><span class="sc">0x27</span></code><span class="character-card" id="pcre2-character-11" role="tooltip" aria-label="APOSTROPHE (U+0027)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character="'"></span><span class="character-name" data-character-name="APOSTROPHE"></span><span class="character-codepoint" data-codepoint="U+0027"></span></span></span>)</dd></div><div class="dlist-item"><dt><span><code>\f</code> </span></dt><dd>form feed (<span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-12"><code class="character pcre2-api rouge"><span class="sc">0x0c</span></code><span class="character-card" id="pcre2-character-12" role="tooltip" aria-label="FORM FEED (U+000C)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="FORM FEED"></span><span class="character-codepoint" data-codepoint="U+000C"></span></span></span>)</dd></div><div class="dlist-item"><dt><span><code>\n</code> </span></dt><dd>newline (<span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-13"><code class="character pcre2-api rouge"><span class="sc">0x0a</span></code><span class="character-card" id="pcre2-character-13" role="tooltip" aria-label="LINE FEED (U+000A)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="LINE FEED"></span><span class="character-codepoint" data-codepoint="U+000A"></span></span></span>)</dd></div><div class="dlist-item"><dt><span><code>\N{U+<em>hh...</em>}</code> </span></dt><dd>unicode character (any number of hex digits)</dd></div><div class="dlist-item"><dt><span><code>\r</code> </span></dt><dd>carriage return (<span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-14"><code class="character pcre2-api rouge"><span class="sc">0x0d</span></code><span class="character-card" id="pcre2-character-14" role="tooltip" aria-label="CARRIAGE RETURN (U+000D)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="CARRIAGE RETURN"></span><span class="character-codepoint" data-codepoint="U+000D"></span></span></span>)</dd></div><div class="dlist-item"><dt><span><code>\t</code> </span></dt><dd>tab (<span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-15"><code class="character pcre2-api rouge"><span class="sc">0x09</span></code><span class="character-card" id="pcre2-character-15" role="tooltip" aria-label="CHARACTER TABULATION (U+0009)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="CHARACTER TABULATION"></span><span class="character-codepoint" data-codepoint="U+0009"></span></span></span>)</dd></div><div class="dlist-item"><dt><span><code>\v</code> </span></dt><dd>vertical tab (<span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-16"><code class="character pcre2-api rouge"><span class="sc">0x0b</span></code><span class="character-card" id="pcre2-character-16" role="tooltip" aria-label="LINE TABULATION (U+000B)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="LINE TABULATION"></span><span class="character-codepoint" data-codepoint="U+000B"></span></span></span>)</dd></div><div class="dlist-item"><dt><span><code>\<em>ddd</em></code> </span></dt><dd>octal number (up to 3 octal digits); represent a single | |
| code point unless larger than 255 with the 8-bit library</dd></div><div class="dlist-item"><dt><span><code>\o{<em>dd...</em>}</code> </span></dt><dd>octal number (any number of octal digits) representing a | |
| character in UTF mode or a code point</dd></div><div class="dlist-item"><dt><span><code>\x<em>hh</em></code> </span></dt><dd>hexadecimal byte (up to 2 hex digits)</dd></div><div class="dlist-item"><dt><span><code>\x{<em>hh...</em>}</code> </span></dt><dd>hexadecimal number (up to 8 hex digits) representing a | |
| character in UTF mode or a code point</dd></div></dl> | |
| <p>Invoking <code>\N{U+<em>hh...</em>}</code> or <code>\x{<em>hh...</em>}</code> doesn’t require the use of the <code>utf</code> | |
| modifier on the pattern. It is always recognized. There may be any number of | |
| hexadecimal digits inside the braces; invalid values provoke error messages | |
| but when using <code>\N{U+<em>hh...</em>}</code> with some invalid unicode characters they will | |
| be accepted with a warning instead.</p> | |
| <p>Note that even in UTF-8 mode, <code>\x<em>hh</em></code> (and depending of how large, <code>\<em>ddd</em></code>) | |
| describe one byte rather than one character; this makes it possible to | |
| construct invalid UTF-8 sequences for testing purposes. On the other hand, | |
| <code>\x{<em>hh...</em>}</code> is interpreted as a UTF-8 character in UTF-8 mode, only generating | |
| more than one byte if the value is greater than 127. To avoid the ambiguity | |
| it is preferred to use <code>\N{U+<em>hh</em>...}</code> when describing characters. When testing | |
| the 8-bit library not in UTF-8 mode, <code>\x{<em>hh</em>}</code> generates one byte for values | |
| that could fit on it, and causes an error for greater values.</p> | |
| <p>When testing the 16-bit library, not in UTF-16 mode, all 4-digit <code>\x{<em>hhhh</em>}</code> | |
| values are accepted. This makes it possible to construct invalid UTF-16 | |
| sequences for testing purposes.</p> | |
| <p>When testing the 32-bit library, not in UTF-32 mode, all 4 to 8-digit <code>\x{...}</code> | |
| values are accepted. This makes it possible to construct invalid UTF-32 | |
| sequences for testing purposes.</p> | |
| <p>There is a special backslash sequence that specifies replication of one or more | |
| characters:</p> | |
| <div class="literal-block"><pre>\[<characters>]{<count>}</pre></div> | |
| <p>This makes it possible to test long strings without having to provide them as | |
| part of the file. For example:</p> | |
| <div class="literal-block"><pre>\[abc]{4}</pre></div> | |
| <p>is converted to "abcabcabcabc". This feature does not support nesting. To | |
| include a closing square bracket in the characters, code it as \x5D.</p> | |
| <p>A backslash followed by an equals sign marks the end of the subject string and | |
| the start of a modifier list. For example:</p> | |
| <div class="literal-block"><pre>abc\=notbol,notempty</pre></div> | |
| <p>If the subject string is empty and \= is followed by white space, the line is | |
| treated as a comment line, and is not used for matching. For example:</p> | |
| <div class="literal-block"><pre>\= This is a comment. | |
| abc\= This is an invalid modifier list.</pre></div> | |
| <p>A backslash followed by any other non-alphanumeric character just escapes that | |
| character. A backslash followed by anything else causes an error. However, if | |
| the very last character in the line is a backslash (and there is no modifier | |
| list), it is ignored. This gives a way of passing an empty line as data, since | |
| a real empty line terminates the data input.</p> | |
| <p>If the <code>subject_literal</code> modifier is set for a pattern, all subject lines | |
| that follow are treated as literals, with no special treatment of backslashes. | |
| No replication is possible, and any subject modifiers must be set as defaults | |
| by a <code>#subject</code> command.</p></section> | |
| <section class="doc-section level-1"><h2 id="_pattern_modifiers">Pattern modifiers</h2><p>There are several types of modifier that can appear in pattern lines. Except | |
| where noted below, they may also be used in <code>#pattern</code> commands. A | |
| pattern’s modifier list can add to or override default modifiers that were set | |
| by a previous <code>#pattern</code> command.</p> | |
| <section class="doc-section level-2"><h3 id="_setting_compilation_options">Setting compilation options</h3><p>The following modifiers set options for <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code>. Most of them set | |
| bits in the options argument of that function, but those whose names start with | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA</span></code> are additional options that are set in the compile context. | |
| Some of these options have single-letter abbreviations. There is special | |
| handling for <code class="regex rouge"><span class="pcre2-semantic">/x</span></code>: if a second x is present, <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED</span></code> is converted into | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED_MORE</span></code> as in Perl. A third appearance adds <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED</span></code> as well, | |
| though this makes no difference to the way <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code> behaves. See | |
| <a href="./pcre2api.html"><code>pcre2api</code></a> | |
| for a description of the effects of these options.</p> | |
| <dl class="options compact" style="--tab-width: 14"><div class="dlist-item"><dt><span><code>allow_empty_class</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_ALLOW_EMPTY_CLASS</span></code></dd></div><div class="dlist-item"><dt><span><code>allow_lookaround_bsk</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ALLOW_LOOKAROUND_BSK</span></code></dd></div><div class="dlist-item"><dt><span><code>allow_surrogate_escapes</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ALLOW_SURROGATE_ESCAPES</span></code></dd></div><div class="dlist-item"><dt><span><code>alt_bsux</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_ALT_BSUX</span></code></dd></div><div class="dlist-item"><dt><span><code>alt_circumflex</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_ALT_CIRCUMFLEX</span></code></dd></div><div class="dlist-item"><dt><span><code>alt_extended_class</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_ALT_EXTENDED_CLASS</span></code></dd></div><div class="dlist-item"><dt><span><code>alt_verbnames</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_ALT_VERBNAMES</span></code></dd></div><div class="dlist-item"><dt><span><code>anchored</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_ANCHORED</span></code></dd></div><div class="dlist-item"><dt><span><code>/a ascii_all</code></span></dt><dd>set all ASCII options</dd></div><div class="dlist-item"><dt><span><code>ascii_bsd</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ASCII_BSD</span></code></dd></div><div class="dlist-item"><dt><span><code>ascii_bss</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ASCII_BSS</span></code></dd></div><div class="dlist-item"><dt><span><code>ascii_bsw</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ASCII_BSW</span></code></dd></div><div class="dlist-item"><dt><span><code>ascii_digit</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ASCII_DIGIT</span></code></dd></div><div class="dlist-item"><dt><span><code>ascii_posix</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ASCII_POSIX</span></code></dd></div><div class="dlist-item"><dt><span><code>auto_callout</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_AUTO_CALLOUT</span></code></dd></div><div class="dlist-item"><dt><span><code>bad_escape_is_literal</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_BAD_ESCAPE_IS_LITERAL</span></code></dd></div><div class="dlist-item"><dt><span><code>/i caseless</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_CASELESS</span></code></dd></div><div class="dlist-item"><dt><span><code>/r caseless_restrict</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_CASELESS_RESTRICT</span></code></dd></div><div class="dlist-item"><dt><span><code>dollar_endonly</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_DOLLAR_ENDONLY</span></code></dd></div><div class="dlist-item"><dt><span><code>/s dotall</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_DOTALL</span></code></dd></div><div class="dlist-item"><dt><span><code>dupnames</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_DUPNAMES</span></code></dd></div><div class="dlist-item"><dt><span><code>endanchored</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_ENDANCHORED</span></code></dd></div><div class="dlist-item"><dt><span><code>escaped_cr_is_lf</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ESCAPED_CR_IS_LF</span></code></dd></div><div class="dlist-item"><dt><span><code>/x extended</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED</span></code></dd></div><div class="dlist-item"><dt><span><code>/xx extended_more</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED_MORE</span></code></dd></div><div class="dlist-item"><dt><span><code>extra_alt_bsux</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ALT_BSUX</span></code></dd></div><div class="dlist-item"><dt><span><code>firstline</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_FIRSTLINE</span></code></dd></div><div class="dlist-item"><dt><span><code>literal</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_LITERAL</span></code></dd></div><div class="dlist-item"><dt><span><code>match_line</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_MATCH_LINE</span></code></dd></div><div class="dlist-item"><dt><span><code>match_invalid_utf</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_MATCH_INVALID_UTF</span></code></dd></div><div class="dlist-item"><dt><span><code>match_unset_backref</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_MATCH_UNSET_BACKREF</span></code></dd></div><div class="dlist-item"><dt><span><code>match_word</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_MATCH_WORD</span></code></dd></div><div class="dlist-item"><dt><span><code>/m multiline</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_MULTILINE</span></code></dd></div><div class="dlist-item"><dt><span><code>never_backslash_c</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_NEVER_BACKSLASH_C</span></code></dd></div><div class="dlist-item"><dt><span><code>never_callout</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_NEVER_CALLOUT</span></code></dd></div><div class="dlist-item"><dt><span><code>never_ucp</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_NEVER_UCP</span></code></dd></div><div class="dlist-item"><dt><span><code>never_utf</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_NEVER_UTF</span></code></dd></div><div class="dlist-item"><dt><span><code>/n no_auto_capture</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_AUTO_CAPTURE</span></code></dd></div><div class="dlist-item"><dt><span><code>no_auto_possess</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_AUTO_POSSESS</span></code></dd></div><div class="dlist-item"><dt><span><code>no_bs0</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_NO_BS0</span></code></dd></div><div class="dlist-item"><dt><span><code>no_dotstar_anchor</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_DOTSTAR_ANCHOR</span></code></dd></div><div class="dlist-item"><dt><span><code>no_start_optimize</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_START_OPTIMIZE</span></code></dd></div><div class="dlist-item"><dt><span><code>no_utf_check</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_UTF_CHECK</span></code></dd></div><div class="dlist-item"><dt><span><code>python_octal</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_PYTHON_OCTAL</span></code></dd></div><div class="dlist-item"><dt><span><code>turkish_casing</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_TURKISH_CASING</span></code></dd></div><div class="dlist-item"><dt><span><code>ucp</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_UCP</span></code></dd></div><div class="dlist-item"><dt><span><code>ungreedy</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_UNGREEDY</span></code></dd></div><div class="dlist-item"><dt><span><code>use_offset_limit</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_USE_OFFSET_LIMIT</span></code></dd></div><div class="dlist-item"><dt><span><code>utf</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_UTF</span></code></dd></div></dl> | |
| <p>As well as turning on the <code class="constant pcre2-api rouge"><span class="no">PCRE2_UTF</span></code> option, the <code>utf</code> modifier causes all | |
| non-printing characters in output strings to be printed using the <code class="regex rouge"><span class="pcre2-semantic">\x{<em>hh</em>...}</span></code> | |
| notation. Otherwise, those less than <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-17"><code class="character pcre2-api rouge"><span class="sc">0x100</span></code><span class="character-card" id="pcre2-character-17" role="tooltip" aria-label="LATIN CAPITAL LETTER A WITH MACRON (U+0100)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character="Ā"></span><span class="character-name" data-character-name="LATIN CAPITAL LETTER A WITH MACRON"></span><span class="character-codepoint" data-codepoint="U+0100"></span></span></span> are output in hex without the curly | |
| brackets. Setting <code>utf</code> in 16-bit or 32-bit mode also causes pattern and | |
| subject strings to be translated to UTF-16 or UTF-32, respectively, before | |
| being passed to library functions.</p> | |
| <p>The following modifiers enable or disable performance optimizations by | |
| calling <code class="function pcre2-api rouge"><span class="nf">pcre2_set_optimize()</span></code> before invoking the regex compiler.</p> | |
| <dl class="options compact" style="--tab-width: 10"><div class="dlist-item"><dt><span><code>optimization_full</code></span></dt><dd>enable all optional optimizations</dd></div><div class="dlist-item"><dt><span><code>optimization_none</code></span></dt><dd>disable all optional optimizations</dd></div><div class="dlist-item"><dt><span><code>auto_possess</code></span></dt><dd>auto-possessify variable quantifiers</dd></div><div class="dlist-item"><dt><span><code>auto_possess_off</code></span></dt><dd>don’t auto-possessify variable quantifiers</dd></div><div class="dlist-item"><dt><span><code>dotstar_anchor</code></span></dt><dd>anchor patterns starting with <code class="regex rouge"><span class="pcre2-semantic">.*</span></code></dd></div><div class="dlist-item"><dt><span><code>dotstar_anchor_off</code></span></dt><dd>don’t anchor patterns starting with <code class="regex rouge"><span class="pcre2-semantic">.*</span></code></dd></div><div class="dlist-item"><dt><span><code>start_optimize</code></span></dt><dd>enable pre-scan of subject string</dd></div><div class="dlist-item"><dt><span><code>start_optimize_off</code></span></dt><dd>disable pre-scan of subject string</dd></div></dl> | |
| <p>See the | |
| <a href="./pcre2_set_optimize.html"><code>pcre2_set_optimize</code></a> | |
| documentation for details on these optimizations.</p></section> | |
| <section class="doc-section level-2"><h3 id="_setting_compilation_controls">Setting compilation controls</h3><p>The following modifiers affect the compilation process or request information | |
| about the pattern. There are single-letter abbreviations for some that are | |
| heavily used in the test files.</p> | |
| <dl class="options compact" style="--tab-width: 14"><div class="dlist-item"><dt><span><code>/B bincode</code></span></dt><dd>show binary code without lengths</dd></div><div class="dlist-item"><dt><span><code>bsr=[anycrlf|unicode]</code></span></dt><dd>specify \R handling</dd></div><div class="dlist-item"><dt><span><code>callout_info</code></span></dt><dd>show callout information</dd></div><div class="dlist-item"><dt><span><code>convert=<options></code></span></dt><dd>request foreign pattern conversion</dd></div><div class="dlist-item"><dt><span><code>convert_glob_escape=c</code></span></dt><dd>set glob escape character</dd></div><div class="dlist-item"><dt><span><code>convert_glob_separator=c</code></span></dt><dd>set glob separator character</dd></div><div class="dlist-item"><dt><span><code>convert_length</code></span></dt><dd>set convert buffer length</dd></div><div class="dlist-item"><dt><span><code>debug</code></span></dt><dd>same as <code>info,fullbincode</code></dd></div><div class="dlist-item"><dt><span><code>expand</code></span></dt><dd>expand repetition syntax in pattern</dd></div><div class="dlist-item"><dt><span><code>framesize</code></span></dt><dd>show matching frame size</dd></div><div class="dlist-item"><dt><span><code>fullbincode</code></span></dt><dd>show binary code with lengths</dd></div><div class="dlist-item"><dt><span><code>/I info</code></span></dt><dd>show info about compiled pattern</dd></div><div class="dlist-item"><dt><span><code>hex</code></span></dt><dd>unquoted characters are hexadecimal</dd></div><div class="dlist-item"><dt><span><code>jit[=<number>]</code></span></dt><dd>use JIT</dd></div><div class="dlist-item"><dt><span><code>jitfast</code></span></dt><dd>use JIT fast path</dd></div><div class="dlist-item"><dt><span><code>jitverify</code></span></dt><dd>verify JIT use</dd></div><div class="dlist-item"><dt><span><code>locale=<name></code></span></dt><dd>use this locale</dd></div><div class="dlist-item"><dt><span><code>max_pattern_compiled_length=<n></code></span></dt><dd>set maximum compiled pattern length (bytes)</dd></div><div class="dlist-item"><dt><span><code>max_pattern_length=<n></code></span></dt><dd>set maximum pattern length (code units)</dd></div><div class="dlist-item"><dt><span><code>max_varlookbehind=<n></code></span></dt><dd>set maximum variable lookbehind length</dd></div><div class="dlist-item"><dt><span><code>memory</code></span></dt><dd>show memory used</dd></div><div class="dlist-item"><dt><span><code>newline=<type></code></span></dt><dd>set newline type</dd></div><div class="dlist-item"><dt><span><code>null_context</code></span></dt><dd>compile with a NULL context</dd></div><div class="dlist-item"><dt><span><code>null_pattern</code></span></dt><dd>pass pattern as NULL</dd></div><div class="dlist-item"><dt><span><code>parens_nest_limit=<n></code></span></dt><dd>set maximum parentheses depth</dd></div><div class="dlist-item"><dt><span><code>posix</code></span></dt><dd>use the POSIX API</dd></div><div class="dlist-item"><dt><span><code>posix_nosub</code></span></dt><dd>use the POSIX API with <code class="c rouge" data-lang="c"><span class="no">REG_NOSUB</span></code></dd></div><div class="dlist-item"><dt><span><code>push</code></span></dt><dd>push compiled pattern onto the stack</dd></div><div class="dlist-item"><dt><span><code>pushcopy</code></span></dt><dd>push a copy onto the stack</dd></div><div class="dlist-item"><dt><span><code>pushtablescopy</code></span></dt><dd>push a copy with tables onto the stack</dd></div><div class="dlist-item"><dt><span><code>stackguard=<number></code></span></dt><dd>test the stackguard feature</dd></div><div class="dlist-item"><dt><span><code>subject_literal</code></span></dt><dd>treat all subject lines as literal</dd></div><div class="dlist-item"><dt><span><code>tables=[0|1|2|3]</code></span></dt><dd>select internal tables</dd></div><div class="dlist-item"><dt><span><code>use_length</code></span></dt><dd>do not zero-terminate the pattern</dd></div><div class="dlist-item"><dt><span><code>utf8_input</code></span></dt><dd>treat input as UTF-8</dd></div></dl> | |
| <p>The effects of these modifiers are described in the following sections.</p></section> | |
| <section class="doc-section level-2"><h3 id="_newline_and_r_handling">Newline and \R handling</h3><p>The <code>bsr</code> modifier specifies what <code class="regex rouge"><span class="pcre2-semantic">\R</span></code> in a pattern should match. If it is | |
| set to "anycrlf", <code class="regex rouge"><span class="pcre2-semantic">\R</span></code> matches CR, LF, or CRLF only. If it is set to "unicode", | |
| <code class="regex rouge"><span class="pcre2-semantic">\R</span></code> matches any Unicode newline sequence. The default can be specified when | |
| PCRE2 is built; if it is not, the default is set to Unicode.</p> | |
| <p>The <code>newline</code> modifier specifies which characters are to be interpreted as | |
| newlines, both in the pattern and in subject lines. The type must be one of CR, | |
| LF, CRLF, ANYCRLF, ANY, or NUL (in upper or lower case).</p></section> | |
| <section class="doc-section level-2"><h3 id="_information_about_a_pattern">Information about a pattern</h3><p>The <code>debug</code> modifier is a shorthand for <code>info,fullbincode</code>, requesting | |
| all available information.</p> | |
| <p>The <code>bincode</code> modifier causes a representation of the compiled code to be | |
| output after compilation. This information does not contain length and offset | |
| values, which ensures that the same output is generated for different internal | |
| link sizes and different code unit widths. By using <code>bincode</code>, the same | |
| regression tests can be used in different environments.</p> | |
| <p>The <code>fullbincode</code> modifier, by contrast, <em>does</em> include length and | |
| offset values. This is used in a few special tests that run only for specific | |
| code unit widths and link sizes, and is also useful for one-off tests.</p> | |
| <p>The <code>info</code> modifier requests information about the compiled pattern | |
| (whether it is anchored, has a fixed first character, and so on). The | |
| information is obtained from the <code class="function pcre2-api rouge"><span class="nf">pcre2_pattern_info()</span></code> function. Here are | |
| some typical examples:</p> | |
| <div class="literal-block"><pre> re> /(?i)(^a|^b)/m,info | |
| Capture group count = 1 | |
| Compile options: multiline | |
| Overall options: caseless multiline | |
| First code unit at start or follows newline | |
| Subject length lower bound = 1</pre></div> | |
| <div class="literal-block"><pre> re> /(?i)abc/info | |
| Capture group count = 0 | |
| Compile options: <none> | |
| Overall options: caseless | |
| First code unit = 'a' (caseless) | |
| Last code unit = 'c' (caseless) | |
| Subject length lower bound = 3</pre></div> | |
| <p>"Compile options" are those specified by modifiers; "overall options" have | |
| added options that are taken or deduced from the pattern. If both sets of | |
| options are the same, just a single "options" line is output; if there are no | |
| options, the line is omitted. "First code unit" is where any match must start; | |
| if there is more than one they are listed as "starting code units". "Last code | |
| unit" is the last literal code unit that must be present in any match. This is | |
| not necessarily the last character. These lines are omitted if no starting or | |
| ending code units are recorded. The subject length line is omitted when | |
| <code>no_start_optimize</code> is set because the minimum length is not calculated | |
| when it can never be used.</p> | |
| <p>The <code>framesize</code> modifier shows the size, in bytes, of each storage frame | |
| used by <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> for handling backtracking. The size depends on the | |
| number of capturing parentheses in the pattern. A vector of these frames is | |
| used at matching time; its overall size is shown when the <code>heapframes_size</code> | |
| subject modifier is set.</p> | |
| <p>The <code>callout_info</code> modifier requests information about all the callouts in | |
| the pattern. A list of them is output at the end of any other information that | |
| is requested. For each callout, either its number or string is given, followed | |
| by the item that follows it in the pattern.</p></section> | |
| <section class="doc-section level-2"><h3 id="_passing_a_null_context">Passing a <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> context</h3><p>Normally, <code>pcre2test</code> passes a context block to <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code>. If | |
| the <code>null_context</code> modifier is set, however, <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> is passed. This is for | |
| testing that <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code> behaves correctly in this case (it uses | |
| default values).</p></section> | |
| <section class="doc-section level-2"><h3 id="_passing_a_null_pattern">Passing a <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> pattern</h3><p>The <code>null_pattern</code> modifier is for testing the behaviour of | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code> when the pattern argument is <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code>. The length value | |
| passed is the default <code class="constant pcre2-api rouge"><span class="no">PCRE2_ZERO_TERMINATED</span></code> unless <code>use_length</code> is set. | |
| Any length other than zero causes an error.</p></section> | |
| <section class="doc-section level-2"><h3 id="_specifying_pattern_characters_in_hexadecimal">Specifying pattern characters in hexadecimal</h3><p>The <code>hex</code> modifier specifies that the characters of the pattern, except for | |
| substrings enclosed in single or double quotes, are to be interpreted as pairs | |
| of hexadecimal digits. This feature is provided as a way of creating patterns | |
| that contain binary zeros and other non-printing characters. White space is | |
| permitted between pairs of digits. For example, this pattern contains three | |
| characters:</p> | |
| <div class="literal-block"><pre>/ab 32 59/hex</pre></div> | |
| <p>Parts of such a pattern are taken literally if quoted. This pattern contains | |
| nine characters, only two of which are specified in hexadecimal:</p> | |
| <div class="literal-block"><pre>/ab "literal" 32/hex</pre></div> | |
| <p>Either single or double quotes may be used. There is no way of including | |
| the delimiter within a substring. The <code>hex</code> and <code>expand</code> modifiers are | |
| mutually exclusive.</p></section> | |
| <section class="doc-section level-2"><h3 id="_specifying_the_patterns_length">Specifying the pattern’s length</h3><p>By default, patterns are passed to the compiling functions as zero-terminated | |
| strings but can be passed by length instead of being zero-terminated. The | |
| <code>use_length</code> modifier causes this to happen. Using a length happens | |
| automatically (whether or not <code>use_length</code> is set) when <code>hex</code> is set, | |
| because patterns specified in hexadecimal may contain binary zeros.</p> | |
| <p>If <code>hex</code> or <code>use_length</code> is used with the POSIX wrapper API (see | |
| "Using the POSIX wrapper API" | |
| below), the REG_PEND extension is used to pass the pattern’s length.</p></section> | |
| <section class="doc-section level-2"><h3 id="_specifying_a_maximum_for_variable_lookbehinds">Specifying a maximum for variable lookbehinds</h3><p>Variable lookbehind assertions are supported only if, for each one, there is a | |
| maximum length (in characters) that it can match. There is a limit on this, | |
| whose default can be set at build time, with an ultimate default of 255. The | |
| <code>max_varlookbehind</code> modifier uses the <code class="function pcre2-api rouge"><span class="nf">pcre2_set_max_varlookbehind()</span></code> | |
| function to change the limit. Lookbehinds whose branches each match a fixed | |
| length are limited to 65,535 characters per branch.</p></section> | |
| <section class="doc-section level-2"><h3 id="_specifying_wide_characters_in_16_bit_and_32_bit_modes">Specifying wide characters in 16-bit and 32-bit modes</h3><p>In 16-bit and 32-bit modes, all input is automatically treated as UTF-8 and | |
| translated to UTF-16 or UTF-32 when the <code>utf</code> modifier is set. For testing | |
| the 16-bit and 32-bit libraries in non-UTF mode, the <code>utf8_input</code> modifier | |
| can be used. It is mutually exclusive with <code>utf</code>. Input lines are | |
| interpreted as UTF-8 as a means of specifying wide characters. More details are | |
| given in | |
| "Input encoding" | |
| above.</p></section> | |
| <section class="doc-section level-2"><h3 id="_generating_long_repetitive_patterns">Generating long repetitive patterns</h3><p>Some tests use long patterns that are very repetitive. Instead of creating a | |
| very long input line for such a pattern, you can use a special repetition | |
| feature, similar to the one described for subject lines above. If the | |
| <code>expand</code> modifier is present on a pattern, parts of the pattern that have | |
| the form</p> | |
| <div class="literal-block"><pre>\[<characters>]{<count>}</pre></div> | |
| <p>are expanded before the pattern is passed to <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code>. For | |
| example, \[AB]{6000} is expanded to "ABAB…" 6000 times. This construction | |
| cannot be nested. An initial "\[" sequence is recognized only if "]{" followed | |
| by decimal digits and "}" is found later in the pattern. If not, the characters | |
| remain in the pattern unaltered. The <code>expand</code> and <code>hex</code> modifiers are | |
| mutually exclusive.</p> | |
| <p>If part of an expanded pattern looks like an expansion, but is really part of | |
| the actual pattern, unwanted expansion can be avoided by giving two values in | |
| the quantifier. For example, \[AB]{6000,6000} is not recognized as an | |
| expansion item.</p> | |
| <p>If the <code>info</code> modifier is set on an expanded pattern, the result of the | |
| expansion is included in the information that is output.</p></section> | |
| <section class="doc-section level-2"><h3 id="_jit_compilation">JIT compilation</h3><p>Just-in-time (JIT) compiling is a heavyweight optimization that can greatly | |
| speed up pattern matching. See the | |
| <a href="./pcre2jit.html"><code>pcre2jit</code></a> | |
| documentation for details. JIT compiling happens, optionally, after a pattern | |
| has been successfully compiled into an internal form. The JIT compiler converts | |
| this to optimized machine code. It needs to know whether the match-time options | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_PARTIAL_HARD</span></code> and <code class="constant pcre2-api rouge"><span class="no">PCRE2_PARTIAL_SOFT</span></code> are going to be used, because | |
| different code is generated for the different cases. See the <code>partial</code> | |
| modifier in "Subject Modifiers" | |
| below | |
| for details of how these options are specified for each match attempt.</p> | |
| <p>JIT compilation is requested by the <code>jit</code> pattern modifier, which may | |
| optionally be followed by an equals sign and a number in the range 0 to 7. | |
| The three bits that make up the number specify which of the three JIT operating | |
| modes are to be compiled:</p> | |
| <dl class="compact" style="--tab-width: 4"><div class="dlist-item"><dt><span>1</span></dt><dd>compile JIT code for non-partial matching</dd></div><div class="dlist-item"><dt><span>2</span></dt><dd>compile JIT code for soft partial matching</dd></div><div class="dlist-item"><dt><span>4</span></dt><dd>compile JIT code for hard partial matching</dd></div></dl> | |
| <p>The possible values for the <code>jit</code> modifier are therefore:</p> | |
| <dl class="compact" style="--tab-width: 4"><div class="dlist-item"><dt><span>0</span></dt><dd>disable JIT</dd></div><div class="dlist-item"><dt><span>1</span></dt><dd>normal matching only</dd></div><div class="dlist-item"><dt><span>2</span></dt><dd>soft partial matching only</dd></div><div class="dlist-item"><dt><span>3</span></dt><dd>normal and soft partial matching</dd></div><div class="dlist-item"><dt><span>4</span></dt><dd>hard partial matching only</dd></div><div class="dlist-item"><dt><span>6</span></dt><dd>soft and hard partial matching only</dd></div><div class="dlist-item"><dt><span>7</span></dt><dd>all three modes</dd></div></dl> | |
| <p>If no number is given, 7 is assumed. The phrase "partial matching" means a call | |
| to <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> with either the <code class="constant pcre2-api rouge"><span class="no">PCRE2_PARTIAL_SOFT</span></code> or the | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_PARTIAL_HARD</span></code> option set. Note that such a call may return a complete | |
| match; the options enable the possibility of a partial match, but do not | |
| require it. Note also that if you request JIT compilation only for partial | |
| matching (for example, jit=2) but do not set the <code>partial</code> modifier on a | |
| subject line, that match will not use JIT code because none was compiled for | |
| non-partial matching.</p> | |
| <p>If JIT compilation is successful, the compiled JIT code will automatically be | |
| used when an appropriate type of match is run, except when incompatible | |
| run-time options are specified. For more details, see the | |
| <a href="./pcre2jit.html"><code>pcre2jit</code></a> | |
| documentation. See also the <code>jitstack</code> modifier below for a way of | |
| setting the size of the JIT stack.</p> | |
| <p>If the <code>jitfast</code> modifier is specified, matching is done using the JIT | |
| "fast path" interface, <code class="function pcre2-api rouge"><span class="nf">pcre2_jit_match()</span></code>, which skips some of the sanity | |
| checks that are done by <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code>, and of course does not work when | |
| JIT is not supported. If <code>jitfast</code> is specified without <code>jit</code>, jit=7 is | |
| assumed.</p> | |
| <p>If the <code>jitverify</code> modifier is specified, information about the compiled | |
| pattern shows whether JIT compilation was or was not successful. If | |
| <code>jitverify</code> is specified without <code>jit</code>, jit=7 is assumed. If JIT | |
| compilation is successful when <code>jitverify</code> is set, the text "(JIT)" is | |
| added to the first output line after a match or non match when JIT-compiled | |
| code was actually used in the match.</p></section> | |
| <section class="doc-section level-2"><h3 id="_setting_a_locale">Setting a locale</h3><p>The <code>locale</code> modifier must specify the name of a locale, for example:</p> | |
| <div class="literal-block"><pre>/pattern/locale=fr_FR</pre></div> | |
| <p>The given locale is set, <code class="function pcre2-api rouge"><span class="nf">pcre2_maketables()</span></code> is called to build a set of | |
| character tables for the locale, and this is then passed to | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code> when compiling the regular expression. The same tables | |
| are used when matching the following subject lines. The <code>locale</code> modifier | |
| applies only to the pattern on which it appears, but can be given in a | |
| <code>#pattern</code> command if a default is needed. Setting a locale and alternate | |
| character tables are mutually exclusive.</p></section> | |
| <section class="doc-section level-2"><h3 id="_showing_pattern_memory">Showing pattern memory</h3><p>The <code>memory</code> modifier causes the size in bytes of the memory used to hold | |
| the compiled pattern to be output. This does not include the size of the | |
| <code class="type pcre2-api rouge"><span class="kt">pcre2_code</span></code> block; it is just the actual compiled data. If the pattern is | |
| subsequently passed to the JIT compiler, the size of the JIT compiled code is | |
| also output. Here is an example:</p> | |
| <div class="literal-block"><pre> re> /a(b)c/jit,memory | |
| Memory allocation (code space): 21 | |
| Memory allocation (JIT code): 1910</pre></div></section> | |
| <section class="doc-section level-2"><h3 id="_limiting_nested_parentheses">Limiting nested parentheses</h3><p>The <code>parens_nest_limit</code> modifier sets a limit on the depth of nested | |
| parentheses in a pattern. Breaching the limit causes a compilation error. | |
| The default for the library is set when PCRE2 is built, but <code>pcre2test</code> | |
| sets its own default of 220, which is required for running the standard test | |
| suite.</p></section> | |
| <section class="doc-section level-2"><h3 id="_limiting_the_pattern_length">Limiting the pattern length</h3><p>The <code>max_pattern_length</code> modifier sets a limit, in code units, to the | |
| length of pattern that <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code> will accept. Breaching the limit | |
| causes a compilation error. The default is the largest number a <code class="type pcre2-api rouge"><span class="kt">PCRE2_SIZE</span></code> | |
| variable can hold (essentially unlimited).</p></section> | |
| <section class="doc-section level-2"><h3 id="_limiting_the_size_of_a_compiled_pattern">Limiting the size of a compiled pattern</h3><p>The <code>max_pattern_compiled_length</code> modifier sets a limit, in bytes, to the | |
| amount of memory used by a compiled pattern. Breaching the limit causes a | |
| compilation error. The default is the largest number a <code class="type pcre2-api rouge"><span class="kt">PCRE2_SIZE</span></code> variable can | |
| hold (essentially unlimited).</p></section> | |
| <section class="doc-section level-2"><h3 id="_using_the_posix_wrapper_api">Using the POSIX wrapper API</h3><p>The <code>posix</code> and <code>posix_nosub</code> modifiers cause <code>pcre2test</code> to call | |
| PCRE2 via the POSIX wrapper API rather than its native API. When | |
| <code>posix_nosub</code> is used, the POSIX option <code class="c rouge" data-lang="c"><span class="no">REG_NOSUB</span></code> is passed to | |
| <code class="c rouge" data-lang="c"><span class="nf">regcomp</span><span class="p">()</span></code>. The POSIX wrapper supports only the 8-bit library. Note that | |
| it does not imply POSIX matching semantics; for more detail see the | |
| <a href="./pcre2posix.html"><code>pcre2posix</code></a> | |
| documentation. The following pattern modifiers set options for the | |
| <code class="c rouge" data-lang="c"><span class="nf">regcomp</span><span class="p">()</span></code> function:</p> | |
| <dl class="compact" style="--tab-width: 6"><div class="dlist-item"><dt><span><code>caseless</code> </span></dt><dd><code class="constant pcre2-api rouge"><span class="no">REG_ICASE</span></code></dd></div><div class="dlist-item"><dt><span><code>multiline</code> </span></dt><dd><code class="constant pcre2-api rouge"><span class="no">REG_NEWLINE</span></code></dd></div><div class="dlist-item"><dt><span><code>dotall</code> </span></dt><dd><code class="constant pcre2-api rouge"><span class="no">REG_DOTALL</span></code></dd></div><div class="dlist-item"><dt><span><code>ungreedy</code> </span></dt><dd><code class="constant pcre2-api rouge"><span class="no">REG_UNGREEDY</span></code></dd></div><div class="dlist-item"><dt><span><code>ucp</code> </span></dt><dd><code class="constant pcre2-api rouge"><span class="no">REG_UCP</span></code></dd></div><div class="dlist-item"><dt><span><code>utf</code> </span></dt><dd><code class="constant pcre2-api rouge"><span class="no">REG_UTF8</span></code></dd></div></dl> | |
| <p>The four options <code class="constant pcre2-api rouge"><span class="no">REG_DOTALL</span></code>, <code class="constant pcre2-api rouge"><span class="no">REG_UNGREEDY</span></code>, <code class="constant pcre2-api rouge"><span class="no">REG_UCP</span></code>, and <code class="constant pcre2-api rouge"><span class="no">REG_UTF8</span></code> are not part of the | |
| POSIX standard.</p> | |
| <p>The <code>regerror_buffsize</code> modifier specifies a size for the error buffer that | |
| is passed to <code class="c rouge" data-lang="c"><span class="nf">regerror</span><span class="p">()</span></code> in the event of a compilation error. For example:</p> | |
| <div class="literal-block"><pre>/abc/posix,regerror_buffsize=20</pre></div> | |
| <p>This provides a means of testing the behaviour of <code class="c rouge" data-lang="c"><span class="nf">regerror</span><span class="p">()</span></code> when the | |
| buffer is too small for the error message. If this modifier has not been set, a | |
| large buffer is used.</p> | |
| <p>The <code>aftertext</code> and <code>allaftertext</code> subject modifiers work as described | |
| below. All other modifiers are either ignored, with a warning message, or cause | |
| an error.</p> | |
| <p>The pattern is passed to <code class="c rouge" data-lang="c"><span class="nf">regcomp</span><span class="p">()</span></code> as a zero-terminated string by | |
| default, but if the <code>use_length</code> or <code>hex</code> modifiers are set, the | |
| <code class="c rouge" data-lang="c"><span class="no">REG_PEND</span></code> extension is used to pass it by length.</p></section> | |
| <section class="doc-section level-2"><h3 id="_testing_the_stack_guard_feature">Testing the stack guard feature</h3><p>The <code>stackguard</code> modifier is used to test the use of | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_set_compile_recursion_guard()</span></code>, a function that is provided to | |
| enable stack availability to be checked during compilation (see the | |
| <a href="./pcre2api.html"><code>pcre2api</code></a> | |
| documentation for details). If the number specified by the modifier is greater | |
| than zero, <code class="function pcre2-api rouge"><span class="nf">pcre2_set_compile_recursion_guard()</span></code> is called to set up | |
| callback from <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code> to a local function. The argument it | |
| receives is the current nesting parenthesis depth; if this is greater than the | |
| value given by the modifier, non-zero is returned, causing the compilation to | |
| be aborted.</p></section> | |
| <section class="doc-section level-2"><h3 id="_using_alternative_character_tables">Using alternative character tables</h3><p>The value specified for the <code>tables</code> modifier must be one of the digits 0, | |
| 1, 2, or 3. It causes a specific set of built-in character tables to be passed | |
| to <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code>. This is used in the PCRE2 tests to check behaviour | |
| with different character tables. The digit specifies the tables as follows:</p> | |
| <dl class="compact" style="--tab-width: 4"><div class="dlist-item"><dt><span>0</span></dt><dd>do not pass any special character tables</dd></div><div class="dlist-item"><dt><span>1</span></dt><dd>the default ASCII tables, as distributed in <code>pcre2_chartables.c.dist</code></dd></div><div class="dlist-item"><dt><span>2</span></dt><dd>a set of tables defining ISO 8859 characters</dd></div><div class="dlist-item"><dt><span>3</span></dt><dd>a set of tables loaded by the <code>#loadtables</code> command</dd></div></dl> | |
| <p>In tables 2, some characters whose codes are greater than 128 are identified as | |
| letters, digits, spaces, etc. Tables 3 can be used only after a | |
| <code>#loadtables</code> command has loaded them from a binary file. Setting alternate | |
| character tables and a locale are mutually exclusive.</p></section> | |
| <section class="doc-section level-2"><h3 id="_setting_certain_match_controls">Setting certain match controls</h3><p>The following modifiers are really subject modifiers, and are described under | |
| "Subject Modifiers" below. However, they may be included in a pattern’s | |
| modifier list, in which case they are applied to every subject line that is | |
| processed with that pattern. These modifiers do not affect the compilation | |
| process.</p> | |
| <dl class="options compact" style="--tab-width: 14"><div class="dlist-item"><dt><span><code>aftertext</code></span></dt><dd>show text after match</dd></div><div class="dlist-item"><dt><span><code>allaftertext</code></span></dt><dd>show text after captures</dd></div><div class="dlist-item"><dt><span><code>allcaptures</code></span></dt><dd>show all captures</dd></div><div class="dlist-item"><dt><span><code>allvector</code></span></dt><dd>show the entire ovector</dd></div><div class="dlist-item"><dt><span><code>allusedtext</code></span></dt><dd>show all consulted text</dd></div><div class="dlist-item"><dt><span><code>altglobal</code></span></dt><dd>alternative global matching</dd></div><div class="dlist-item"><dt><span><code>/g global</code></span></dt><dd>global matching</dd></div><div class="dlist-item"><dt><span><code>heapframes_size</code></span></dt><dd>show match data heapframes size</dd></div><div class="dlist-item"><dt><span><code>jitstack=<n></code></span></dt><dd>set size of JIT stack</dd></div><div class="dlist-item"><dt><span><code>mark</code></span></dt><dd>show mark values</dd></div><div class="dlist-item"><dt><span><code>null_substitute_match_data</code></span></dt><dd>substitute with NULL match data</dd></div><div class="dlist-item"><dt><span><code>replace=<str></code></span></dt><dd>specify a replacement string</dd></div><div class="dlist-item"><dt><span><code>startchar</code></span></dt><dd>show starting character when relevant</dd></div><div class="dlist-item"><dt><span><code>substitute_callout</code></span></dt><dd>use substitution callouts</dd></div><div class="dlist-item"><dt><span><code>substitute_case_callout</code></span></dt><dd>use substitution case callouts</dd></div><div class="dlist-item"><dt><span><code>substitute_extended</code></span></dt><dd>use <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_EXTENDED</span></code></dd></div><div class="dlist-item"><dt><span><code>substitute_literal</code></span></dt><dd>use <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_LITERAL</span></code></dd></div><div class="dlist-item"><dt><span><code>substitute_matched</code></span></dt><dd>use <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_MATCHED</span></code></dd></div><div class="dlist-item"><dt><span><code>substitute_overflow_length</code></span></dt><dd>use <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_OVERFLOW_LENGTH</span></code></dd></div><div class="dlist-item"><dt><span><code>substitute_replacement_only</code></span></dt><dd>use <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_REPLACEMENT_ONLY</span></code></dd></div><div class="dlist-item"><dt><span><code>substitute_skip=<n></code></span></dt><dd>skip substitution <n></dd></div><div class="dlist-item"><dt><span><code>substitute_stop=<n></code></span></dt><dd>skip substitution <n> and following</dd></div><div class="dlist-item"><dt><span><code>substitute_unknown_unset</code></span></dt><dd>use <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_UNKNOWN_UNSET</span></code></dd></div><div class="dlist-item"><dt><span><code>substitute_unset_empty</code></span></dt><dd>use <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_UNSET_EMPTY</span></code></dd></div></dl> | |
| <p>These modifiers may not appear in a <code>#pattern</code> command. If you want them as | |
| defaults, set them in a <code>#subject</code> command.</p></section> | |
| <section class="doc-section level-2"><h3 id="_specifying_literal_subject_lines">Specifying literal subject lines</h3><p>If the <code>subject_literal</code> modifier is present on a pattern, all the subject | |
| lines that it matches are taken as literal strings, with no interpretation of | |
| backslashes. It is not possible to set subject modifiers on such lines, but any | |
| that are set as defaults by a <code>#subject</code> command are recognized.</p></section> | |
| <section class="doc-section level-2"><h3 id="_saving_a_compiled_pattern">Saving a compiled pattern</h3><p>When a pattern with the <code>push</code> modifier is successfully compiled, it is | |
| pushed onto a stack of compiled patterns, and <code>pcre2test</code> expects the next | |
| line to contain a new pattern (or a command) instead of a subject line. This | |
| facility is used when saving compiled patterns to a file, as described in the | |
| section <a href="#saving-restoring-patterns">Saving and restoring compiled patterns</a> | |
| below. | |
| If <code>pushcopy</code> is used instead of <code>push</code>, a copy of the compiled | |
| pattern is stacked, leaving the original as current, ready to match the | |
| following input lines. This provides a way of testing the | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_code_copy()</span></code> function. | |
| The <code>push</code> and <code>pushcopy</code> modifiers are incompatible with compilation | |
| modifiers such as <code>global</code> that act at match time. Any that are specified | |
| are ignored (for the stacked copy), with a warning message, except for | |
| <code>replace</code>, which causes an error. Note that <code>jitverify</code>, which is | |
| allowed, does not carry through to any subsequent matching that uses a stacked | |
| pattern.</p></section> | |
| <section class="doc-section level-2"><h3 id="_testing_foreign_pattern_conversion">Testing foreign pattern conversion</h3><p>The experimental foreign pattern conversion functions in PCRE2 can be tested by | |
| setting the <code>convert</code> modifier. Its argument is a colon-separated list of | |
| options, which set the equivalent option for the <code class="function pcre2-api rouge"><span class="nf">pcre2_pattern_convert()</span></code> | |
| function:</p> | |
| <dl class="options compact" style="--tab-width: 12"><div class="dlist-item"><dt><span><code>glob</code></span></dt><dd><code class="constant pcre2-api rouge"><span class="no">PCRE2_CONVERT_GLOB</span></code></dd></div><div class="dlist-item"><dt><span><code>glob_no_starstar</code></span></dt><dd><code class="constant pcre2-api rouge"><span class="no">PCRE2_CONVERT_GLOB_NO_STARSTAR</span></code></dd></div><div class="dlist-item"><dt><span><code>glob_no_wild_separator</code></span></dt><dd><code class="constant pcre2-api rouge"><span class="no">PCRE2_CONVERT_GLOB_NO_WILD_SEPARATOR</span></code></dd></div><div class="dlist-item"><dt><span><code>posix_basic</code></span></dt><dd><code class="constant pcre2-api rouge"><span class="no">PCRE2_CONVERT_POSIX_BASIC</span></code></dd></div><div class="dlist-item"><dt><span><code>posix_extended</code></span></dt><dd><code class="constant pcre2-api rouge"><span class="no">PCRE2_CONVERT_POSIX_EXTENDED</span></code></dd></div><div class="dlist-item"><dt><span><code>unset</code></span></dt><dd>Unset all options</dd></div></dl> | |
| <p>The "unset" value is useful for turning off a default that has been set by a | |
| <code>#pattern</code> command. When one of these options is set, the input pattern is | |
| passed to <code class="function pcre2-api rouge"><span class="nf">pcre2_pattern_convert()</span></code>. If the conversion is successful, the | |
| result is reflected in the output and then passed to <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code>. The | |
| normal <code>utf</code> and <code>no_utf_check</code> options, if set, cause the | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_CONVERT_UTF</span></code> and <code class="constant pcre2-api rouge"><span class="no">PCRE2_CONVERT_NO_UTF_CHECK</span></code> options to be passed to | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_pattern_convert()</span></code>.</p> | |
| <p>By default, the conversion function is allowed to allocate a buffer for its | |
| output. However, if the <code>convert_length</code> modifier is set to a value greater | |
| than zero, <code>pcre2test</code> passes a buffer of the given length. This makes it | |
| possible to test the length check.</p> | |
| <p>The <code>convert_glob_escape</code> and <code>convert_glob_separator</code> modifiers can be | |
| used to specify the escape and separator characters for glob processing, | |
| overriding the defaults, which are operating-system dependent.</p></section></section> | |
| <section class="doc-section level-1"><h2 id="_subject_modifiers">Subject modifiers</h2><p>The modifiers that can appear in subject lines and the <code>#subject</code> | |
| command are of two types.</p> | |
| <section class="doc-section level-2"><h3 id="_setting_match_options">Setting match options</h3><p>The following modifiers set options for <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> or | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code>. See | |
| <a href="./pcre2api.html"><code>pcre2api</code></a> | |
| for a description of their effects.</p> | |
| <dl class="options compact" style="--tab-width: 14"><div class="dlist-item"><dt><span><code>anchored</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_ANCHORED</span></code></dd></div><div class="dlist-item"><dt><span><code>copy_matched_subject</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_COPY_MATCHED_SUBJECT</span></code></dd></div><div class="dlist-item"><dt><span><code>endanchored</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_ENDANCHORED</span></code></dd></div><div class="dlist-item"><dt><span><code>dfa_restart</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_DFA_RESTART</span></code></dd></div><div class="dlist-item"><dt><span><code>dfa_shortest</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_DFA_SHORTEST</span></code></dd></div><div class="dlist-item"><dt><span><code>disable_recurseloop_check</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_DISABLE_RECURSELOOP_CHECK</span></code></dd></div><div class="dlist-item"><dt><span><code>no_jit</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_JIT</span></code></dd></div><div class="dlist-item"><dt><span><code>no_utf_check</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_UTF_CHECK</span></code></dd></div><div class="dlist-item"><dt><span><code>notbol</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_NOTBOL</span></code></dd></div><div class="dlist-item"><dt><span><code>notempty</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_NOTEMPTY</span></code></dd></div><div class="dlist-item"><dt><span><code>notempty_atstart</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_NOTEMPTY_ATSTART</span></code></dd></div><div class="dlist-item"><dt><span><code>noteol</code></span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_NOTEOL</span></code></dd></div><div class="dlist-item"><dt><span><code>partial_hard</code> (or <code>ph</code>)</span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_PARTIAL_HARD</span></code></dd></div><div class="dlist-item"><dt><span><code>partial_soft</code> (or <code>ps</code>)</span></dt><dd>set <code class="constant pcre2-api rouge"><span class="no">PCRE2_PARTIAL_SOFT</span></code></dd></div></dl> | |
| <p>The partial matching modifiers are provided with abbreviations because they | |
| appear frequently in tests.</p> | |
| <p>If the <code>posix</code> or <code>posix_nosub</code> modifier was present on the pattern, | |
| causing the POSIX wrapper API to be used, the only option-setting modifiers | |
| that have any effect are <code>notbol</code>, <code>notempty</code>, and <code>noteol</code>, | |
| causing <code class="c rouge" data-lang="c"><span class="no">REG_NOTBOL</span></code>, <code class="c rouge" data-lang="c"><span class="no">REG_NOTEMPTY</span></code>, and <code class="c rouge" data-lang="c"><span class="no">REG_NOTEOL</span></code>, respectively, to be passed to | |
| <code class="c rouge" data-lang="c"><span class="nf">regexec</span><span class="p">()</span></code>. The other modifiers are ignored, with a warning message.</p> | |
| <p>There is one additional modifier that can be used with the POSIX wrapper. It is | |
| ignored (with a warning) if used for non-POSIX matching.</p> | |
| <dl class="options compact" style="--tab-width: 4"><div class="dlist-item"><dt><span><code>posix_startend=<n>[:<m>]</code></span></dt><dd>This causes the subject string to be passed to <code class="c rouge" data-lang="c"><span class="nf">regexec</span><span class="p">()</span></code> using the | |
| <code class="c rouge" data-lang="c"><span class="no">REG_STARTEND</span></code> option, which uses offsets to specify which part of the string is | |
| searched. If only one number is given, the end offset is passed as the end of | |
| the subject string. For more detail of <code class="c rouge" data-lang="c"><span class="no">REG_STARTEND</span></code>, see the | |
| <a href="./pcre2posix.html"><code>pcre2posix</code></a> | |
| documentation. If the subject string contains binary zeros (coded as escapes | |
| such as \x{00} because <code>pcre2test</code> does not support actual binary zeros in | |
| its input), you must use <code>posix_startend</code> to specify its length.</dd></div></dl></section> | |
| <section class="doc-section level-2"><h3 id="_setting_match_controls">Setting match controls</h3><p>The following modifiers affect the matching process or request additional | |
| information. Some of them may also be specified on a pattern line (see above), | |
| in which case they apply to every subject line that is matched against that | |
| pattern, but can be overridden by modifiers on the subject.</p> | |
| <dl class="options compact" style="--tab-width: 14"><div class="dlist-item"><dt><span><code>aftertext</code></span></dt><dd>show text after match</dd></div><div class="dlist-item"><dt><span><code>allaftertext</code></span></dt><dd>show text after captures</dd></div><div class="dlist-item"><dt><span><code>allcaptures</code></span></dt><dd>show all captures</dd></div><div class="dlist-item"><dt><span><code>allusedtext</code></span></dt><dd>show all consulted text (non-JIT only)</dd></div><div class="dlist-item"><dt><span><code>allvector</code></span></dt><dd>show the entire ovector</dd></div><div class="dlist-item"><dt><span><code>altglobal</code></span></dt><dd>alternative global matching</dd></div><div class="dlist-item"><dt><span><code>callout_capture</code></span></dt><dd>show captures at callout time</dd></div><div class="dlist-item"><dt><span><code>callout_data=<n></code></span></dt><dd>set a value to pass via callouts</dd></div><div class="dlist-item"><dt><span><code>callout_error=<n>[:<m>]</code></span></dt><dd>control callout error</dd></div><div class="dlist-item"><dt><span><code>callout_extra</code></span></dt><dd>show extra callout information</dd></div><div class="dlist-item"><dt><span><code>callout_fail=<n>[:<m>]</code></span></dt><dd>control callout failure</dd></div><div class="dlist-item"><dt><span><code>callout_no_where</code></span></dt><dd>do not show position of a callout</dd></div><div class="dlist-item"><dt><span><code>callout_none</code></span></dt><dd>do not supply a callout function</dd></div><div class="dlist-item"><dt><span><code>copy=<number or name></code></span></dt><dd>copy captured substring</dd></div><div class="dlist-item"><dt><span><code>depth_limit=<n></code></span></dt><dd>set a depth limit</dd></div><div class="dlist-item"><dt><span><code>dfa</code></span></dt><dd>use <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code></dd></div><div class="dlist-item"><dt><span><code>find_limits</code></span></dt><dd>find heap, match and depth limits</dd></div><div class="dlist-item"><dt><span><code>find_limits_noheap</code></span></dt><dd>find match and depth limits</dd></div><div class="dlist-item"><dt><span><code>get=<number or name></code></span></dt><dd>extract captured substring</dd></div><div class="dlist-item"><dt><span><code>getall</code></span></dt><dd>extract all captured substrings</dd></div><div class="dlist-item"><dt><span><code>/g global</code></span></dt><dd>global matching</dd></div><div class="dlist-item"><dt><span><code>heapframes_size</code></span></dt><dd>show match data heapframes size</dd></div><div class="dlist-item"><dt><span><code>heap_limit=<n></code></span></dt><dd>set a limit on heap memory (Kbytes)</dd></div><div class="dlist-item"><dt><span><code>jitstack=<n></code></span></dt><dd>set size of JIT stack</dd></div><div class="dlist-item"><dt><span><code>mark</code></span></dt><dd>show mark values</dd></div><div class="dlist-item"><dt><span><code>match_limit=<n></code></span></dt><dd>set a match limit</dd></div><div class="dlist-item"><dt><span><code>memory</code></span></dt><dd>show heap memory usage</dd></div><div class="dlist-item"><dt><span><code>null_context</code></span></dt><dd>match with a NULL context</dd></div><div class="dlist-item"><dt><span><code>null_replacement</code></span></dt><dd>substitute with NULL replacement</dd></div><div class="dlist-item"><dt><span><code>null_subject</code></span></dt><dd>match with NULL subject</dd></div><div class="dlist-item"><dt><span><code>null_substitute_buffer</code></span></dt><dd>substitute with a NULL output buffer</dd></div><div class="dlist-item"><dt><span><code>null_substitute_match_data</code></span></dt><dd>substitute with NULL match data</dd></div><div class="dlist-item"><dt><span><code>offset=<n></code></span></dt><dd>set starting offset</dd></div><div class="dlist-item"><dt><span><code>offset_limit=<n></code></span></dt><dd>set offset limit</dd></div><div class="dlist-item"><dt><span><code>ovector=<n></code></span></dt><dd>set size of output vector</dd></div><div class="dlist-item"><dt><span><code>recursion_limit=<n></code></span></dt><dd>obsolete synonym for depth_limit</dd></div><div class="dlist-item"><dt><span><code>replace=<str></code></span></dt><dd>specify a replacement string</dd></div><div class="dlist-item"><dt><span><code>startchar</code></span></dt><dd>show startchar when relevant</dd></div><div class="dlist-item"><dt><span><code>startoffset=<n></code></span></dt><dd>same as offset=<n></dd></div><div class="dlist-item"><dt><span><code>substitute_callout</code></span></dt><dd>use substitution callouts</dd></div><div class="dlist-item"><dt><span><code>substitute_case_callout</code></span></dt><dd>use substitution case callouts</dd></div><div class="dlist-item"><dt><span><code>substitute_extended</code></span></dt><dd>use <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_EXTENDED</span></code></dd></div><div class="dlist-item"><dt><span><code>substitute_literal</code></span></dt><dd>use <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_LITERAL</span></code></dd></div><div class="dlist-item"><dt><span><code>substitute_matched</code></span></dt><dd>use <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_MATCHED</span></code></dd></div><div class="dlist-item"><dt><span><code>substitute_overflow_length</code></span></dt><dd>use <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_OVERFLOW_LENGTH</span></code></dd></div><div class="dlist-item"><dt><span><code>substitute_replacement_only</code></span></dt><dd>use <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_REPLACEMENT_ONLY</span></code></dd></div><div class="dlist-item"><dt><span><code>substitute_skip=<n></code></span></dt><dd>skip substitution number n</dd></div><div class="dlist-item"><dt><span><code>substitute_stop=<n></code></span></dt><dd>skip substitution number n and greater</dd></div><div class="dlist-item"><dt><span><code>substitute_subject=<str></code></span></dt><dd>specify a different subject for substitution</dd></div><div class="dlist-item"><dt><span><code>substitute_unknown_unset</code></span></dt><dd>use <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_UNKNOWN_UNSET</span></code></dd></div><div class="dlist-item"><dt><span><code>substitute_unset_empty</code></span></dt><dd>use <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_UNSET_EMPTY</span></code></dd></div><div class="dlist-item"><dt><span><code>zero_terminate</code></span></dt><dd>pass the subject as zero-terminated</dd></div></dl> | |
| <p>The effects of these modifiers are described in the following sections. When | |
| matching via the POSIX wrapper API, the <code>aftertext</code>, <code>allaftertext</code>, | |
| and <code>ovector</code> subject modifiers work as described below. All other | |
| modifiers are either ignored, with a warning message, or cause an error.</p></section> | |
| <section class="doc-section level-2"><h3 id="_showing_more_text">Showing more text</h3><p>The <code>aftertext</code> modifier requests that as well as outputting the part of | |
| the subject string that matched the entire pattern, <code>pcre2test</code> should in | |
| addition output the remainder of the subject string. This is useful for tests | |
| where the subject contains multiple copies of the same substring. The | |
| <code>allaftertext</code> modifier requests the same action for captured substrings as | |
| well as the main matched substring. In each case the remainder is output on the | |
| following line with a plus character following the capture number.</p> | |
| <p>The <code>allusedtext</code> modifier requests that all the text that was consulted | |
| during a successful pattern match by the interpreter should be shown, for both | |
| full and partial matches. This feature is not supported for JIT matching, and | |
| if requested with JIT it is ignored (with a warning message). Setting this | |
| modifier affects the output if there is a lookbehind at the start of a match, | |
| or, for a complete match, a lookahead at the end, or if <code class="regex rouge"><span class="pcre2-semantic">\K</span></code> is used in the | |
| pattern. Characters that precede or follow the start and end of the actual | |
| match are indicated in the output by '<' or '>' characters underneath them. | |
| Here is an example:</p> | |
| <div class="literal-block"><pre> re> /(?<=pqr)abc(?=xyz)/ | |
| data> 123pqrabcxyz456\=allusedtext | |
| 0: pqrabcxyz | |
| <<< >>> | |
| data> 123pqrabcxy\=ph,allusedtext | |
| Partial match: pqrabcxy | |
| <<<</pre></div> | |
| <p>The first, complete match shows that the matched string is "abc", with the | |
| preceding and following strings "pqr" and "xyz" having been consulted during | |
| the match (when processing the assertions). The partial match can indicate only | |
| the preceding string.</p> | |
| <p>The <code>startchar</code> modifier requests that the starting character for the match | |
| be indicated, if it is different to the start of the matched string. The only | |
| time when this occurs is when <code class="regex rouge"><span class="pcre2-semantic">\K</span></code> has been processed as part of the match. In | |
| this situation, the output for the matched string is displayed from the | |
| starting character instead of from the match point, with circumflex characters | |
| under the earlier characters. For example:</p> | |
| <div class="literal-block"><pre> re> /abc\Kxyz/ | |
| data> abcxyz\=startchar | |
| 0: abcxyz | |
| ^^^</pre></div> | |
| <p>Unlike <code>allusedtext</code>, the <code>startchar</code> modifier can be used with JIT. | |
| However, these two modifiers are mutually exclusive.</p></section> | |
| <section class="doc-section level-2"><h3 id="_showing_the_value_of_all_capture_groups">Showing the value of all capture groups</h3><p>The <code>allcaptures</code> modifier requests that the values of all potential | |
| captured parentheses be output after a match. By default, only those up to the | |
| highest one actually used in the match are output (corresponding to the return | |
| code from <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code>). Groups that did not take part in the match | |
| are output as "<unset>". This modifier is not relevant for DFA matching (which | |
| does no capturing) and does not apply when <code>replace</code> is specified; it is | |
| ignored, with a warning message, if present.</p></section> | |
| <section class="doc-section level-2"><h3 id="_showing_the_entire_ovector_for_all_outcomes">Showing the entire ovector, for all outcomes</h3><p>The <code>allvector</code> modifier requests that the entire ovector be shown, | |
| whatever the outcome of the match. Compare <code>allcaptures</code>, which shows only | |
| up to the maximum number of capture groups for the pattern, and then only for a | |
| successful complete non-DFA match. This modifier, which acts after any match | |
| result, and also for DFA matching, provides a means of checking that there are | |
| no unexpected modifications to ovector fields. Before each match attempt, the | |
| ovector is filled with a special value, and if this is found in both elements | |
| of a capturing pair, "<unchanged>" is output. After a successful match, this | |
| applies to all groups after the maximum capture group for the pattern. In other | |
| cases it applies to the entire ovector. After a partial match, the first two | |
| elements are the only ones that should be set. After a DFA match, the amount of | |
| ovector that is used depends on the number of matches that were found.</p></section> | |
| <section class="doc-section level-2"><h3 id="_testing_pattern_callouts">Testing pattern callouts</h3><p>A callout function is supplied when <code>pcre2test</code> calls the library matching | |
| functions, unless <code>callout_none</code> is specified. Its behaviour can be | |
| controlled by various modifiers listed above whose names begin with | |
| <code>callout_</code>. Details are given in the section <a href="#callouts">Callouts</a> | |
| below. | |
| Testing callouts from <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code> is described separately in | |
| "Testing the substitution function" | |
| below.</p></section> | |
| <section class="doc-section level-2"><h3 id="_finding_all_matches_in_a_string">Finding all matches in a string</h3><p>Searching for all possible matches within a subject can be requested by the | |
| <code>global</code> or <code>altglobal</code> modifier. After finding a match, the matching | |
| function is called again to search the remainder of the subject. The difference | |
| between <code>global</code> and <code>altglobal</code> is that the former uses the | |
| <code class="parameter pcre2-api rouge"><span class="nv">start_offset</span></code> argument to <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> or <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code> | |
| to start searching at a new point within the entire string (which is what Perl | |
| does), whereas the latter passes over a shortened subject. This makes a | |
| difference to the matching process if the pattern begins with a lookbehind | |
| assertion (including <code class="regex rouge"><span class="pcre2-semantic">\b</span></code> or <code class="regex rouge"><span class="pcre2-semantic">\B</span></code>).</p> | |
| <p>If an empty string is matched, the next match is done with the | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_NOTEMPTY_ATSTART</span></code> flag set, in order to search for another, non-empty, | |
| match at the same point in the subject. This imitates the way Perl handles such | |
| cases when using the <code class="regex rouge"><span class="pcre2-semantic">/g</span></code> modifier or the <code>split()</code> function.</p></section> | |
| <section class="doc-section level-2"><h3 id="_testing_substring_extraction_functions">Testing substring extraction functions</h3><p>The <code>copy</code> and <code>get</code> modifiers can be used to test the | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_substring_copy_xxx()</span></code> and <code class="function pcre2-api rouge"><span class="nf">pcre2_substring_get_xxx()</span></code> functions. | |
| They can be given more than once, and each can specify a capture group name or | |
| number, for example:</p> | |
| <div class="literal-block"><pre> abcd\=copy=1,copy=3,get=G1</pre></div> | |
| <p>If the <code>#subject</code> command is used to set default copy and/or get lists, | |
| these can be unset by specifying a negative number to cancel all numbered | |
| groups and an empty name to cancel all named groups.</p> | |
| <p>The <code>getall</code> modifier tests <code class="function pcre2-api rouge"><span class="nf">pcre2_substring_list_get()</span></code>, which | |
| extracts all captured substrings.</p> | |
| <p>If the subject line is successfully matched, the substrings extracted by the | |
| convenience functions are output with C, G, or L after the string number | |
| instead of a colon. This is in addition to the normal full list. The string | |
| length (that is, the return from the extraction function) is given in | |
| parentheses after each substring, followed by the name when the extraction was | |
| by name.</p></section> | |
| <section class="doc-section level-2"><h3 id="_testing_the_substitution_function">Testing the substitution function</h3><p>If the <code>replace</code> modifier is set, the <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code> function is | |
| called instead of one of the matching functions (or after one call of | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> in the case of <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_MATCHED</span></code>). Note that | |
| replacement strings cannot contain commas, because a comma signifies the end of | |
| a modifier. This is not thought to be an issue in a test program.</p> | |
| <p>Specifying a completely empty replacement string disables this modifier. | |
| However, it is possible to specify an empty replacement by providing a buffer | |
| length, as described below, for an otherwise empty replacement.</p> | |
| <p>Unlike subject strings, <code>pcre2test</code> does not process replacement strings | |
| for escape sequences. In UTF mode, a replacement string is checked to see if it | |
| is a valid UTF-8 string. If so, it is correctly converted to a UTF string of | |
| the appropriate code unit width. If it is not a valid UTF-8 string, the | |
| individual code units are copied directly. This provides a means of passing an | |
| invalid UTF-8 string for testing purposes.</p> | |
| <p>The following modifiers set options (in additional to the normal match options) | |
| for <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code>:</p> | |
| <dl class="options compact" style="--tab-width: 14"><div class="dlist-item"><dt><span><code>global</code></span></dt><dd><code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_GLOBAL</span></code></dd></div><div class="dlist-item"><dt><span><code>substitute_extended</code></span></dt><dd><code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_EXTENDED</span></code></dd></div><div class="dlist-item"><dt><span><code>substitute_literal</code></span></dt><dd><code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_LITERAL</span></code></dd></div><div class="dlist-item"><dt><span><code>substitute_matched</code></span></dt><dd><code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_MATCHED</span></code></dd></div><div class="dlist-item"><dt><span><code>substitute_overflow_length</code></span></dt><dd><code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_OVERFLOW_LENGTH</span></code></dd></div><div class="dlist-item"><dt><span><code>substitute_replacement_only</code></span></dt><dd><code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_REPLACEMENT_ONLY</span></code></dd></div><div class="dlist-item"><dt><span><code>substitute_unknown_unset</code></span></dt><dd><code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_UNKNOWN_UNSET</span></code></dd></div><div class="dlist-item"><dt><span><code>substitute_unset_empty</code></span></dt><dd><code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_UNSET_EMPTY</span></code></dd></div></dl> | |
| <p>See the | |
| <a href="./pcre2api.html"><code>pcre2api</code></a> | |
| documentation for details of these options.</p> | |
| <p>After a successful substitution, the modified string is output, preceded by the | |
| number of replacements. This may be zero if there were no matches. Here is a | |
| simple example of a substitution test:</p> | |
| <div class="literal-block"><pre>/abc/replace=xxx | |
| =abc=abc= | |
| 1: =xxx=abc= | |
| =abc=abc=\=global | |
| 2: =xxx=xxx=</pre></div> | |
| <p>Subject and replacement strings should be kept relatively short (fewer than 256 | |
| characters) for substitution tests, as fixed-size buffers are used. To make it | |
| easy to test for buffer overflow, if the replacement string starts with a | |
| number in square brackets, that number is passed to <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code> as | |
| the size of the output buffer, with the replacement string starting at the next | |
| character. Here is an example that tests the edge case:</p> | |
| <div class="literal-block"><pre>/abc/ | |
| 123abc123\=replace=[10]XYZ | |
| 1: 123XYZ123 | |
| 123abc123\=replace=[9]XYZ | |
| Failed: error -48: no more memory</pre></div> | |
| <p>The default action of <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code> is to return | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_NOMEMORY</span></code> when the output buffer is too small. However, if the | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_OVERFLOW_LENGTH</span></code> option is set (by using the | |
| <code>substitute_overflow_length</code> modifier), <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code> continues | |
| to go through the motions of matching and substituting (but not doing any | |
| callouts), in order to compute the size of buffer that is required. When this | |
| happens, <code>pcre2test</code> shows the required buffer length (which includes space | |
| for the trailing zero) as part of the error message. For example:</p> | |
| <div class="literal-block"><pre>/abc/substitute_overflow_length | |
| 123abc123\=replace=[9]XYZ | |
| Failed: error -48: no more memory: 10 code units are needed</pre></div> | |
| <p>A replacement string is ignored with POSIX and DFA matching. Specifying partial | |
| matching provokes an error return ("bad option value") from | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code>.</p> | |
| <p>The <code>substitute_subject</code> modifier may be used to test the use of the PCRE2 | |
| API, in which a client calls <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> followed by <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code> | |
| with <code class="constant pcre2-api rouge"><span class="no">PCRE2_SUBSTITUTE_MATCHED</span></code>, but the client performs an unexpected and | |
| unsupported modification of the subject buffer in-place, in between the match | |
| and substitution.</p></section> | |
| <section class="doc-section level-2"><h3 id="_testing_substitute_callouts">Testing substitute callouts</h3><p>If the <code>substitute_callout</code> modifier is set, a substitution callout | |
| function is set up. The <code>null_context</code> modifier must not be set, because | |
| the address of the callout function is passed in a match context. When the | |
| callout function is called (after each substitution), details of the input | |
| and output strings are output. For example:</p> | |
| <div class="literal-block"><pre>/abc/g,replace=<$0>,substitute_callout | |
| abcdefabcpqr | |
| 1(1) Old 0 3 "abc" New 0 5 "<abc>" | |
| 2(1) Old 6 9 "abc" New 8 13 "<abc>" | |
| 2: <abc>def<abc>pqr</pre></div> | |
| <p>The first number on each callout line is the count of matches. The | |
| parenthesized number is the number of pairs that are set in the ovector (that | |
| is, one more than the number of capturing groups that were set). Then are | |
| listed the offsets of the old substring, its contents, and the same for the | |
| replacement.</p> | |
| <p>By default, the substitution callout function returns zero, which accepts the | |
| replacement and causes matching to continue if /g was used. Two further | |
| modifiers can be used to test other return values. If <code>substitute_skip</code> is | |
| set to a value greater than zero the callout function returns <code class="c rouge" data-lang="c"><span class="o">+</span><span class="mi">1</span></code> for the match | |
| of that number, and similarly <code>substitute_stop</code> returns -1. These cause the | |
| replacement to be rejected, and -1 causes no further matching to take place. If | |
| either of them are set, <code>substitute_callout</code> is assumed. For example:</p> | |
| <div class="literal-block"><pre>/abc/g,replace=<$0>,substitute_skip=1 | |
| abcdefabcpqr | |
| 1(1) Old 0 3 "abc" New 0 5 "<abc> SKIPPED" | |
| 2(1) Old 6 9 "abc" New 6 11 "<abc>" | |
| 2: abcdef<abc>pqr | |
| abcdefabcpqr\=substitute_stop=1 | |
| 1(1) Old 0 3 "abc" New 0 5 "<abc> STOPPED" | |
| 1: abcdefabcpqr</pre></div> | |
| <p>If both are set for the same number, stop takes precedence. Only a single skip | |
| or stop is supported, which is sufficient for testing that the feature works.</p></section> | |
| <section class="doc-section level-2"><h3 id="_testing_substitute_case_callouts">Testing substitute case callouts</h3><p>If the <code>substitute_case_callout</code> modifier is set, a substitution | |
| case callout function is set up. The callout function is called for each | |
| substituted chunk which is to be case-transformed.</p> | |
| <p>The callout function passed is a fixed function with implementation for certain | |
| behaviours: inputs which shrink when case-transformed; inputs which grow; inputs | |
| with distinct upper/lower/titlecase forms. The characters which are not | |
| special-cased for testing purposes are left unmodified, as if they are caseless | |
| characters.</p></section> | |
| <section class="doc-section level-2"><h3 id="_setting_the_jit_stack_size">Setting the JIT stack size</h3><p>The <code>jitstack</code> modifier provides a way of setting the maximum stack size | |
| that is used by the just-in-time optimization code. It is ignored if JIT | |
| optimization is not being used. The value is a number of kibibytes (units of | |
| 1024 bytes). Setting zero reverts to the default of 32KiB. Providing a stack | |
| that is larger than the default is necessary only for very complicated | |
| patterns. If <code>jitstack</code> is set non-zero on a subject line it overrides any | |
| value that was set on the pattern.</p></section> | |
| <section class="doc-section level-2"><h3 id="_setting_heap_match_and_depth_limits">Setting heap, match, and depth limits</h3><p>The <code>heap_limit</code>, <code>match_limit</code>, and <code>depth_limit</code> modifiers set | |
| the appropriate limits in the match context. These values are ignored when the | |
| <code>find_limits</code> or <code>find_limits_noheap</code> modifier is specified.</p></section> | |
| <section class="doc-section level-2"><h3 id="_finding_minimum_limits">Finding minimum limits</h3><p>If the <code>find_limits</code> modifier is present on a subject line, <code>pcre2test</code> | |
| calls the relevant matching function several times, setting different values in | |
| the match context via <code class="function pcre2-api rouge"><span class="nf">pcre2_set_heap_limit()</span></code>, | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_set_match_limit()</span></code>, or <code class="function pcre2-api rouge"><span class="nf">pcre2_set_depth_limit()</span></code> until it finds | |
| the smallest value for each parameter that allows the match to complete without | |
| a "limit exceeded" error. The match itself may succeed or fail. An alternative | |
| modifier, <code>find_limits_noheap</code>, omits the heap limit. This is used in the | |
| standard tests, because the minimum heap limit varies between systems. If JIT | |
| is being used, only the match limit is relevant, and the other two are | |
| automatically omitted.</p> | |
| <p>When using this modifier, the pattern should not contain any limit settings | |
| such as (<code class="regex rouge"><span class="pcre2-semantic">*LIMIT_MATCH=...</span></code>) within it. If such a setting is present and is | |
| lower than the minimum matching value, the minimum value cannot be found | |
| because <code class="function pcre2-api rouge"><span class="nf">pcre2_set_match_limit()</span></code> etc. are only able to reduce the value of | |
| an in-pattern limit; they cannot increase it.</p> | |
| <p>For non-DFA matching, the minimum <code>depth_limit</code> number is a measure of how | |
| much nested backtracking happens (that is, how deeply the pattern’s tree is | |
| In the case of DFA matching, <code>depth_limit</code> controls the depth of | |
| recursive calls of the internal function that is used for handling pattern | |
| recursion, lookaround assertions, and atomic groups.</p> | |
| <p>For non-DFA matching, the <code>match_limit</code> number is a measure of the amount | |
| of backtracking that takes place, and learning the minimum value can be | |
| instructive. For most simple matches, the number is quite small, but for | |
| patterns with very large numbers of matching possibilities, it can become large | |
| very quickly with increasing length of subject string. In the case of DFA | |
| matching, <code>match_limit</code> controls the total number of calls, both recursive | |
| and non-recursive, to the internal matching function, thus controlling the | |
| overall amount of computing resource that is used.</p> | |
| <p>For both kinds of matching, the <code>heap_limit</code> number, which is in kibibytes | |
| (units of 1024 bytes), limits the amount of heap memory used for matching.</p></section> | |
| <section class="doc-section level-2"><h3 id="_showing_mark_names">Showing MARK names</h3><p>The <code>mark</code> modifier causes the names from backtracking control verbs that | |
| are returned from calls to <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> to be displayed. If a mark is | |
| returned for a match, non-match, or partial match, <code>pcre2test</code> shows it. | |
| For a match, it is on a line by itself, tagged with <code>MK:</code>. Otherwise, it | |
| is added to the non-match message.</p></section> | |
| <section class="doc-section level-2"><h3 id="_showing_memory_usage">Showing memory usage</h3><p>The <code>memory</code> modifier causes <code>pcre2test</code> to log the sizes of all heap | |
| memory allocation and freeing calls that occur during a call to | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> or <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code>. In the latter case, heap memory | |
| is used only when a match requires more internal workspace that the default | |
| allocation on the stack, so in many cases there will be no output. No heap | |
| memory is allocated during matching with JIT. For this modifier to work, the | |
| <code>null_context</code> modifier must not be set on both the pattern and the | |
| subject, though it can be set on one or the other.</p></section> | |
| <section class="doc-section level-2"><h3 id="_showing_the_heap_frame_overall_vector_size">Showing the heap frame overall vector size</h3><p>The <code>heapframes_size</code> modifier is relevant for matches using | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> without JIT. After a match has run (whether successful or | |
| not) the size, in bytes, of the allocated heap frames vector that is left | |
| attached to the match data block is shown. If the matching action involved | |
| several calls to <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> (for example, global matching or for | |
| timing) only the final value is shown.</p> | |
| <p>This modifier is ignored, with a warning, for POSIX or DFA matching. JIT | |
| matching does not use the heap frames vector, so the size is always zero, | |
| unless there was a previous non-JIT match. Note that specifing a size of zero | |
| for the output vector (see below) causes <code>pcre2test</code> to free its match data | |
| block (and associated heap frames vector) and allocate a new one.</p></section> | |
| <section class="doc-section level-2"><h3 id="_setting_a_starting_offset">Setting a starting offset</h3><p>The <code>offset</code> modifier sets an offset in the subject string at which | |
| matching starts. Its value is a number of code units, not characters.</p></section> | |
| <section class="doc-section level-2"><h3 id="_setting_an_offset_limit">Setting an offset limit</h3><p>The <code>offset_limit</code> modifier sets a limit for unanchored matches. If a match | |
| cannot be found starting at or before this offset in the subject, a "no match" | |
| return is given. The data value is a number of code units, not characters. When | |
| this modifier is used, the <code>use_offset_limit</code> modifier must have been set | |
| for the pattern; if not, an error is generated.</p></section> | |
| <section class="doc-section level-2"><h3 id="_setting_the_size_of_the_output_vector">Setting the size of the output vector</h3><p>The <code>ovector</code> modifier applies only to the subject line in which it | |
| appears, though of course it can also be used to set a default in a | |
| <code>#subject</code> command. It specifies the number of pairs of offsets that are | |
| available for storing matching information. The default is 15.</p> | |
| <p>A value of zero is useful when testing the POSIX API because it causes | |
| <code class="c rouge" data-lang="c"><span class="nf">regexec</span><span class="p">()</span></code> to be called with a <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> capture vector. When not testing the | |
| POSIX API, a value of zero is used to cause | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_match_data_create_from_pattern()</span></code> to be called, in order to create a | |
| new match block of exactly the right size for the pattern. (It is not possible | |
| to create a match block with a zero-length ovector; there is always at least | |
| one pair of offsets.) The old match data block is freed.</p></section> | |
| <section class="doc-section level-2"><h3 id="_passing_the_subject_as_zero_terminated">Passing the subject as zero-terminated</h3><p>By default, the subject string is passed to a native API matching function with | |
| its correct length. In order to test the facility for passing a zero-terminated | |
| string, the <code>zero_terminate</code> modifier is provided. It causes the length to | |
| be passed as <code class="constant pcre2-api rouge"><span class="no">PCRE2_ZERO_TERMINATED</span></code>. When matching via the POSIX interface, | |
| this modifier is ignored, with a warning.</p> | |
| <p>When testing <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code>, this modifier also has the effect of | |
| passing the replacement string as zero-terminated.</p></section> | |
| <section class="doc-section level-2"><h3 id="_passing_a_null_context_subject_replacement_or_substitute_buffer">Passing a <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> context, subject, replacement, or substitute buffer</h3><p>Normally, <code>pcre2test</code> passes a context block to <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code>, | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code>, <code class="function pcre2-api rouge"><span class="nf">pcre2_jit_match()</span></code> or <code class="function pcre2-api rouge"><span class="nf">pcre2_substitute()</span></code>. | |
| If the <code>null_context</code> modifier is set, however, <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code> is passed. This is for | |
| testing that the matching and substitution functions behave correctly in this | |
| case (they use default values). This modifier cannot be used with the | |
| <code>find_limits</code>, <code>find_limits_noheap</code>, or <code>substitute_callout</code> | |
| modifiers.</p> | |
| <p>Similarly, for testing purposes, if the <code>null_subject</code>, | |
| or <code>null_replacement</code>, or <code>null_substitute_buffer</code> modifiers are set, then the | |
| subject, or replacement string, or substitute output buffer pointers are passed | |
| as <code class="constant pcre2-api rouge"><span class="kc">NULL</span></code>, respectively, to the relevant functions. For <code>null_substitute_buffer</code>, | |
| the paired argument for the passed-in buffer length is set by starting the | |
| replacement string with "[NUM]" as described in "Testing the substitution | |
| function" above.</p></section></section> | |
| <section class="doc-section level-1"><h2 id="_the_alternative_matching_function">The alternative matching function</h2><p>By default, <code>pcre2test</code> uses the standard PCRE2 matching function, | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> to match each subject line. PCRE2 also supports an | |
| alternative matching function, <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code>, which operates in a | |
| different way, and has some restrictions. The differences between the two | |
| functions are described in the | |
| <a href="./pcre2matching.html"><code>pcre2matching</code></a> | |
| documentation.</p> | |
| <p>If the <code>dfa</code> modifier is set, the alternative matching function is used. | |
| This function finds all possible matches at a given point in the subject. If, | |
| however, the <code>dfa_shortest</code> modifier is set, processing stops after the | |
| first match is found. This is always the shortest possible match.</p></section> | |
| <section class="doc-section level-1"><h2 id="_default_output_from_pcre2test">Default output from pcre2test</h2><p>This section describes the output when the normal matching function, | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code>, is being used.</p> | |
| <p>When a match succeeds, <code>pcre2test</code> outputs the list of captured substrings, | |
| starting with number 0 for the string that matched the whole pattern. | |
| Otherwise, it outputs "No match" when the return is <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_NOMATCH</span></code>, or | |
| "Partial match:" followed by the partially matching substring when the | |
| return is <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_PARTIAL</span></code>. (Note that this is the | |
| entire substring that was inspected during the partial match; it may include | |
| characters before the actual match start if a lookbehind assertion, <code class="regex rouge"><span class="pcre2-semantic">\K</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\b</span></code>, | |
| or <code class="regex rouge"><span class="pcre2-semantic">\B</span></code> was involved.)</p> | |
| <p>For any other return, <code>pcre2test</code> outputs the PCRE2 negative error number | |
| and a short descriptive phrase. If the error is a failed UTF string check, the | |
| code unit offset of the start of the failing character is also output. Here is | |
| an example of an interactive <code>pcre2test</code> run.</p> | |
| <div class="literal-block"><pre>$ pcre2test | |
| PCRE2 version 10.22 2016-07-29</pre></div> | |
| <div class="literal-block"><pre> re> /^abc(\d+)/ | |
| data> abc123 | |
| 0: abc123 | |
| 1: 123 | |
| data> xyz | |
| No match</pre></div> | |
| <p>Unset capturing substrings that are not followed by one that is set are not | |
| shown by <code>pcre2test</code> unless the <code>allcaptures</code> modifier is specified. In | |
| the following example, there are two capturing substrings, but when the first | |
| data line is matched, the second, unset substring is not shown. An "internal" | |
| unset substring is shown as "<unset>", as for the second data line.</p> | |
| <div class="literal-block"><pre> re> /(a)|(b)/ | |
| data> a | |
| 0: a | |
| 1: a | |
| data> b | |
| 0: b | |
| 1: <unset> | |
| 2: b</pre></div> | |
| <p>If the strings contain any non-printing characters, they are output as \xhh | |
| escapes if the value is less than 256 and UTF mode is not set. Otherwise they | |
| are output as <code>\x{<em>hh</em>...}</code> escapes. See below for the definition of non-printing | |
| characters. If the <code>aftertext</code> modifier is set, the output for substring 0 | |
| is followed by the rest of the subject string, identified by "0+" like this:</p> | |
| <div class="literal-block"><pre> re> /cat/aftertext | |
| data> cataract | |
| 0: cat | |
| 0+ aract</pre></div> | |
| <p>If global matching is requested, the results of successive matching attempts | |
| are output in sequence, like this:</p> | |
| <div class="literal-block"><pre> re> /\Bi(\w\w)/g | |
| data> Mississippi | |
| 0: iss | |
| 1: ss | |
| 0: iss | |
| 1: ss | |
| 0: ipp | |
| 1: pp</pre></div> | |
| <p>"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 the <code>offset</code> | |
| modifier is past the end of the subject string):</p> | |
| <div class="literal-block"><pre> re> /xyz/ | |
| data> xyz\=offset=4 | |
| Error -24 (bad offset value)</pre></div> | |
| <p>Note that whereas patterns can be continued over several lines (a plain ">" | |
| prompt is used for continuations), subject lines may not. However newlines can | |
| be included in a subject by means of the \n escape (or \r, \r\n, etc., | |
| depending on the newline sequence setting).</p></section> | |
| <section class="doc-section level-1"><h2 id="_output_from_the_alternative_matching_function">Output from the alternative matching function</h2><p>When the alternative matching function, <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code>, is used, the | |
| output consists of a list of all the matches that start at the first point in | |
| the subject where there is at least one match. For example:</p> | |
| <div class="literal-block"><pre> re> /(tang|tangerine|tan)/ | |
| data> yellow tangerine\=dfa | |
| 0: tangerine | |
| 1: tang | |
| 2: tan</pre></div> | |
| <p>Using the normal matching function on this data finds only "tang". The | |
| longest matching string is always given first (and numbered zero). After a | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_PARTIAL</span></code> return, the output is "Partial match:", followed by the | |
| partially matching substring. Note that this is the entire substring that was | |
| inspected during the partial match; it may include characters before the actual | |
| match start if a lookbehind assertion, <code class="regex rouge"><span class="pcre2-semantic">\b</span></code>, or <code class="regex rouge"><span class="pcre2-semantic">\B</span></code> was involved. (<code class="regex rouge"><span class="pcre2-semantic">\K</span></code> is not | |
| supported for DFA matching.)</p> | |
| <p>If global matching is requested, the search for further matches resumes | |
| at the end of the longest match. For example:</p> | |
| <div class="literal-block"><pre> re> /(tang|tangerine|tan)/g | |
| data> yellow tangerine and tangy sultana\=dfa | |
| 0: tangerine | |
| 1: tang | |
| 2: tan | |
| 0: tang | |
| 1: tan | |
| 0: tan</pre></div> | |
| <p>The alternative matching function does not support substring capture, so the | |
| modifiers that are concerned with captured substrings are not relevant.</p></section> | |
| <section class="doc-section level-1"><h2 id="_restarting_after_a_partial_match">Restarting after a partial match</h2><p>When the alternative matching function has given the <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_PARTIAL</span></code> | |
| return, indicating that the subject partially matched the pattern, you can | |
| restart the match with additional subject data by means of the | |
| <code>dfa_restart</code> modifier. For example:</p> | |
| <div class="literal-block"><pre> re> /^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$/ | |
| data> 23ja\=ps,dfa | |
| Partial match: 23ja | |
| data> n05\=dfa,dfa_restart | |
| 0: n05</pre></div> | |
| <p>For further information about partial matching, see the | |
| <a href="./pcre2partial.html"><code>pcre2partial</code></a> | |
| documentation.</p></section> | |
| <section class="doc-section level-1"><h2 id="callouts">Callouts</h2><p>If the pattern contains any callout requests, <code>pcre2test</code>'s callout | |
| function is called during matching unless <code>callout_none</code> is specified. This | |
| works with both matching functions, and with JIT, though there are some | |
| differences in behaviour. The output for callouts with numerical arguments and | |
| those with string arguments is slightly different.</p> | |
| <section class="doc-section level-2"><h3 id="_callouts_with_numerical_arguments">Callouts with numerical arguments</h3><p>By default, the callout function displays the callout number, the start and | |
| current positions in the subject text at the callout time, and the next pattern | |
| item to be tested. For example:</p> | |
| <div class="literal-block"><pre>--->pqrabcdef | |
| 0 ^ ^ \d</pre></div> | |
| <p>This output indicates that callout number 0 occurred for a match attempt | |
| starting at the fourth character of the subject string, when the pointer was at | |
| the seventh character, and when the next pattern item was <code class="regex rouge"><span class="pcre2-semantic">\d</span></code>. Just | |
| one circumflex is output if the start and current positions are the same, or if | |
| the current position precedes the start position, which can happen if the | |
| callout is in a lookbehind assertion.</p> | |
| <p>Callouts numbered 255 are assumed to be automatic callouts, inserted as a | |
| result of the <code>auto_callout</code> pattern modifier. In this case, instead of | |
| showing the callout number, the offset in the pattern, preceded by a plus, is | |
| output. For example:</p> | |
| <div class="literal-block"><pre> re> /\d?[A-E]\*/auto_callout | |
| data> E* | |
| --->E* | |
| +0 ^ \d? | |
| +3 ^ [A-E] | |
| +8 ^^ \* | |
| +10 ^ ^ | |
| 0: E*</pre></div> | |
| <p>If a pattern contains <code class="regex rouge"><span class="pcre2-semantic">(*MARK)</span></code> items, an additional line is output whenever | |
| a change of latest mark is passed to the callout function. For example:</p> | |
| <div class="literal-block"><pre> re> /a(*MARK:X)bc/auto_callout | |
| data> abc | |
| --->abc | |
| +0 ^ a | |
| +1 ^^ (*MARK:X) | |
| +10 ^^ b | |
| Latest Mark: X | |
| +11 ^ ^ c | |
| +12 ^ ^ | |
| 0: abc</pre></div> | |
| <p>The mark changes between matching "a" and "b", but stays the same for the rest | |
| of the match, so nothing more is output. If, as a result of backtracking, the | |
| mark reverts to being unset, the text "<unset>" is output.</p></section> | |
| <section class="doc-section level-2"><h3 id="_callouts_with_string_arguments">Callouts with string arguments</h3><p>The output for a callout with a string argument is similar, except that instead | |
| of outputting a callout number before the position indicators, the callout | |
| string and its offset in the pattern string are output before the reflection of | |
| the subject string, and the subject string is reflected for each callout. For | |
| example:</p> | |
| <div class="literal-block"><pre> re> /^ab(?C’first')cd(?C"second")ef/ | |
| data> abcdefg | |
| Callout (7): 'first' | |
| --->abcdefg | |
| ^ ^ c | |
| Callout (20): "second" | |
| --->abcdefg | |
| ^ ^ e | |
| 0: abcdef</pre></div></section> | |
| <section class="doc-section level-2"><h3 id="_callout_modifiers">Callout modifiers</h3><p>The callout function in <code>pcre2test</code> returns zero (carry on matching) by | |
| default, but you can use a <code>callout_fail</code> modifier in a subject line to | |
| change this and other parameters of the callout (see below).</p> | |
| <p>If the <code>callout_capture</code> modifier is set, the current captured groups are | |
| output when a callout occurs. This is useful only for non-DFA matching, as | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code> does not support capturing, so no captures are ever | |
| shown.</p> | |
| <p>The normal callout output, showing the callout number or pattern offset (as | |
| described above) is suppressed if the <code>callout_no_where</code> modifier is set.</p> | |
| <p>When using the interpretive matching function <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> without JIT, | |
| setting the <code>callout_extra</code> modifier causes additional output from | |
| <code>pcre2test</code>'s callout function to be generated. For the first callout in a | |
| match attempt at a new starting position in the subject, "New match attempt" is | |
| output. If there has been a backtrack since the last callout (or start of | |
| matching if this is the first callout), "Backtrack" is output, followed by "No | |
| other matching paths" if the backtrack ended the previous match attempt. For | |
| example:</p> | |
| <div class="literal-block"><pre> re> /(a+)b/auto_callout,no_start_optimize,no_auto_possess | |
| data> aac\=callout_extra | |
| New match attempt | |
| --->aac | |
| +0 ^ ( | |
| +1 ^ a+ | |
| +3 ^ ^ ) | |
| +4 ^ ^ b | |
| Backtrack | |
| --->aac | |
| +3 ^^ ) | |
| +4 ^^ b | |
| Backtrack | |
| No other matching paths | |
| New match attempt | |
| --->aac | |
| +0 ^ ( | |
| +1 ^ a+ | |
| +3 ^^ ) | |
| +4 ^^ b | |
| Backtrack | |
| No other matching paths | |
| New match attempt | |
| --->aac | |
| +0 ^ ( | |
| +1 ^ a+ | |
| Backtrack | |
| No other matching paths | |
| New match attempt | |
| --->aac | |
| +0 ^ ( | |
| +1 ^ a+ | |
| No match</pre></div> | |
| <p>Notice that various optimizations must be turned off if you want all possible | |
| matching paths to be scanned. If <code>no_start_optimize</code> is not used, there is | |
| an immediate "no match", without any callouts, because the starting | |
| optimization fails to find "b" in the subject, which it knows must be present | |
| for any match. If <code>no_auto_possess</code> is not used, the <code class="regex rouge"><span class="pcre2-semantic">a+</span></code> item is turned | |
| into <code class="regex rouge"><span class="pcre2-semantic">a++</span></code>, which reduces the number of backtracks.</p> | |
| <p>The <code>callout_extra</code> modifier has no effect if used with the DFA matching | |
| function, or with JIT.</p></section> | |
| <section class="doc-section level-2"><h3 id="_return_values_from_callouts">Return values from callouts</h3><p>The default return from the callout function is zero, which allows matching to | |
| continue. The <code>callout_fail</code> modifier can be given one or two numbers. If | |
| there is only one number, 1 is returned instead of 0 (causing matching to | |
| backtrack) when a callout of that number is reached. If two numbers (<n>:<m>) | |
| are given, 1 is returned when callout <n> is reached and there have been at | |
| least <m> callouts. The <code>callout_error</code> modifier is similar, except that | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_ERROR_CALLOUT</span></code> is returned, causing the entire matching process to be | |
| aborted. If both these modifiers are set for the same callout number, | |
| <code>callout_error</code> takes precedence. Note that callouts with string arguments | |
| are always given the number zero.</p> | |
| <p>The <code>callout_data</code> modifier can be given an unsigned or a negative number. | |
| This is set as the "user data" that is passed to the matching function, and | |
| passed back when the callout function is invoked. Any value other than zero is | |
| used as a return from <code>pcre2test</code>'s callout function.</p> | |
| <p>Inserting callouts can be helpful when using <code>pcre2test</code> to check | |
| complicated regular expressions. For further information about callouts, see | |
| the | |
| <a href="./pcre2callout.html"><code>pcre2callout</code></a> | |
| documentation.</p></section></section> | |
| <section class="doc-section level-1"><h2 id="_non_printing_characters">Non-printing characters</h2><p>When <code>pcre2test</code> is outputting text in the compiled version of a pattern, | |
| bytes other than 32-126 are always treated as non-printing characters and are | |
| therefore shown as hex escapes.</p> | |
| <p>When <code>pcre2test</code> is outputting text that is a matched part of a subject | |
| string, it behaves in the same way, unless a different locale has been set for | |
| the pattern (using the <code>locale</code> modifier). In this case, the | |
| <code class="c rouge" data-lang="c"><span class="nf">isprint</span><span class="p">()</span></code> function is used to distinguish printing and non-printing | |
| characters.</p></section> | |
| <section class="doc-section level-1"><h2 id="saving-restoring-patterns">Saving and restoring compiled patterns</h2><p>It is possible to save compiled patterns on disc or elsewhere, and reload them | |
| later, subject to a number of restrictions. JIT data cannot be saved. The host | |
| on which the patterns are reloaded must be running the same version of PCRE2, | |
| with the same code unit width, and must also have the same endianness, pointer | |
| width and <code class="type pcre2-api rouge"><span class="kt">PCRE2_SIZE</span></code> type. Before compiled patterns can be saved they must be | |
| serialized, that is, converted to a stream of bytes. A single byte stream may | |
| contain any number of compiled patterns, but they must all use the same | |
| character tables. A single copy of the tables is included in the byte stream | |
| (its size is 1,088 bytes).</p> | |
| <p>The functions whose names begin with <code class="c rouge" data-lang="c"><span class="kt">pcre2_serialize_</span></code> are used | |
| for serializing and de-serializing. They are described in the | |
| <a href="./pcre2serialize.html"><code>pcre2serialize</code></a> | |
| documentation. In this section we describe the features of <code>pcre2test</code> that | |
| can be used to test these functions.</p> | |
| <p>Note that "serialization" in PCRE2 does not convert compiled patterns to an | |
| abstract format like Java or .NET. It just makes a reloadable byte code stream. | |
| Hence the restrictions on reloading mentioned above.</p> | |
| <p>In <code>pcre2test</code>, when a pattern with <code>push</code> modifier is successfully | |
| compiled, it is pushed onto a stack of compiled patterns, and <code>pcre2test</code> | |
| expects the next line to contain a new pattern (or command) instead of a | |
| subject line. By contrast, the <code>pushcopy</code> modifier causes a copy of the | |
| compiled pattern to be stacked, leaving the original available for immediate | |
| matching. By using <code>push</code> and/or <code>pushcopy</code>, a number of patterns can | |
| be compiled and retained. These modifiers are incompatible with <code>posix</code>, | |
| and control modifiers that act at match time are ignored (with a message) for | |
| the stacked patterns. The <code>jitverify</code> modifier applies only at compile | |
| time.</p> | |
| <p>The command</p> | |
| <div class="literal-block"><pre>#save <filename></pre></div> | |
| <p>causes all the stacked patterns to be serialized and the result written to the | |
| named file. Afterwards, all the stacked patterns are freed. The command</p> | |
| <div class="literal-block"><pre>#load <filename></pre></div> | |
| <p>reads the data in the file, and then arranges for it to be de-serialized, with | |
| the resulting compiled patterns added to the pattern stack. The pattern on the | |
| top of the stack can be retrieved by the #pop command, which must be followed | |
| by lines of subjects that are to be matched with the pattern, terminated as | |
| usual by an empty line or end of file. This command may be followed by a | |
| modifier list containing only | |
| control modifiers | |
| that act after a pattern has been compiled. In particular, <code>hex</code>, | |
| <code>posix</code>, <code>posix_nosub</code>, <code>push</code>, and <code>pushcopy</code> are not allowed, | |
| nor are any | |
| option-setting modifiers. | |
| The JIT modifiers are, however permitted. Here is an example that saves and | |
| reloads two patterns.</p> | |
| <div class="literal-block"><pre>/abc/push | |
| /xyz/push | |
| #save tempfile | |
| #load tempfile | |
| #pop info | |
| xyz</pre></div> | |
| <div class="literal-block"><pre>#pop jit,bincode | |
| abc</pre></div> | |
| <p>If <code>jitverify</code> is used with #pop, it does not automatically imply | |
| <code>jit</code>, which is different behaviour from when it is used on a pattern.</p> | |
| <p>The #popcopy command is analogous to the <code>pushcopy</code> modifier in that it | |
| makes current a copy of the topmost stack pattern, leaving the original still | |
| on the stack.</p></section> | |
| <section class="doc-section level-1"><h2 id="_see_also">See also</h2><p><a href="./pcre2.html"><code>pcre2</code></a>, <a href="./pcre2api.html"><code>pcre2api</code></a>, <a href="./pcre2callout.html"><code>pcre2callout</code></a>, | |
| <a href="./pcre2jit.html"><code>pcre2jit</code></a>, <a href="./pcre2matching.html"><code>pcre2matching</code></a>, <a href="./pcre2partial.html"><code>pcre2partial</code></a>, | |
| <a href="./pcre2pattern.html"><code>pcre2pattern</code></a>, <a href="./pcre2serialize.html"><code>pcre2serialize</code></a>.</p> | |
| <h2 id="_author" class="discrete">Author</h2> | |
| <p>Philip Hazel<br> | |
| Retired from University Computing Service<br> | |
| Cambridge, England.</p> | |
| <h2 id="_revision" class="discrete">Revision</h2> | |
| <p>Last updated: 22 August 2026<br> | |
| Copyright © 1997-2024 University of Cambridge.</p></section></article></div></main><footer class="offline-footer"></footer></body></html> |