| <!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="Specification of the regular expressions supported by PCRE2"><title>pcre2pattern(3)</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>pcre2pattern(3)</h1><p class="document-meta">PCRE2 10.50-DEV manual; updated <time datetime="2025-10-25">25 Oct 2025</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="#_pcre2_regular_expression_details" title="PCRE2 regular expression details">PCRE2 regular expression details</a></li><li><a href="#_ebcdic_character_codes" title="EBCDIC character codes">EBCDIC character codes</a></li><li><a href="#_special_start_of_pattern_items" title="Special start-of-pattern items">Special start-of-pattern items</a><ol class="toc-list level-2"><li><a href="#_utf_support" title="UTF support">UTF support</a></li><li><a href="#_unicode_property_support" title="Unicode property support">Unicode property support</a></li><li><a href="#_locking_out_empty_string_matching" title="Locking out empty string matching">Locking out empty string matching</a></li><li><a href="#_disabling_auto_possessification" title="Disabling auto-possessification">Disabling auto-possessification</a></li><li><a href="#_disabling_start_up_optimizations" title="Disabling start-up optimizations">Disabling start-up optimizations</a></li><li><a href="#_disabling_automatic_anchoring" title="Disabling automatic anchoring">Disabling automatic anchoring</a></li><li><a href="#_disabling_jit_compilation" title="Disabling JIT compilation">Disabling JIT compilation</a></li><li><a href="#_setting_match_resource_limits" title="Setting match resource limits">Setting match resource limits</a></li><li><a href="#newline-conventions" title="Newline conventions">Newline conventions</a></li><li><a href="#specifying-r-matches" title="Specifying what \R matches">Specifying what <code class="regex rouge"><span class="pcre2-semantic">\R</span></code> matches</a></li></ol></li><li><a href="#_characters_and_metacharacters" title="Characters and metacharacters">Characters and metacharacters</a></li><li><a href="#_backslash" title="Backslash">Backslash</a><ol class="toc-list level-2"><li><a href="#non-printing-characters" title="Non-printing characters">Non-printing characters</a></li><li><a href="#_octal_escapes_and_back_references" title="Octal escapes and back references">Octal escapes and back references</a></li><li><a href="#_perl_rules_for_non_class_backslash_1_9" title="Perl rules for non-class backslash 1-9">Perl rules for non-class backslash 1-9</a></li><li><a href="#_python_rules_for_non_class_backslash_1_9" title="Python rules for non-class backslash 1-9">Python rules for non-class backslash 1-9</a></li><li><a href="#_constraints_on_character_values" title="Constraints on character values">Constraints on character values</a></li><li><a href="#_escape_sequences_in_character_classes" title="Escape sequences in character classes">Escape sequences in character classes</a></li><li><a href="#_unsupported_escape_sequences" title="Unsupported escape sequences">Unsupported escape sequences</a></li><li><a href="#_absolute_and_relative_backreferences" title="Absolute and relative backreferences">Absolute and relative backreferences</a></li><li><a href="#_absolute_and_relative_subroutine_calls" title="Absolute and relative subroutine calls">Absolute and relative subroutine calls</a></li><li><a href="#generic-character-types" title="Generic character types">Generic character types</a></li><li><a href="#newline-sequences" title="Newline sequences">Newline sequences</a></li><li><a href="#_unicode_character_properties" title="Unicode character properties">Unicode character properties</a></li><li><a href="#_script_properties_for_p_and_p" title="Script properties for \p and \P">Script properties for <code class="regex rouge"><span class="pcre2-semantic">\p</span></code> and <code class="regex rouge"><span class="pcre2-semantic">\P</span></code></a></li><li><a href="#_the_general_category_property_for_p_and_p" title="The general category property for \p and \P">The general category property for <code class="regex rouge"><span class="pcre2-semantic">\p</span></code> and <code class="regex rouge"><span class="pcre2-semantic">\P</span></code></a></li><li><a href="#_binary_yesno_properties_for_p_and_p" title="Binary (yes/no) properties for \p and \P">Binary (yes/no) properties for <code class="regex rouge"><span class="pcre2-semantic">\p</span></code> and <code class="regex rouge"><span class="pcre2-semantic">\P</span></code></a></li><li><a href="#_the_bidi_class_property_for_p_and_p" title="The Bidi_Class property for \p and \P">The Bidi_Class property for <code class="regex rouge"><span class="pcre2-semantic">\p</span></code> and <code class="regex rouge"><span class="pcre2-semantic">\P</span></code></a></li><li><a href="#_extended_grapheme_clusters" title="Extended grapheme clusters">Extended grapheme clusters</a></li><li><a href="#_pcre2s_additional_properties" title="PCRE2’s additional properties">PCRE2’s additional properties</a></li><li><a href="#_resetting_the_match_start" title="Resetting the match start">Resetting the match start</a></li><li><a href="#_simple_assertions" title="Simple assertions">Simple assertions</a></li></ol></li><li><a href="#circumflex-and-dollar" title="Circumflex and dollar">Circumflex and dollar</a></li><li><a href="#_full_stop_period_dot_and_n" title="Full stop (period, dot) and \n">Full stop (period, dot) and <code class="regex rouge"><span class="pcre2-semantic">\n</span></code></a></li><li><a href="#_matching_a_single_code_unit" title="Matching a single code unit">Matching a single code unit</a></li><li><a href="#_square_brackets_and_character_classes" title="Square brackets and character classes">Square brackets and character classes</a></li><li><a href="#_perl_extended_character_classes" title="Perl extended character classes">Perl extended character classes</a></li><li><a href="#_uts18_extended_character_classes" title="UTS#18 extended character classes">UTS#18 extended character classes</a></li><li><a href="#_posix_character_classes" title="POSIX character classes">POSIX character classes</a></li><li><a href="#_compatibility_feature_for_word_boundaries" title="Compatibility feature for word boundaries">Compatibility feature for word boundaries</a></li><li><a href="#_vertical_bar_pipe" title="Vertical bar (pipe)">Vertical bar (pipe)</a></li><li><a href="#internal-option-setting" title="Internal option setting">Internal option setting</a></li><li><a href="#groups" title="Groups">Groups</a></li><li><a href="#duplicate-group-numbers" title="Duplicate group numbers">Duplicate group numbers</a></li><li><a href="#named-capture-groups" title="Named capture groups">Named capture groups</a></li><li><a href="#_repetition" title="Repetition">Repetition</a></li><li><a href="#_atomic_grouping_and_possessive_quantifiers" title="Atomic grouping and possessive quantifiers">Atomic grouping and possessive quantifiers</a></li><li><a href="#_backreferences" title="Backreferences">Backreferences</a><ol class="toc-list level-2"><li><a href="#_recursive_backreferences" title="Recursive backreferences">Recursive backreferences</a></li></ol></li><li><a href="#_assertions" title="Assertions">Assertions</a><ol class="toc-list level-2"><li><a href="#_alphabetic_assertion_names" title="Alphabetic assertion names">Alphabetic assertion names</a></li><li><a href="#_lookahead_assertions" title="Lookahead assertions">Lookahead assertions</a></li><li><a href="#_lookbehind_assertions" title="Lookbehind assertions">Lookbehind assertions</a></li><li><a href="#_using_multiple_assertions" title="Using multiple assertions">Using multiple assertions</a></li></ol></li><li><a href="#non-atomic-assertions" title="Non-atomic assertions">Non-atomic assertions</a></li><li><a href="#scan-substring-assertions" title="Scan substring assertions">Scan substring assertions</a></li><li><a href="#_script_runs" title="Script runs">Script runs</a></li><li><a href="#conditional-groups" title="Conditional groups">Conditional groups</a><ol class="toc-list level-2"><li><a href="#_checking_for_a_used_capture_group_by_number" title="Checking for a used capture group by number">Checking for a used capture group by number</a></li><li><a href="#_checking_for_a_used_capture_group_by_name" title="Checking for a used capture group by name">Checking for a used capture group by name</a></li><li><a href="#checking-pattern-recursion" title="Checking for pattern recursion">Checking for pattern recursion</a></li><li><a href="#defining-capture-groups" title="Defining capture groups for use by reference only">Defining capture groups for use by reference only</a></li><li><a href="#_checking_the_pcre2_version" title="Checking the PCRE2 version">Checking the PCRE2 version</a></li><li><a href="#_assertion_conditions" title="Assertion conditions">Assertion conditions</a></li></ol></li><li><a href="#_comments" title="Comments">Comments</a></li><li><a href="#recursive-patterns" title="Recursive patterns">Recursive patterns</a><ol class="toc-list level-2"><li><a href="#_differences_in_recursion_processing_between_pcre2_and_perl" title="Differences in recursion processing between PCRE2 and Perl">Differences in recursion processing between PCRE2 and Perl</a></li><li><a href="#groups-as-subroutines" title="Groups as subroutines">Groups as subroutines</a></li><li><a href="#_recursion_and_subroutines_with_returned_capture_groups" title="Recursion and subroutines with returned capture groups">Recursion and subroutines with returned capture groups</a></li><li><a href="#_oniguruma_subroutine_syntax" title="Oniguruma subroutine syntax">Oniguruma subroutine syntax</a></li></ol></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></ol></li><li><a href="#_backtracking_control" title="Backtracking control">Backtracking control</a><ol class="toc-list level-2"><li><a href="#_optimizations_that_affect_backtracking_verbs" title="Optimizations that affect backtracking verbs">Optimizations that affect backtracking verbs</a></li><li><a href="#_verbs_that_act_immediately" title="Verbs that act immediately">Verbs that act immediately</a></li><li><a href="#_recording_which_path_was_taken" title="Recording which path was taken">Recording which path was taken</a></li><li><a href="#_verbs_that_act_after_backtracking" title="Verbs that act after backtracking">Verbs that act after backtracking</a></li><li><a href="#_more_than_one_backtracking_verb" title="More than one backtracking verb">More than one backtracking verb</a></li><li><a href="#_backtracking_verbs_in_repeated_groups" title="Backtracking verbs in repeated groups">Backtracking verbs in repeated groups</a></li><li><a href="#_backtracking_verbs_in_assertions" title="Backtracking verbs in assertions">Backtracking verbs in assertions</a></li><li><a href="#backtracking-verbs-in-subroutines" title="Backtracking verbs in subroutines">Backtracking verbs in subroutines</a></li></ol></li><li><a href="#ebcdic-environments" title="EBCDIC environments">EBCDIC environments</a><ol class="toc-list level-2"><li><a href="#_escape_sequences" title="Escape sequences">Escape sequences</a></li><li><a href="#_character_classes" title="Character classes">Character classes</a></li></ol></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="_pcre2_regular_expression_details">PCRE2 regular expression details</h2><p>The syntax and semantics of the regular expressions that are supported by PCRE2 | |
| are described in detail below. There is a quick-reference syntax summary in the | |
| <a href="./pcre2syntax.html"><code>pcre2syntax</code></a> | |
| page. PCRE2 tries to match Perl syntax and semantics as closely as it can. | |
| PCRE2 also supports some alternative regular expression syntax that does not | |
| conflict with the Perl syntax in order to provide some compatibility with | |
| regular expressions in Python, .NET, and Oniguruma. There are in addition some | |
| options that enable alternative syntax and semantics that are not the same as | |
| in Perl.</p> | |
| <p>Perl’s regular expressions are described in its own documentation, and regular | |
| expressions in general are covered in a number of books, some of which have | |
| copious examples. Jeffrey Friedl’s "Mastering Regular Expressions", published | |
| by O’Reilly, covers regular expressions in great detail. This description of | |
| PCRE2’s regular expressions is intended as reference material.</p> | |
| <p>This document discusses the regular expression patterns that are supported by | |
| PCRE2 when its main matching function, <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code>, is used. PCRE2 also | |
| has an alternative matching function, <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code>, which matches | |
| using a different algorithm that is not Perl-compatible. Some of the features | |
| discussed below are not available when DFA matching is used. The advantages and | |
| disadvantages of the alternative function, and how it differs from the normal | |
| function, are discussed in the | |
| <a href="./pcre2matching.html"><code>pcre2matching</code></a> | |
| page.</p></section> | |
| <section class="doc-section level-1"><h2 id="_ebcdic_character_codes">EBCDIC character codes</h2><p>Most computers use ASCII or Unicode for encoding characters, and PCRE2 assumes | |
| this by default. However, it can be compiled to run in an environment that uses | |
| the EBCDIC code, which is the case for some IBM mainframe operating systems. In | |
| the sections below, character code values are ASCII or Unicode; in an EBCDIC | |
| environment these characters may have different code values, and there are no | |
| code points greater than 255. Differences in behaviour when PCRE2 is running in | |
| an EBCDIC environment are described in the section <a href="#ebcdic-environments">EBCDIC environments</a> | |
| below, which you can ignore unless you really are in an EBCDIC environment.</p></section> | |
| <section class="doc-section level-1"><h2 id="_special_start_of_pattern_items">Special start-of-pattern items</h2><p>A number of options that can be passed to <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code> can also be set | |
| by special items at the start of a pattern. These are not Perl-compatible, but | |
| are provided to make these options accessible to pattern writers who are not | |
| able to change the program that processes the pattern. Any number of these | |
| items may appear, but they must all be together right at the start of the | |
| pattern string, and the letters must be in upper case.</p> | |
| <section class="doc-section level-2"><h3 id="_utf_support">UTF support</h3><p>In the 8-bit and 16-bit PCRE2 libraries, characters may be coded either as | |
| single code units, or as multiple UTF-8 or UTF-16 code units. UTF-32 can be | |
| specified for the 32-bit library, in which case it constrains the character | |
| values to valid Unicode code points. To process UTF strings, PCRE2 must be | |
| built to include Unicode support (which is the default). When using UTF strings | |
| you must either call the compiling function with one or both of the <code class="constant pcre2-api rouge"><span class="no">PCRE2_UTF</span></code> | |
| or <code class="constant pcre2-api rouge"><span class="no">PCRE2_MATCH_INVALID_UTF</span></code> options, or the pattern must start with the special | |
| sequence <code class="regex rouge"><span class="pcre2-semantic">(*UTF)</span></code>, which is equivalent to setting the relevant <code class="constant pcre2-api rouge"><span class="no">PCRE2_UTF</span></code>. How | |
| setting a UTF mode affects pattern matching is mentioned in several places | |
| below. There is also a summary of features in the | |
| <a href="./pcre2unicode.html"><code>pcre2unicode</code></a> | |
| page.</p> | |
| <p>Some applications that allow their users to supply patterns may wish to | |
| restrict them to non-UTF data for security reasons. If the <code class="constant pcre2-api rouge"><span class="no">PCRE2_NEVER_UTF</span></code> | |
| option is passed to <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code>, <code class="regex rouge"><span class="pcre2-semantic">(*UTF)</span></code> is not allowed, and its | |
| appearance in a pattern causes an error.</p></section> | |
| <section class="doc-section level-2"><h3 id="_unicode_property_support">Unicode property support</h3><p>Another special sequence that may appear at the start of a pattern is <code class="regex rouge"><span class="pcre2-semantic">(*UCP)</span></code>. | |
| This has the same effect as setting the <code class="constant pcre2-api rouge"><span class="no">PCRE2_UCP</span></code> option: it causes sequences | |
| such as <code class="regex rouge"><span class="pcre2-semantic">\d</span></code> and <code class="regex rouge"><span class="pcre2-semantic">\w</span></code> to use Unicode properties to determine character types, | |
| instead of recognizing only characters with codes less than 256 via a lookup | |
| table. If also causes upper/lower casing operations to use Unicode properties | |
| for characters with code points greater than 127, even when UTF is not set. | |
| These behaviours can be changed within the pattern; see the section | |
| <a href="#internal-option-setting">Internal option setting</a> | |
| below.</p> | |
| <p>Some applications that allow their users to supply patterns may wish to | |
| restrict them for security reasons. If the <code class="constant pcre2-api rouge"><span class="no">PCRE2_NEVER_UCP</span></code> option is passed to | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code>, <code class="regex rouge"><span class="pcre2-semantic">(*UCP)</span></code> is not allowed, and its appearance in a pattern | |
| causes an error.</p></section> | |
| <section class="doc-section level-2"><h3 id="_locking_out_empty_string_matching">Locking out empty string matching</h3><p>Starting a pattern with <code class="regex rouge"><span class="pcre2-semantic">(*NOTEMPTY)</span></code> or <code class="regex rouge"><span class="pcre2-semantic">(*NOTEMPTY_ATSTART)</span></code> has the same effect | |
| as passing the <code class="constant pcre2-api rouge"><span class="no">PCRE2_NOTEMPTY</span></code> or <code class="constant pcre2-api rouge"><span class="no">PCRE2_NOTEMPTY_ATSTART</span></code> option to whichever | |
| matching function is subsequently called to match the pattern. These options | |
| lock out the matching of empty strings, either entirely, or only at the start | |
| of the subject.</p></section> | |
| <section class="doc-section level-2"><h3 id="_disabling_auto_possessification">Disabling auto-possessification</h3><p>If a pattern starts with <code class="regex rouge"><span class="pcre2-semantic">(*NO_AUTO_POSSESS)</span></code>, it has the same effect as setting | |
| the <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_AUTO_POSSESS</span></code> option, or calling <code class="function pcre2-api rouge"><span class="nf">pcre2_set_optimize()</span></code> with | |
| a <code class="constant pcre2-api rouge"><span class="no">PCRE2_AUTO_POSSESS_OFF</span></code> directive. This stops PCRE2 from making quantifiers | |
| possessive when what follows cannot match the repeated item. For example, by | |
| default <code class="regex rouge"><span class="pcre2-semantic">a+b</span></code> is treated as <code class="regex rouge"><span class="pcre2-semantic">a++b</span></code>. For more details, see the | |
| <a href="./pcre2api.html"><code>pcre2api</code></a> | |
| documentation.</p></section> | |
| <section class="doc-section level-2"><h3 id="_disabling_start_up_optimizations">Disabling start-up optimizations</h3><p>If a pattern starts with <code class="regex rouge"><span class="pcre2-semantic">(*NO_START_OPT)</span></code>, it has the same effect as setting the | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_START_OPTIMIZE</span></code> option, or calling <code class="function pcre2-api rouge"><span class="nf">pcre2_set_optimize()</span></code> with | |
| a <code class="constant pcre2-api rouge"><span class="no">PCRE2_START_OPTIMIZE_OFF</span></code> directive. This disables several optimizations for | |
| quickly reaching "no match" results. For more details, see the | |
| <a href="./pcre2api.html"><code>pcre2api</code></a> | |
| documentation.</p></section> | |
| <section class="doc-section level-2"><h3 id="_disabling_automatic_anchoring">Disabling automatic anchoring</h3><p>If a pattern starts with <code class="regex rouge"><span class="pcre2-semantic">(*NO_DOTSTAR_ANCHOR)</span></code>, it has the same effect as | |
| setting the <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_DOTSTAR_ANCHOR</span></code> option, or | |
| calling <code class="function pcre2-api rouge"><span class="nf">pcre2_set_optimize()</span></code> with a <code class="constant pcre2-api rouge"><span class="no">PCRE2_DOTSTAR_ANCHOR_OFF</span></code> directive. | |
| This disables optimizations that apply to patterns whose top-level branches | |
| all start with <code class="regex rouge"><span class="pcre2-semantic">.*</span></code> (match any number of arbitrary characters). For more details, | |
| see the | |
| <a href="./pcre2api.html"><code>pcre2api</code></a> | |
| documentation.</p></section> | |
| <section class="doc-section level-2"><h3 id="_disabling_jit_compilation">Disabling JIT compilation</h3><p>If a pattern that starts with <code class="regex rouge"><span class="pcre2-semantic">(*NO_JIT)</span></code> is successfully compiled, an attempt by | |
| the application to apply the JIT optimization by calling | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_jit_compile()</span></code> is ignored.</p></section> | |
| <section class="doc-section level-2"><h3 id="_setting_match_resource_limits">Setting match resource limits</h3><p>The <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> function contains a counter that is incremented every | |
| time it goes round its main loop. The caller of <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> can set a | |
| limit on this counter, which therefore limits the amount of computing resource | |
| used for a match. The maximum depth of nested backtracking can also be limited; | |
| this indirectly restricts the amount of heap memory that is used, but there is | |
| also an explicit memory limit that can be set.</p> | |
| <p>These facilities are provided to catch runaway matches that are provoked by | |
| patterns with huge matching trees. A common example is a pattern with nested | |
| unlimited repeats applied to a long string that does not match. When one of | |
| these limits is reached, <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> gives an error return. The limits | |
| can also be set by items at the start of the pattern of the form</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(*LIMIT_HEAP=<em>d</em>) | |
| (*LIMIT_MATCH=<em>d</em>) | |
| (*LIMIT_DEPTH=<em>d</em>)</span></code></pre></div> | |
| <p>where <em>d</em> is any number of decimal digits. However, the value of the setting must | |
| be less than the value set (or defaulted) by the caller of <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> | |
| for it to have any effect. In other words, the pattern writer can lower the | |
| limits set by the programmer, but not raise them. If there is more than one | |
| setting of one of these limits, the lower value is used. The heap limit is | |
| specified in kibibytes (units of 1024 bytes).</p> | |
| <p>Prior to release 10.30, LIMIT_DEPTH was called LIMIT_RECURSION. This name is | |
| still recognized for backwards compatibility.</p> | |
| <p>The heap limit applies only when the <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> interpreters are used for matching. It does not apply | |
| to JIT. The match limit is used (but in a different way) when JIT is being | |
| used, or when <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code> is called, to limit computing resource | |
| usage by those matching functions. The depth limit is ignored by JIT but is | |
| relevant for DFA matching, which uses function recursion for recursions within | |
| the pattern and for lookaround assertions and atomic groups. In this case, the | |
| depth limit controls the depth of such recursion.</p></section> | |
| <section class="doc-section level-2"><h3 id="newline-conventions">Newline conventions</h3><p>PCRE2 supports six different conventions for indicating line breaks in | |
| strings: a single CR (carriage return) character, a single LF (linefeed) | |
| character, the two-character sequence CRLF, any of the three preceding, any | |
| Unicode newline sequence, or the NUL character (binary zero). The | |
| <a href="./pcre2api.html"><code>pcre2api</code></a> | |
| page has | |
| further discussion | |
| about newlines, and shows how to set the newline convention when calling | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code>.</p> | |
| <p>It is also possible to specify a newline convention by starting a pattern | |
| string with one of the following sequences:</p> | |
| <dl class="compact" style="--tab-width: 6"><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">(*CR)</span></code></span></dt><dd>Carriage return</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">(*LF)</span></code></span></dt><dd>Linefeed</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">(*CRLF)</span></code></span></dt><dd>Carriage return, followed by linefeed</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">(*ANYCRLF)</span></code></span></dt><dd>Any of the three above</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">(*ANY)</span></code></span></dt><dd>All Unicode newline sequences</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">(*NUL)</span></code></span></dt><dd>The NUL character (binary zero)</dd></div></dl> | |
| <p>These override the default and the options given to the compiling function. For | |
| example, on a Unix system where LF is the default newline sequence, the pattern</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(*CR)a.b</span></code></pre></div> | |
| <p>changes the convention to CR. That pattern matches <code class="subject rouge"><span class="pcre2-semantic">a\nb</span></code> because LF is no | |
| longer a newline. If more than one of these settings is present, the last one | |
| is used.</p> | |
| <p>The newline convention affects where the circumflex and dollar assertions are | |
| true. It also affects the interpretation of the dot metacharacter when | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_DOTALL</span></code> is not set, and the behaviour of <code class="regex rouge"><span class="pcre2-semantic">\N</span></code> when not followed by an | |
| opening brace. However, it does not affect what the <code class="regex rouge"><span class="pcre2-semantic">\R</span></code> escape sequence | |
| matches. By default, this is any Unicode newline sequence, for Perl | |
| compatibility. However, this can be changed; see the section | |
| <a href="#specifying-r-matches">Specifying what <code class="regex rouge"><span class="pcre2-semantic">\R</span></code> matches</a> and the | |
| description of <code class="regex rouge"><span class="pcre2-semantic">\R</span></code> in the section <a href="#newline-sequences">Newline sequences</a> | |
| below. A change of <code class="regex rouge"><span class="pcre2-semantic">\R</span></code> setting can be combined with a change of newline | |
| convention.</p></section> | |
| <section class="doc-section level-2"><h3 id="specifying-r-matches">Specifying what <code class="regex rouge"><span class="pcre2-semantic">\R</span></code> matches</h3><p>It is possible to restrict <code class="regex rouge"><span class="pcre2-semantic">\R</span></code> to match only CR, LF, or CRLF (instead of the | |
| complete set of Unicode line endings) by setting the option <code class="constant pcre2-api rouge"><span class="no">PCRE2_BSR_ANYCRLF</span></code> | |
| at compile time. This effect can also be achieved by starting a pattern with | |
| <code class="regex rouge"><span class="pcre2-semantic">(*BSR_ANYCRLF)</span></code>. For completeness, <code class="regex rouge"><span class="pcre2-semantic">(*BSR_UNICODE)</span></code> is also recognized, | |
| corresponding to <code class="constant pcre2-api rouge"><span class="no">PCRE2_BSR_UNICODE</span></code>.</p></section></section> | |
| <section class="doc-section level-1"><h2 id="_characters_and_metacharacters">Characters and metacharacters</h2><p>A regular expression is a pattern that is matched against a subject string from | |
| left to right. Most characters stand for themselves in a pattern, and match the | |
| corresponding characters in the subject. As a trivial example, the pattern</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">The quick brown fox</span></code></pre></div> | |
| <p>matches a portion of a subject string that is identical to itself. When | |
| caseless matching is specified (the <code class="constant pcre2-api rouge"><span class="no">PCRE2_CASELESS</span></code> option or <code class="regex rouge"><span class="pcre2-semantic">(?i)</span></code> within the | |
| pattern), letters are matched independently of case. Note that there are two | |
| ASCII characters, K and S, that, in addition to their lower case ASCII | |
| equivalents, are case-equivalent with Unicode <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-1"><code class="character pcre2-api rouge"><span class="sc">U+212A</span></code><span class="character-card" id="pcre2-character-1" role="tooltip" aria-label="KELVIN SIGN (U+212A)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character="K"></span><span class="character-name" data-character-name="KELVIN SIGN"></span><span class="character-codepoint" data-codepoint="U+212A"></span></span></span> (Kelvin sign) and <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-2"><code class="character pcre2-api rouge"><span class="sc">U+017F</span></code><span class="character-card" id="pcre2-character-2" role="tooltip" aria-label="LATIN SMALL LETTER LONG S (U+017F)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character="ſ"></span><span class="character-name" data-character-name="LATIN SMALL LETTER LONG S"></span><span class="character-codepoint" data-codepoint="U+017F"></span></span></span> | |
| (long S) respectively when either <code class="constant pcre2-api rouge"><span class="no">PCRE2_UTF</span></code> or <code class="constant pcre2-api rouge"><span class="no">PCRE2_UCP</span></code> is set, unless the | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_CASELESS_RESTRICT</span></code> option is in force (either passed to | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code> or set by <code class="regex rouge"><span class="pcre2-semantic">(*CASELESS_RESTRICT)</span></code> or <code class="regex rouge"><span class="pcre2-semantic">(?r)</span></code> within the | |
| pattern). If the <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_TURKISH_CASING</span></code> option is in force (either passed | |
| to <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code> or set by <code class="regex rouge"><span class="pcre2-semantic">(*TURKISH_CASING)</span></code> within the pattern), then | |
| the 'i' letters are matched according to Turkish and Azeri languages.</p> | |
| <p>The power of regular expressions comes from the ability to include wild cards, | |
| character classes, alternatives, and repetitions in the pattern. These are | |
| encoded in the pattern by the use of <em>metacharacters</em>, which do not stand | |
| for themselves but instead are interpreted in some special way.</p> | |
| <p>There are two different sets of metacharacters: those that are recognized | |
| anywhere in the pattern except within square brackets, and those that are | |
| recognized within square brackets. Outside square brackets, the metacharacters | |
| are as follows:</p> | |
| <dl class="compact" style="--tab-width: 4"><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\</span></code> </span></dt><dd>general escape character with several uses</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">^</span></code> </span></dt><dd>assert start of string (or line, in multiline mode)</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">$</span></code> </span></dt><dd>assert end of string (or line, in multiline mode)</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">.</span></code> </span></dt><dd>match any character except newline (by default)</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">[</span></code> </span></dt><dd>start character class definition</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">|</span></code> </span></dt><dd>start of alternative branch</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">(</span></code> </span></dt><dd>start group or control verb</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">)</span></code> </span></dt><dd>end group or control verb</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">*</span></code> </span></dt><dd>0 or more quantifier</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">+</span></code> </span></dt><dd>1 or more quantifier; also "possessive quantifier"</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">?</span></code> </span></dt><dd>0 or 1 quantifier; also quantifier minimizer</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">{</span></code> </span></dt><dd>potential start of min/max quantifier</dd></div></dl> | |
| <p>Brace characters <code class="regex rouge"><span class="pcre2-semantic">{</span></code> and <code class="regex rouge"><span class="pcre2-semantic">}</span></code> are also used to enclose data for constructions such | |
| as <code class="regex rouge"><span class="pcre2-semantic">\g{2}</span></code> or <code class="regex rouge"><span class="pcre2-semantic">\k{<em>name</em>}</span></code>. In almost all uses of braces, space and/or horizontal | |
| tab characters that follow <code class="regex rouge"><span class="pcre2-semantic">{</span></code> or precede <code class="regex rouge"><span class="pcre2-semantic">}</span></code> are allowed and are ignored. In the | |
| case of quantifiers, they may also appear before or after the comma. The | |
| exception to this is <code class="regex rouge"><span class="pcre2-semantic">\u{...}</span></code> which is an ECMAScript compatibility feature | |
| that is recognized only when the <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ALT_BSUX</span></code> option is set. ECMAScript | |
| does not ignore such white space; it causes the item to be interpreted as | |
| literal.</p> | |
| <p>Part of a pattern that is in square brackets is called a "character class". In | |
| a character class the only metacharacters are:</p> | |
| <dl class="compact" style="--tab-width: 4"><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\</span></code></span></dt><dd>general escape character</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">^</span></code></span></dt><dd>negate the class, but only if the first character</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">-</span></code></span></dt><dd>indicates character range</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">[</span></code></span></dt><dd>POSIX character class (if followed by POSIX syntax)</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">]</span></code></span></dt><dd>terminates the character class</dd></div></dl> | |
| <p>If a pattern is compiled with the <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED</span></code> option, most white space in | |
| the pattern, other than in a character class, within a <code class="regex rouge"><span class="pcre2-semantic">\Q...\E</span></code> sequence, or | |
| between a <code class="regex rouge"><span class="pcre2-semantic">#</span></code> outside a character class and the next newline, inclusive, is | |
| ignored. An escaping backslash can be used to include a white space or a # | |
| character as part of the pattern. If the <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED_MORE</span></code> option is set, the | |
| same applies, but in addition unescaped space and horizontal tab characters are | |
| ignored inside a character class. Note: only these two characters are ignored, | |
| not the full set of pattern white space characters that are ignored outside a | |
| character class. Option settings can be changed within a pattern; see the | |
| section <a href="#internal-option-setting">Internal option setting</a> | |
| below.</p> | |
| <p>The following sections describe the use of each of the metacharacters.</p></section> | |
| <section class="doc-section level-1"><h2 id="_backslash">Backslash</h2><p>The backslash character has several uses. Firstly, if it is followed by a | |
| character that is not a digit or a letter, it takes away any special meaning | |
| that character may have. This use of backslash as an escape character applies | |
| both inside and outside character classes.</p> | |
| <p>For example, if you want to match a <code class="subject rouge"><span class="pcre2-semantic">*</span></code> character, you must write <code class="regex rouge"><span class="pcre2-semantic">\*</span></code> in the | |
| pattern. This escaping action applies whether or not the following character | |
| would otherwise be interpreted as a metacharacter, so it is always safe to | |
| precede a non-alphanumeric with backslash to specify that it stands for itself. | |
| In particular, if you want to match a backslash, you write <code class="regex rouge"><span class="pcre2-semantic">\\</span></code>.</p> | |
| <p>Only ASCII digits and letters have any special meaning after a backslash. All | |
| other characters (in particular, those whose code points are greater than 127) | |
| are treated as literals.</p> | |
| <p>If you want to treat all characters in a sequence as literals, you can do so by | |
| putting them between <code class="regex rouge"><span class="pcre2-semantic">\Q</span></code> and <code class="regex rouge"><span class="pcre2-semantic">\E</span></code>. Note that this includes white space even when | |
| the <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED</span></code> option is set so that most other white space is ignored. The | |
| behaviour is different from Perl in that $ and @ are handled as literals in | |
| <code class="regex rouge"><span class="pcre2-semantic">\Q...\E</span></code> sequences in PCRE2, whereas in Perl, $ and @ cause variable | |
| interpolation. Also, Perl does "double-quotish backslash interpolation" on any | |
| backslashes between <code class="regex rouge"><span class="pcre2-semantic">\Q</span></code> and <code class="regex rouge"><span class="pcre2-semantic">\E</span></code> which, its documentation says, "may lead to | |
| confusing results". PCRE2 treats a backslash between <code class="regex rouge"><span class="pcre2-semantic">\Q</span></code> and <code class="regex rouge"><span class="pcre2-semantic">\E</span></code> just like any | |
| other character. Note the following examples:</p> | |
| <div class="table-block"><table class="frame-all grid-all stretch"><colgroup><col style="width: 25%;"><col style="width: 25%;"><col style="width: 50%;"></colgroup><thead><tr><th class="halign-left valign-top">Pattern</th><th class="halign-left valign-top">PCRE2 matches</th><th class="halign-left valign-top">Perl matches</th></tr></thead><tbody><tr><td class="halign-left valign-top"><code class="regex rouge"><span class="pcre2-semantic">\Qabc$xyz\E</span></code></td><td class="halign-left valign-top"><code class="subject rouge"><span class="pcre2-semantic">abc$xyz</span></code></td><td class="halign-left valign-top"><code class="subject rouge"><span class="pcre2-semantic">abc</span></code> followed by the contents of <code>$xyz</code></td></tr><tr><td class="halign-left valign-top"><code class="regex rouge"><span class="pcre2-semantic">\Qabc\$xyz\E</span></code></td><td class="halign-left valign-top"><code class="subject rouge"><span class="pcre2-semantic">abc\$xyz</span></code></td><td class="halign-left valign-top"><code class="subject rouge"><span class="pcre2-semantic">abc\$xyz</span></code></td></tr><tr><td class="halign-left valign-top"><code class="regex rouge"><span class="pcre2-semantic">\Qabc\E\$\Qxyz\E</span></code></td><td class="halign-left valign-top"><code class="subject rouge"><span class="pcre2-semantic">abc$xyz</span></code></td><td class="halign-left valign-top"><code class="subject rouge"><span class="pcre2-semantic">abc$xyz</span></code></td></tr><tr><td class="halign-left valign-top"><code class="regex rouge"><span class="pcre2-semantic">\QA\B\E</span></code></td><td class="halign-left valign-top"><code class="subject rouge"><span class="pcre2-semantic">A\B</span></code></td><td class="halign-left valign-top"><code class="subject rouge"><span class="pcre2-semantic">A\B</span></code></td></tr><tr><td class="halign-left valign-top"><code class="regex rouge"><span class="pcre2-semantic">\Q\\E</span></code></td><td class="halign-left valign-top"><code class="subject rouge"><span class="pcre2-semantic">\</span></code></td><td class="halign-left valign-top"><code class="subject rouge"><span class="pcre2-semantic">\\E</span></code></td></tr></tbody></table></div> | |
| <p>The <code class="regex rouge"><span class="pcre2-semantic">\Q...\E</span></code> sequence is recognized both inside and outside character classes. | |
| An isolated <code class="regex rouge"><span class="pcre2-semantic">\E</span></code> that is not preceded by <code class="regex rouge"><span class="pcre2-semantic">\Q</span></code> is ignored. If <code class="regex rouge"><span class="pcre2-semantic">\Q</span></code> is not followed | |
| by <code class="regex rouge"><span class="pcre2-semantic">\E</span></code> later in the pattern, the literal interpretation continues to the end of | |
| the pattern (that is, <code class="regex rouge"><span class="pcre2-semantic">\E</span></code> is assumed at the end). If the isolated <code class="regex rouge"><span class="pcre2-semantic">\Q</span></code> is inside | |
| a character class, this causes an error, because the character class is then | |
| not terminated by a closing square bracket.</p> | |
| <p>Another difference from Perl is that any appearance of <code class="regex rouge"><span class="pcre2-semantic">\Q</span></code> or <code class="regex rouge"><span class="pcre2-semantic">\E</span></code> inside what | |
| might otherwise be a quantifier causes PCRE2 not to recognize the sequence as a | |
| quantifier. Perl recognizes a quantifier if (redundantly) either of the numbers | |
| is inside <code class="regex rouge"><span class="pcre2-semantic">\Q...\E</span></code>, but not if the separating comma is. When not recognized as | |
| a quantifier a sequence such as <code class="regex rouge"><span class="pcre2-semantic">{\Q1\E,2}</span></code> is treated as the literal string | |
| <code class="subject rouge"><span class="pcre2-semantic">{1,2}</span></code>.</p> | |
| <section class="doc-section level-2"><h3 id="non-printing-characters">Non-printing characters</h3><p>A second use of backslash provides a way of encoding non-printing characters | |
| in patterns in a visible manner. There is no restriction on the appearance of | |
| non-printing characters in a pattern, but when a pattern is being prepared by | |
| text editing, it is often easier to use one of the following escape sequences | |
| instead of the binary character it represents. In an ASCII or Unicode | |
| environment, these escapes are as follows:</p> | |
| <dl class="compact" style="--tab-width: 12"><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\a</span></code> </span></dt><dd>alarm, that is, the BEL character (<span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-3"><code class="character pcre2-api rouge"><span class="sc">0x07</span></code><span class="character-card" id="pcre2-character-3" 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 class="regex rouge"><span class="pcre2-semantic">\c<em>x</em></span></code> </span></dt><dd>"control-<em>x</em>", where <em>x</em> is a non-control ASCII character</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\e</span></code> </span></dt><dd>escape (<span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-4"><code class="character pcre2-api rouge"><span class="sc">0x1B</span></code><span class="character-card" id="pcre2-character-4" role="tooltip" aria-label="ESCAPE (U+001B)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="ESCAPE"></span><span class="character-codepoint" data-codepoint="U+001B"></span></span></span>)</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\f</span></code> </span></dt><dd>form feed (<span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-5"><code class="character pcre2-api rouge"><span class="sc">0x0C</span></code><span class="character-card" id="pcre2-character-5" 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 class="regex rouge"><span class="pcre2-semantic">\n</span></code> </span></dt><dd>linefeed (<span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-6"><code class="character pcre2-api rouge"><span class="sc">0x0A</span></code><span class="character-card" id="pcre2-character-6" 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 class="regex rouge"><span class="pcre2-semantic">\r</span></code> </span></dt><dd>carriage return (<span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-7"><code class="character pcre2-api rouge"><span class="sc">0x0D</span></code><span class="character-card" id="pcre2-character-7" 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>) (but see below)</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\t</span></code> </span></dt><dd>tab (<span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-8"><code class="character pcre2-api rouge"><span class="sc">0x09</span></code><span class="character-card" id="pcre2-character-8" 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 class="regex rouge"><span class="pcre2-semantic">\0<em>dd</em></span></code> </span></dt><dd>character with octal code 0<em>dd</em></dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\<em>ddd</em></span></code> </span></dt><dd>character with octal code <em>ddd</em>, or back reference</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\o{<em>ddd..</em>}</span></code> </span></dt><dd>character with octal code <em>ddd..</em></dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\x<em>hh</em></span></code> </span></dt><dd>character with hex code <em>hh</em></dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\x{<em>hhh..</em>}</span></code> </span></dt><dd>character with hex code <em>hhh..</em></dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\N{U+<em>hhh..</em>}</span></code> </span></dt><dd>character with Unicode hex code point <em>hhh..</em></dd></div></dl> | |
| <p>A description of how back references work is given | |
| later, | |
| following the discussion of | |
| parenthesized groups.</p> | |
| <p>By default, after <code class="regex rouge"><span class="pcre2-semantic">\x</span></code> that is not followed by {, one or two hexadecimal | |
| digits are read (letters can be in upper or lower case). If the character that | |
| follows <code class="regex rouge"><span class="pcre2-semantic">\x</span></code> is neither { nor a hexadecimal digit, an error occurs. This is | |
| different from Perl’s default behaviour, which generates a NUL character, but | |
| is in line with the behaviour of Perl’s 'strict' mode in re.</p> | |
| <p>Any number of hexadecimal digits may appear between <code class="regex rouge"><span class="pcre2-semantic">\x{</span></code> and <code class="regex rouge"><span class="pcre2-semantic">}</span></code>. If a character | |
| other than a hexadecimal digit appears between <code class="regex rouge"><span class="pcre2-semantic">\x{</span></code> and <code class="regex rouge"><span class="pcre2-semantic">}</span></code>, or if there is no | |
| terminating <code class="regex rouge"><span class="pcre2-semantic">}</span></code>, an error occurs.</p> | |
| <p>Characters whose code points are less than 256 can be defined by either of the | |
| two syntaxes for <code class="regex rouge"><span class="pcre2-semantic">\x</span></code> or by an octal sequence. There is no difference in the way | |
| they are handled. For example, <code class="regex rouge"><span class="pcre2-semantic">\xdc</span></code> is exactly the same as <code class="regex rouge"><span class="pcre2-semantic">\x{dc}</span></code> or <code class="regex rouge"><span class="pcre2-semantic">\334</span></code>. | |
| However, using the braced versions does make such sequences easier to read.</p> | |
| <p>Support is available for some ECMAScript (JavaScript) escape sequences via | |
| two compile-time options. If <code class="constant pcre2-api rouge"><span class="no">PCRE2_ALT_BSUX</span></code> is set, the sequence <code class="regex rouge"><span class="pcre2-semantic">\x</span></code> followed | |
| by <code class="regex rouge"><span class="pcre2-semantic">{</span></code> is not recognized. Only if <code class="regex rouge"><span class="pcre2-semantic">\x</span></code> is followed by two hexadecimal digits is it | |
| recognized as a character escape. Otherwise it is interpreted as a literal <code class="subject rouge"><span class="pcre2-semantic">x</span></code> | |
| character. In this mode, support for code points greater than 256 is provided | |
| by <code class="regex rouge"><span class="pcre2-semantic">\u</span></code>, which must be followed by four hexadecimal digits; otherwise it is | |
| interpreted as a literal <code class="subject rouge"><span class="pcre2-semantic">u</span></code> character.</p> | |
| <p><code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ALT_BSUX</span></code> has the same effect as <code class="constant pcre2-api rouge"><span class="no">PCRE2_ALT_BSUX</span></code> and, in addition, | |
| <code class="regex rouge"><span class="pcre2-semantic">\u{hhh..}</span></code> is recognized as the character specified by hexadecimal code point. | |
| There may be any number of hexadecimal digits, but unlike other places that | |
| also use curly brackets, spaces are not allowed and would result in the string | |
| being interpreted as a literal. This syntax is from ECMAScript 6.</p> | |
| <p>The <code class="regex rouge"><span class="pcre2-semantic">\N{U+<em>hhh...</em>}</span></code> escape sequence is recognized only when PCRE2 is operating in | |
| UTF mode. Perl also uses <code class="regex rouge"><span class="pcre2-semantic">\N{<em>name</em>}</span></code> to specify characters by Unicode name; PCRE2 | |
| does not support this. Note that when <code class="regex rouge"><span class="pcre2-semantic">\N</span></code> is not followed by an opening brace | |
| (curly bracket) it has an entirely different meaning, matching any character | |
| that is not a newline.</p> | |
| <p>There are some legacy applications where the escape sequence <code class="regex rouge"><span class="pcre2-semantic">\r</span></code> is expected to | |
| match a newline. If the <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ESCAPED_CR_IS_LF</span></code> option is set, <code class="regex rouge"><span class="pcre2-semantic">\r</span></code> in a | |
| pattern is converted to <code class="regex rouge"><span class="pcre2-semantic">\n</span></code> so that it matches a LF (linefeed) instead of a CR | |
| (carriage return) character.</p> | |
| <p>An error occurs if <code class="regex rouge"><span class="pcre2-semantic">\c</span></code> is not followed by a character whose ASCII code point | |
| is in the range 32 to 126. The precise effect of <code class="regex rouge"><span class="pcre2-semantic">\c<em>x</em></span></code> is as follows: if <em>x</em> is a | |
| lower case letter, it is converted to upper case. Then bit 6 of the character | |
| (<span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-9"><code class="character pcre2-api rouge"><span class="sc">0x40</span></code><span class="character-card" id="pcre2-character-9" role="tooltip" aria-label="COMMERCIAL AT (U+0040)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character="@"></span><span class="character-name" data-character-name="COMMERCIAL AT"></span><span class="character-codepoint" data-codepoint="U+0040"></span></span></span>) is inverted. Thus <code class="regex rouge"><span class="pcre2-semantic">\cA</span></code> to <code class="regex rouge"><span class="pcre2-semantic">\cZ</span></code> become <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-10"><code class="character pcre2-api rouge"><span class="sc">0x01</span></code><span class="character-card" id="pcre2-character-10" role="tooltip" aria-label="START OF HEADING (U+0001)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="START OF HEADING"></span><span class="character-codepoint" data-codepoint="U+0001"></span></span></span> to <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-11"><code class="character pcre2-api rouge"><span class="sc">0x1A</span></code><span class="character-card" id="pcre2-character-11" 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> (A is 41, Z is | |
| 5A), but <code class="regex rouge"><span class="pcre2-semantic">\c{</span></code> becomes <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-12"><code class="character pcre2-api rouge"><span class="sc">0x3B</span></code><span class="character-card" id="pcre2-character-12" role="tooltip" aria-label="SEMICOLON (U+003B)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=";"></span><span class="character-name" data-character-name="SEMICOLON"></span><span class="character-codepoint" data-codepoint="U+003B"></span></span></span> ({ is 7B), and <code class="regex rouge"><span class="pcre2-semantic">\c;</span></code> becomes <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-13"><code class="character pcre2-api rouge"><span class="sc">0x7B</span></code><span class="character-card" id="pcre2-character-13" role="tooltip" aria-label="LEFT CURLY BRACKET (U+007B)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character="{"></span><span class="character-name" data-character-name="LEFT CURLY BRACKET"></span><span class="character-codepoint" data-codepoint="U+007B"></span></span></span> (; is 3B). If | |
| the code unit following <code class="regex rouge"><span class="pcre2-semantic">\c</span></code> has a code point less than 32 or greater than 126, | |
| a compile-time error occurs.</p> | |
| <p>For differences in the way some escapes behave in EBCDIC environments, | |
| see section <a href="#ebcdic-environments">EBCDIC environments</a> | |
| below.</p></section> | |
| <section class="doc-section level-2"><h3 id="_octal_escapes_and_back_references">Octal escapes and back references</h3><p>The escape <code class="regex rouge"><span class="pcre2-semantic">\o</span></code> must be followed by a sequence of octal digits, enclosed in | |
| braces. An error occurs if this is not the case. This escape provides a way of | |
| specifying character code points as octal numbers greater than 0777, and it | |
| also allows octal numbers and backreferences to be unambiguously distinguished.</p> | |
| <p>If braces are not used, after <code class="regex rouge"><span class="pcre2-semantic">\0</span></code> up to two further octal digits are read. | |
| However, if the <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_NO_BS0</span></code> option is set, at least one more octal digit | |
| must follow <code class="regex rouge"><span class="pcre2-semantic">\0</span></code> (use <code class="regex rouge"><span class="pcre2-semantic">\00</span></code> to generate a NUL character). Make sure you supply | |
| two digits after the initial zero if the pattern character that follows is | |
| itself an octal digit.</p> | |
| <p>Inside a character class, when a backslash is followed by any octal digit, up | |
| to three octal digits are read to generate a code point. Any subsequent digits | |
| stand for themselves. The sequences <code class="regex rouge"><span class="pcre2-semantic">\8</span></code> and <code class="regex rouge"><span class="pcre2-semantic">\9</span></code> are treated as the literal | |
| characters <code class="subject rouge"><span class="pcre2-semantic">8</span></code> and <code class="subject rouge"><span class="pcre2-semantic">9</span></code>.</p> | |
| <p>Outside a character class, Perl’s handling of a backslash followed by a digit | |
| other than 0 is complicated by ambiguity, and Perl has changed over time, | |
| causing PCRE2 also to change. From PCRE2 release 10.45 there is an option | |
| called <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_PYTHON_OCTAL</span></code> that causes PCRE2 to use Python’s unambiguous | |
| rules. The next two subsections describe the two sets of rules.</p> | |
| <p>For greater clarity and unambiguity, it is best to avoid following backslash by a | |
| digit greater than zero. Instead, use <code class="regex rouge"><span class="pcre2-semantic">\o{...}</span></code> or <code class="regex rouge"><span class="pcre2-semantic">\x{...}</span></code> | |
| to specify numerical | |
| character code points, and <code class="regex rouge"><span class="pcre2-semantic">\g{...}</span></code> to specify backreferences.</p></section> | |
| <section class="doc-section level-2"><h3 id="_perl_rules_for_non_class_backslash_1_9">Perl rules for non-class backslash 1-9</h3><p>All the digits that follow the backslash are read as a decimal number. If the | |
| number is less than 10, begins with the digit 8 or 9, or if there are at least | |
| that many previous capture groups in the expression, the entire sequence is | |
| taken as a back reference. Otherwise, up to three octal digits are read to form | |
| a character code. For example:</p> | |
| <dl class="compact" style="--tab-width: 4"><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\040</span></code> </span></dt><dd>is another way of writing an ASCII space</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\40</span></code> </span></dt><dd>is the same, provided there are fewer than 40 previous capture groups</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\7</span></code> </span></dt><dd>is always a backreference</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\11</span></code> </span></dt><dd>might be a backreference, or another way of writing a tab</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\011</span></code> </span></dt><dd>is always a tab</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\0113</span></code> </span></dt><dd>is a tab followed by the character "3"</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\113</span></code> </span></dt><dd>might be a backreference, otherwise the character with octal code 113</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\377</span></code> </span></dt><dd>might be a backreference, otherwise the value 255 (decimal)</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\81</span></code> </span></dt><dd>is always a backreference</dd></div></dl> | |
| <p>Note that octal values of 100 or greater that are specified using this syntax | |
| must not be introduced by a leading zero, because no more than three octal | |
| digits are ever read.</p></section> | |
| <section class="doc-section level-2"><h3 id="_python_rules_for_non_class_backslash_1_9">Python rules for non-class backslash 1-9</h3><p>If there are at least three octal digits after the backslash, exactly three are | |
| read as an octal code point number, but the value must be no greater than | |
| 377, even in modes where higher code point values are supported. Any | |
| subsequent digits stand for themselves. If there are fewer than three octal | |
| digits, the sequence is taken as a decimal back reference. Thus, for example, | |
| <code class="regex rouge"><span class="pcre2-semantic">\12</span></code> is always a back reference, independent of how many captures there are in | |
| the pattern. An error is generated for a reference to a non-existent capturing | |
| group.</p></section> | |
| <section class="doc-section level-2"><h3 id="_constraints_on_character_values">Constraints on character values</h3><p>Characters that are specified using octal or hexadecimal numbers are | |
| limited to certain values, as follows:</p> | |
| <dl class="compact" style="--tab-width: 12"><div class="dlist-item"><dt><span>8-bit non-UTF mode</span></dt><dd>No greater than <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-14"><code class="character pcre2-api rouge"><span class="sc">0xff</span></code><span class="character-card" id="pcre2-character-14" 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></dd></div><div class="dlist-item"><dt><span>16-bit non-UTF mode</span></dt><dd>No greater than <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-15"><code class="character pcre2-api rouge"><span class="sc">0xffff</span></code><span class="character-card" id="pcre2-character-15" 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></dd></div><div class="dlist-item"><dt><span>32-bit non-UTF mode</span></dt><dd>No greater than <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-16"><code class="character pcre2-api rouge"><span class="sc">0xffffffff</span></code><span class="character-card" id="pcre2-character-16" role="tooltip" aria-label="Outside Unicode range (0xffffffff)" 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="0xffffffff"></span></span></span></dd></div><div class="dlist-item"><dt><span>All UTF modes</span></dt><dd>No greater than <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-17"><code class="character pcre2-api rouge"><span class="sc">0x10ffff</span></code><span class="character-card" id="pcre2-character-17" role="tooltip" aria-label="<noncharacter-10FFFF> (U+10FFFF)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="<noncharacter-10FFFF>"></span><span class="character-codepoint" data-codepoint="U+10FFFF"></span></span></span> and a valid code point</dd></div></dl> | |
| <p>Invalid Unicode code points are all those in the range <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-18"><code class="character pcre2-api rouge"><span class="sc">0xd800</span></code><span class="character-card" id="pcre2-character-18" role="tooltip" aria-label="Surrogate code point (U+D800)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="Surrogate code point"></span><span class="character-codepoint" data-codepoint="U+D800"></span></span></span> to <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-19"><code class="character pcre2-api rouge"><span class="sc">0xdfff</span></code><span class="character-card" id="pcre2-character-19" role="tooltip" aria-label="Surrogate code point (U+DFFF)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="Surrogate code point"></span><span class="character-codepoint" data-codepoint="U+DFFF"></span></span></span> (the | |
| so-called "surrogate" code points). The check for these can be disabled by the | |
| caller of <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code> by setting the option | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ALLOW_SURROGATE_ESCAPES</span></code>. However, this is possible only in UTF-8 | |
| and UTF-32 modes, because these values are not representable in UTF-16.</p></section> | |
| <section class="doc-section level-2"><h3 id="_escape_sequences_in_character_classes">Escape sequences in character classes</h3><p>All the sequences that define a single character value can be used both inside | |
| and outside character classes. In addition, inside a character class, <code class="regex rouge"><span class="pcre2-semantic">\b</span></code> is | |
| interpreted as the backspace character (<span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-20"><code class="character pcre2-api rouge"><span class="sc">0x08</span></code><span class="character-card" id="pcre2-character-20" 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>).</p> | |
| <p>When not followed by an opening brace, <code class="regex rouge"><span class="pcre2-semantic">\N</span></code> is not allowed in a character class. | |
| <code class="regex rouge"><span class="pcre2-semantic">\B</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\R</span></code>, and <code class="regex rouge"><span class="pcre2-semantic">\X</span></code> are not special inside a character class. Like other | |
| unrecognized alphabetic escape sequences, they cause an error. Outside a | |
| character class, these sequences have different meanings.</p></section> | |
| <section class="doc-section level-2"><h3 id="_unsupported_escape_sequences">Unsupported escape sequences</h3><p>In Perl, the sequences <code class="regex rouge"><span class="pcre2-semantic">\F</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\l</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\L</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\u</span></code>, and <code class="regex rouge"><span class="pcre2-semantic">\U</span></code> are recognized by its string | |
| handler and used to modify the case of following characters. By default, PCRE2 | |
| does not support these escape sequences in patterns. However, if either of the | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_ALT_BSUX</span></code> or <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ALT_BSUX</span></code> options is set, <code class="regex rouge"><span class="pcre2-semantic">\U</span></code> matches a <code class="subject rouge"><span class="pcre2-semantic">U</span></code> | |
| character, and <code class="regex rouge"><span class="pcre2-semantic">\u</span></code> can be used to define a character by code point, as | |
| described above.</p></section> | |
| <section class="doc-section level-2"><h3 id="_absolute_and_relative_backreferences">Absolute and relative backreferences</h3><p>The sequence <code class="regex rouge"><span class="pcre2-semantic">\g</span></code> followed by a signed or unsigned number, optionally enclosed | |
| in braces, is an absolute or relative backreference. A named backreference | |
| can be coded as <code class="regex rouge"><span class="pcre2-semantic">\g{<em>name</em>}</span></code>. Backreferences are discussed | |
| later, | |
| following the discussion of | |
| parenthesized groups.</p></section> | |
| <section class="doc-section level-2"><h3 id="_absolute_and_relative_subroutine_calls">Absolute and relative subroutine calls</h3><p>For compatibility with Oniguruma, the non-Perl syntax <code class="regex rouge"><span class="pcre2-semantic">\g</span></code> followed by a name or | |
| a number enclosed either in angle brackets or single quotes, is an alternative | |
| syntax for referencing a capture group as a subroutine. Details are discussed | |
| later. | |
| Note that <code class="regex rouge"><span class="pcre2-semantic">\g{...}</span></code> (Perl syntax) and <code class="regex rouge"><span class="pcre2-semantic">\g<...></span></code> (Oniguruma syntax) are <em>not</em> | |
| synonymous. The former is a backreference; the latter is a | |
| subroutine | |
| call.</p></section> | |
| <section class="doc-section level-2"><h3 id="generic-character-types">Generic character types</h3><p>Another use of backslash is for specifying generic character types:</p> | |
| <dl class="compact" style="--tab-width: 4"><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\d</span></code></span></dt><dd>Any decimal digit.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\D</span></code></span></dt><dd>Any character that is not a decimal digit.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\h</span></code></span></dt><dd>Any horizontal white space character.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\H</span></code></span></dt><dd>Any character that is not a horizontal white space character.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\N</span></code></span></dt><dd>Any character that is not a newline.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\s</span></code></span></dt><dd>Any white space character.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\S</span></code></span></dt><dd>Any character that is not a white space character.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\v</span></code></span></dt><dd>Any vertical white space character.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\V</span></code></span></dt><dd>Any character that is not a vertical white space character.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\w</span></code></span></dt><dd>Any "word" character.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\W</span></code></span></dt><dd>Any "non-word" character.</dd></div></dl> | |
| <p>The <code class="regex rouge"><span class="pcre2-semantic">\N</span></code> escape sequence has the same meaning as | |
| the <code class="regex rouge"><span class="pcre2-semantic">.</span></code> metacharacter | |
| when <code class="constant pcre2-api rouge"><span class="no">PCRE2_DOTALL</span></code> is not set, but setting <code class="constant pcre2-api rouge"><span class="no">PCRE2_DOTALL</span></code> does not change the | |
| meaning of <code class="regex rouge"><span class="pcre2-semantic">\N</span></code>. Note that when <code class="regex rouge"><span class="pcre2-semantic">\N</span></code> is followed by an opening brace it has a | |
| different meaning. See the section <a href="#non-printing-characters">Non-printing characters</a> | |
| above for details. Perl also uses <code class="regex rouge"><span class="pcre2-semantic">\N{<em>name</em>}</span></code> to specify characters by Unicode | |
| name; PCRE2 does not support this.</p> | |
| <p>Each pair of lower and upper case escape sequences partitions the complete set | |
| of characters into two disjoint sets. Any given character matches one, and only | |
| one, of each pair. The sequences can appear both inside and outside character | |
| classes. They each match one character of the appropriate type. If the current | |
| matching point is at the end of the subject string, all of them fail, because | |
| there is no character to match.</p> | |
| <p>The default <code class="regex rouge"><span class="pcre2-semantic">\s</span></code> characters are HT (9), LF (10), VT (11), FF (12), CR (13), and | |
| space (32), which are defined as white space in the "C" locale. This list may | |
| vary if locale-specific matching is taking place. For example, in some locales | |
| the "non-breaking space" character (<span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-21"><code class="character pcre2-api rouge"><span class="sc">0xA0</span></code><span class="character-card" id="pcre2-character-21" role="tooltip" aria-label="NO-BREAK SPACE (U+00A0)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="NO-BREAK SPACE"></span><span class="character-codepoint" data-codepoint="U+00A0"></span></span></span>) is recognized as white space, and in | |
| others the VT character is not.</p> | |
| <p>A "word" character is an underscore or any character that is a letter or digit. | |
| By default, the definition of letters and digits is controlled by PCRE2’s | |
| low-valued character tables, and may vary if locale-specific matching is taking | |
| place (see | |
| "Locale support" | |
| in the | |
| <a href="./pcre2api.html"><code>pcre2api</code></a> | |
| page). For example, in a French locale such as "fr_FR" in Unix-like systems, | |
| or "french" in Windows, some character codes greater than 127 are used for | |
| accented letters, and these are then matched by <code class="regex rouge"><span class="pcre2-semantic">\w</span></code>. The use of locales with | |
| Unicode is discouraged.</p> | |
| <p>By default, characters whose code points are greater than 127 never match <code class="regex rouge"><span class="pcre2-semantic">\d</span></code>, | |
| <code class="regex rouge"><span class="pcre2-semantic">\s</span></code>, or <code class="regex rouge"><span class="pcre2-semantic">\w</span></code>, and always match <code class="regex rouge"><span class="pcre2-semantic">\D</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\S</span></code>, and <code class="regex rouge"><span class="pcre2-semantic">\W</span></code>, although this may be different | |
| for characters in the range 128–255 when locale-specific matching is happening. | |
| These escape sequences retain their original meanings from before Unicode | |
| support was available, mainly for efficiency reasons. If the <code class="constant pcre2-api rouge"><span class="no">PCRE2_UCP</span></code> option | |
| is set, the behaviour is changed so that Unicode properties are used to | |
| determine character types, as follows:</p> | |
| <dl class="compact" style="--tab-width: 4"><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\d</span></code></span></dt><dd>Any character that matches <code class="regex rouge"><span class="pcre2-semantic">\p{Nd}</span></code> (decimal digit).</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\s</span></code></span></dt><dd>Any character that matches <code class="regex rouge"><span class="pcre2-semantic">\p{Z}</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\h</span></code>, or <code class="regex rouge"><span class="pcre2-semantic">\v</span></code>.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\w</span></code></span></dt><dd>Any character that matches <code class="regex rouge"><span class="pcre2-semantic">\p{L}</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\p{N}</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\p{Mn}</span></code>, or <code class="regex rouge"><span class="pcre2-semantic">\p{Pc}</span></code>.</dd></div></dl> | |
| <p>The addition of <code class="regex rouge"><span class="pcre2-semantic">\p{Mn}</span></code> (non-spacing mark) and the replacement of an explicit | |
| test for underscore with a test for <code class="regex rouge"><span class="pcre2-semantic">\p{Pc}</span></code> (connector punctuation) happened in | |
| PCRE2 release 10.43. This brings PCRE2 into line with Perl.</p> | |
| <p>The upper case escapes match the inverse sets of characters. Note that <code class="regex rouge"><span class="pcre2-semantic">\d</span></code> | |
| matches only decimal digits, whereas <code class="regex rouge"><span class="pcre2-semantic">\w</span></code> matches any Unicode digit, as well as | |
| other character categories. Note also that <code class="constant pcre2-api rouge"><span class="no">PCRE2_UCP</span></code> affects <code class="regex rouge"><span class="pcre2-semantic">\b</span></code>, and | |
| <code class="regex rouge"><span class="pcre2-semantic">\B</span></code> because they are defined in terms of <code class="regex rouge"><span class="pcre2-semantic">\w</span></code> and <code class="regex rouge"><span class="pcre2-semantic">\W</span></code>. Matching these sequences | |
| is noticeably slower when <code class="constant pcre2-api rouge"><span class="no">PCRE2_UCP</span></code> is set.</p> | |
| <p>The effect of <code class="constant pcre2-api rouge"><span class="no">PCRE2_UCP</span></code> on any one of these escape sequences can be negated by | |
| the options <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ASCII_BSD</span></code>, <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ASCII_BSS</span></code>, and | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ASCII_BSW</span></code>, respectively. These options can be set and reset within | |
| a pattern by means of an internal option setting | |
| (see below).</p> | |
| <p>The sequences <code class="regex rouge"><span class="pcre2-semantic">\h</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\H</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\v</span></code>, and <code class="regex rouge"><span class="pcre2-semantic">\V</span></code>, in contrast to the other sequences, which | |
| match only ASCII characters by default, always match a specific list of code | |
| points, whether or not <code class="constant pcre2-api rouge"><span class="no">PCRE2_UCP</span></code> is set. The horizontal space characters are:</p> | |
| <dl class="compact" style="--tab-width: 4"><div class="dlist-item"><dt><span><span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-22"><code class="character pcre2-api rouge"><span class="sc">U+0009</span></code><span class="character-card" id="pcre2-character-22" 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></span></dt><dd>Horizontal tab (HT)</dd></div><div class="dlist-item"><dt><span><span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-23"><code class="character pcre2-api rouge"><span class="sc">U+0020</span></code><span class="character-card" id="pcre2-character-23" role="tooltip" aria-label="SPACE (U+0020)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="SPACE"></span><span class="character-codepoint" data-codepoint="U+0020"></span></span></span></span></dt><dd>Space</dd></div><div class="dlist-item"><dt><span><span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-24"><code class="character pcre2-api rouge"><span class="sc">U+00A0</span></code><span class="character-card" id="pcre2-character-24" role="tooltip" aria-label="NO-BREAK SPACE (U+00A0)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="NO-BREAK SPACE"></span><span class="character-codepoint" data-codepoint="U+00A0"></span></span></span></span></dt><dd>Non-break space</dd></div><div class="dlist-item"><dt><span><span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-25"><code class="character pcre2-api rouge"><span class="sc">U+1680</span></code><span class="character-card" id="pcre2-character-25" role="tooltip" aria-label="OGHAM SPACE MARK (U+1680)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="OGHAM SPACE MARK"></span><span class="character-codepoint" data-codepoint="U+1680"></span></span></span></span></dt><dd>Ogham space mark</dd></div><div class="dlist-item"><dt><span><span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-26"><code class="character pcre2-api rouge"><span class="sc">U+180E</span></code><span class="character-card" id="pcre2-character-26" role="tooltip" aria-label="MONGOLIAN VOWEL SEPARATOR (U+180E)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="MONGOLIAN VOWEL SEPARATOR"></span><span class="character-codepoint" data-codepoint="U+180E"></span></span></span></span></dt><dd>Mongolian vowel separator</dd></div><div class="dlist-item"><dt><span><span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-27"><code class="character pcre2-api rouge"><span class="sc">U+2000</span></code><span class="character-card" id="pcre2-character-27" role="tooltip" aria-label="EN QUAD (U+2000)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="EN QUAD"></span><span class="character-codepoint" data-codepoint="U+2000"></span></span></span></span></dt><dd>En quad</dd></div><div class="dlist-item"><dt><span><span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-28"><code class="character pcre2-api rouge"><span class="sc">U+2001</span></code><span class="character-card" id="pcre2-character-28" role="tooltip" aria-label="EM QUAD (U+2001)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="EM QUAD"></span><span class="character-codepoint" data-codepoint="U+2001"></span></span></span></span></dt><dd>Em quad</dd></div><div class="dlist-item"><dt><span><span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-29"><code class="character pcre2-api rouge"><span class="sc">U+2002</span></code><span class="character-card" id="pcre2-character-29" role="tooltip" aria-label="EN SPACE (U+2002)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="EN SPACE"></span><span class="character-codepoint" data-codepoint="U+2002"></span></span></span></span></dt><dd>En space</dd></div><div class="dlist-item"><dt><span><span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-30"><code class="character pcre2-api rouge"><span class="sc">U+2003</span></code><span class="character-card" id="pcre2-character-30" role="tooltip" aria-label="EM SPACE (U+2003)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="EM SPACE"></span><span class="character-codepoint" data-codepoint="U+2003"></span></span></span></span></dt><dd>Em space</dd></div><div class="dlist-item"><dt><span><span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-31"><code class="character pcre2-api rouge"><span class="sc">U+2004</span></code><span class="character-card" id="pcre2-character-31" role="tooltip" aria-label="THREE-PER-EM SPACE (U+2004)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="THREE-PER-EM SPACE"></span><span class="character-codepoint" data-codepoint="U+2004"></span></span></span></span></dt><dd>Three-per-em space</dd></div><div class="dlist-item"><dt><span><span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-32"><code class="character pcre2-api rouge"><span class="sc">U+2005</span></code><span class="character-card" id="pcre2-character-32" role="tooltip" aria-label="FOUR-PER-EM SPACE (U+2005)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="FOUR-PER-EM SPACE"></span><span class="character-codepoint" data-codepoint="U+2005"></span></span></span></span></dt><dd>Four-per-em space</dd></div><div class="dlist-item"><dt><span><span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-33"><code class="character pcre2-api rouge"><span class="sc">U+2006</span></code><span class="character-card" id="pcre2-character-33" role="tooltip" aria-label="SIX-PER-EM SPACE (U+2006)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="SIX-PER-EM SPACE"></span><span class="character-codepoint" data-codepoint="U+2006"></span></span></span></span></dt><dd>Six-per-em space</dd></div><div class="dlist-item"><dt><span><span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-34"><code class="character pcre2-api rouge"><span class="sc">U+2007</span></code><span class="character-card" id="pcre2-character-34" role="tooltip" aria-label="FIGURE SPACE (U+2007)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="FIGURE SPACE"></span><span class="character-codepoint" data-codepoint="U+2007"></span></span></span></span></dt><dd>Figure space</dd></div><div class="dlist-item"><dt><span><span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-35"><code class="character pcre2-api rouge"><span class="sc">U+2008</span></code><span class="character-card" id="pcre2-character-35" role="tooltip" aria-label="PUNCTUATION SPACE (U+2008)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="PUNCTUATION SPACE"></span><span class="character-codepoint" data-codepoint="U+2008"></span></span></span></span></dt><dd>Punctuation space</dd></div><div class="dlist-item"><dt><span><span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-36"><code class="character pcre2-api rouge"><span class="sc">U+2009</span></code><span class="character-card" id="pcre2-character-36" role="tooltip" aria-label="THIN SPACE (U+2009)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="THIN SPACE"></span><span class="character-codepoint" data-codepoint="U+2009"></span></span></span></span></dt><dd>Thin space</dd></div><div class="dlist-item"><dt><span><span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-37"><code class="character pcre2-api rouge"><span class="sc">U+200A</span></code><span class="character-card" id="pcre2-character-37" role="tooltip" aria-label="HAIR SPACE (U+200A)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="HAIR SPACE"></span><span class="character-codepoint" data-codepoint="U+200A"></span></span></span></span></dt><dd>Hair space</dd></div><div class="dlist-item"><dt><span><span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-38"><code class="character pcre2-api rouge"><span class="sc">U+202F</span></code><span class="character-card" id="pcre2-character-38" role="tooltip" aria-label="NARROW NO-BREAK SPACE (U+202F)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="NARROW NO-BREAK SPACE"></span><span class="character-codepoint" data-codepoint="U+202F"></span></span></span></span></dt><dd>Narrow no-break space</dd></div><div class="dlist-item"><dt><span><span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-39"><code class="character pcre2-api rouge"><span class="sc">U+205F</span></code><span class="character-card" id="pcre2-character-39" role="tooltip" aria-label="MEDIUM MATHEMATICAL SPACE (U+205F)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="MEDIUM MATHEMATICAL SPACE"></span><span class="character-codepoint" data-codepoint="U+205F"></span></span></span></span></dt><dd>Medium mathematical space</dd></div><div class="dlist-item"><dt><span><span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-40"><code class="character pcre2-api rouge"><span class="sc">U+3000</span></code><span class="character-card" id="pcre2-character-40" role="tooltip" aria-label="IDEOGRAPHIC SPACE (U+3000)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="IDEOGRAPHIC SPACE"></span><span class="character-codepoint" data-codepoint="U+3000"></span></span></span></span></dt><dd>Ideographic space</dd></div></dl> | |
| <p>The vertical space characters are:</p> | |
| <dl class="compact" style="--tab-width: 4"><div class="dlist-item"><dt><span><span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-41"><code class="character pcre2-api rouge"><span class="sc">U+000A</span></code><span class="character-card" id="pcre2-character-41" 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></span></dt><dd>Linefeed (LF)</dd></div><div class="dlist-item"><dt><span><span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-42"><code class="character pcre2-api rouge"><span class="sc">U+000B</span></code><span class="character-card" id="pcre2-character-42" 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></span></dt><dd>Vertical tab (VT)</dd></div><div class="dlist-item"><dt><span><span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-43"><code class="character pcre2-api rouge"><span class="sc">U+000C</span></code><span class="character-card" id="pcre2-character-43" 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></span></dt><dd>Form feed (FF)</dd></div><div class="dlist-item"><dt><span><span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-44"><code class="character pcre2-api rouge"><span class="sc">U+000D</span></code><span class="character-card" id="pcre2-character-44" 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></span></dt><dd>Carriage return (CR)</dd></div><div class="dlist-item"><dt><span><span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-45"><code class="character pcre2-api rouge"><span class="sc">U+0085</span></code><span class="character-card" id="pcre2-character-45" role="tooltip" aria-label="NEXT LINE (U+0085)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="NEXT LINE"></span><span class="character-codepoint" data-codepoint="U+0085"></span></span></span></span></dt><dd>Next line (NEL)</dd></div><div class="dlist-item"><dt><span><span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-46"><code class="character pcre2-api rouge"><span class="sc">U+2028</span></code><span class="character-card" id="pcre2-character-46" role="tooltip" aria-label="LINE SEPARATOR (U+2028)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="LINE SEPARATOR"></span><span class="character-codepoint" data-codepoint="U+2028"></span></span></span></span></dt><dd>Line separator</dd></div><div class="dlist-item"><dt><span><span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-47"><code class="character pcre2-api rouge"><span class="sc">U+2029</span></code><span class="character-card" id="pcre2-character-47" role="tooltip" aria-label="PARAGRAPH SEPARATOR (U+2029)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="PARAGRAPH SEPARATOR"></span><span class="character-codepoint" data-codepoint="U+2029"></span></span></span></span></dt><dd>Paragraph separator</dd></div></dl> | |
| <p>In 8-bit, non-UTF-8 mode, only the characters with code points less than 256 | |
| are relevant.</p></section> | |
| <section class="doc-section level-2"><h3 id="newline-sequences">Newline sequences</h3><p>Outside a character class, by default, the escape sequence <code class="regex rouge"><span class="pcre2-semantic">\R</span></code> matches any | |
| Unicode newline sequence. In 8-bit non-UTF-8 mode <code class="regex rouge"><span class="pcre2-semantic">\R</span></code> is equivalent to the | |
| following:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?>\r\n|\n|\x0b|\f|\r|\x85)</span></code></pre></div> | |
| <p>This is an example of an "atomic group", details of which are given | |
| below. | |
| This particular group matches either the two-character sequence CR followed by | |
| LF, or one of the single characters LF (linefeed, <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-48"><code class="character pcre2-api rouge"><span class="sc">U+000A</span></code><span class="character-card" id="pcre2-character-48" 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>), VT (vertical tab, | |
| <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-49"><code class="character pcre2-api rouge"><span class="sc">U+000B</span></code><span class="character-card" id="pcre2-character-49" 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>), FF (form feed, <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-50"><code class="character pcre2-api rouge"><span class="sc">U+000C</span></code><span class="character-card" id="pcre2-character-50" 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>), CR (carriage return, <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-51"><code class="character pcre2-api rouge"><span class="sc">U+000D</span></code><span class="character-card" id="pcre2-character-51" 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>), or NEL (next | |
| line, <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-52"><code class="character pcre2-api rouge"><span class="sc">U+0085</span></code><span class="character-card" id="pcre2-character-52" role="tooltip" aria-label="NEXT LINE (U+0085)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="NEXT LINE"></span><span class="character-codepoint" data-codepoint="U+0085"></span></span></span>). Because this is an atomic group, the two-character sequence is | |
| treated as a single unit that cannot be split.</p> | |
| <p>In other modes, two additional characters whose code points are greater than 255 | |
| are added: LS (line separator, <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-53"><code class="character pcre2-api rouge"><span class="sc">U+2028</span></code><span class="character-card" id="pcre2-character-53" role="tooltip" aria-label="LINE SEPARATOR (U+2028)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="LINE SEPARATOR"></span><span class="character-codepoint" data-codepoint="U+2028"></span></span></span>) and PS (paragraph separator, <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-54"><code class="character pcre2-api rouge"><span class="sc">U+2029</span></code><span class="character-card" id="pcre2-character-54" role="tooltip" aria-label="PARAGRAPH SEPARATOR (U+2029)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="PARAGRAPH SEPARATOR"></span><span class="character-codepoint" data-codepoint="U+2029"></span></span></span>). | |
| Unicode support is not needed for these characters to be recognized.</p> | |
| <p>It is possible to restrict <code class="regex rouge"><span class="pcre2-semantic">\R</span></code> to match only CR, LF, or CRLF (instead of the | |
| complete set of Unicode line endings) by setting the option <code class="constant pcre2-api rouge"><span class="no">PCRE2_BSR_ANYCRLF</span></code> | |
| at compile time. (BSR is an abbreviation for "backslash R".) This can be made | |
| the default when PCRE2 is built; if this is the case, the other behaviour can | |
| be requested via the <code class="constant pcre2-api rouge"><span class="no">PCRE2_BSR_UNICODE</span></code> option. It is also possible to specify | |
| these settings by starting a pattern string with one of the following | |
| sequences:</p> | |
| <dl class="compact" style="--tab-width: 8"><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">(*BSR_ANYCRLF)</span></code></span></dt><dd>CR, LF, or CRLF only.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">(*BSR_UNICODE)</span></code></span></dt><dd>Any Unicode newline sequence.</dd></div></dl> | |
| <p>These override the default and the options given to the compiling function. | |
| Note that these special settings, which are not Perl-compatible, are recognized | |
| only at the very start of a pattern, and that they must be in upper case. If | |
| more than one of them is present, the last one is used. They can be combined | |
| with a change of newline convention; for example, a pattern can start with:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(*ANY)(*BSR_ANYCRLF)</span></code></pre></div> | |
| <p>They can also be combined with the <code class="regex rouge"><span class="pcre2-semantic">(*UTF)</span></code> or <code class="regex rouge"><span class="pcre2-semantic">(*UCP)</span></code> special sequences. Inside a | |
| character class, <code class="regex rouge"><span class="pcre2-semantic">\R</span></code> is treated as an unrecognized escape sequence, and causes | |
| an error.</p></section> | |
| <section class="doc-section level-2"><h3 id="_unicode_character_properties">Unicode character properties</h3><p>When PCRE2 is built with Unicode support (the default), three additional escape | |
| sequences that match characters with specific properties are available. They | |
| can be used in any mode, though in 8-bit and 16-bit non-UTF modes these | |
| sequences are of course limited to testing characters whose code points are | |
| less than <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-55"><code class="character pcre2-api rouge"><span class="sc">U+0100</span></code><span class="character-card" id="pcre2-character-55" 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> or <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-56"><code class="character pcre2-api rouge"><span class="sc">U+10000</span></code><span class="character-card" id="pcre2-character-56" role="tooltip" aria-label="LINEAR B SYLLABLE B008 A (U+10000)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character="𐀀"></span><span class="character-name" data-character-name="LINEAR B SYLLABLE B008 A"></span><span class="character-codepoint" data-codepoint="U+10000"></span></span></span>, respectively. In 32-bit non-UTF mode, code points | |
| greater than <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-57"><code class="character pcre2-api rouge"><span class="sc">0x10ffff</span></code><span class="character-card" id="pcre2-character-57" role="tooltip" aria-label="<noncharacter-10FFFF> (U+10FFFF)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="<noncharacter-10FFFF>"></span><span class="character-codepoint" data-codepoint="U+10FFFF"></span></span></span> (the Unicode limit) may be encountered. These are all | |
| treated as being in the Unknown script and with an unassigned type.</p> | |
| <p>Matching characters by Unicode property is not fast, because PCRE2 has to do a | |
| multistage table lookup in order to find a character’s property. That is why | |
| the traditional escape sequences such as <code class="regex rouge"><span class="pcre2-semantic">\d</span></code> and <code class="regex rouge"><span class="pcre2-semantic">\w</span></code> do not use Unicode | |
| properties in PCRE2 by default, though you can make them do so by setting the | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_UCP</span></code> option or by starting the pattern with <code class="regex rouge"><span class="pcre2-semantic">(*UCP)</span></code>.</p> | |
| <p>The extra escape sequences that provide property support are:</p> | |
| <dl class="compact" style="--tab-width: 8"><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\p{<em>xx</em>}</span></code> </span></dt><dd>a character with the <em>xx</em> property</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\P{<em>xx</em>}</span></code> </span></dt><dd>a character without the <em>xx</em> property</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\X</span></code> </span></dt><dd>a Unicode extended grapheme cluster</dd></div></dl> | |
| <p>For compatibility with Perl, negation can be specified by including a | |
| circumflex between the opening brace and the property. For example, <code class="regex rouge"><span class="pcre2-semantic">\p{^Lu}</span></code> is | |
| the same as <code class="regex rouge"><span class="pcre2-semantic">\P{Lu}</span></code>.</p> | |
| <p>In accordance with Unicode’s "loose matching" rules, ASCII white space | |
| characters, hyphens, and underscores are ignored in the properties represented | |
| by <em>xx</em> above. As well as the space character, ASCII white space can be | |
| tab, linefeed, vertical tab, formfeed, or carriage return.</p> | |
| <p>Some properties are specified as a name only; others as a name and a value, | |
| separated by a colon or an equals sign. The names and values consist of ASCII | |
| letters and digits (with one Perl-specific exception, see below). They are not | |
| case sensitive. Note, however, that the escapes themselves, <code class="regex rouge"><span class="pcre2-semantic">\p</span></code> and <code class="regex rouge"><span class="pcre2-semantic">\P</span></code>, | |
| <em>are</em> case sensitive. There are abbreviations for many names. The following | |
| examples are all equivalent:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">\p{bidiclass=al} | |
| \p{BC=al} | |
| \p{ Bidi_Class : AL } | |
| \p{ Bi-di class = Al } | |
| \P{ ^ Bi-di class = Al }</span></code></pre></div> | |
| <p>There is support for Unicode script names, Unicode general category properties, | |
| "Any", which matches any character (including newline), Bidi_Class, a number of | |
| binary (yes/no) properties, and some special PCRE2 properties (described | |
| below). | |
| Certain other Perl properties such as "InMusicalSymbols" are not supported by | |
| PCRE2. Note that <code class="regex rouge"><span class="pcre2-semantic">\P{Any}</span></code> does not match any characters, so always causes a | |
| match failure.</p></section> | |
| <section class="doc-section level-2"><h3 id="_script_properties_for_p_and_p">Script properties for <code class="regex rouge"><span class="pcre2-semantic">\p</span></code> and <code class="regex rouge"><span class="pcre2-semantic">\P</span></code></h3><p>There are three different syntax forms for matching a script. Each Unicode | |
| character has a basic script and, optionally, a list of other scripts ("Script | |
| Extensions") with which it is commonly used. Using the Adlam script as an | |
| example, <code class="regex rouge"><span class="pcre2-semantic">\p{sc:Adlam}</span></code> matches characters whose basic script is Adlam, whereas | |
| <code class="regex rouge"><span class="pcre2-semantic">\p{scx:Adlam}</span></code> matches, in addition, characters that have Adlam in their | |
| extensions list. The full names "script" and "script extensions" for the | |
| property types are recognized and, as for all property specifications, an | |
| equals sign is an alternative to the colon. If a script name is given without a | |
| property type, for example, <code class="regex rouge"><span class="pcre2-semantic">\p{Adlam}</span></code>, it is treated as <code class="regex rouge"><span class="pcre2-semantic">\p{scx:Adlam}</span></code>. Perl | |
| changed to this interpretation at release 5.26 and PCRE2 changed at release | |
| 10.40.</p> | |
| <p>Unassigned characters (and in non-UTF 32-bit mode, characters with code points | |
| greater than <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-58"><code class="character pcre2-api rouge"><span class="sc">0x10FFFF</span></code><span class="character-card" id="pcre2-character-58" role="tooltip" aria-label="<noncharacter-10FFFF> (U+10FFFF)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="<noncharacter-10FFFF>"></span><span class="character-codepoint" data-codepoint="U+10FFFF"></span></span></span>) are assigned the "Unknown" script. Others that are not | |
| part of an identified script are lumped together as "Common". The current list | |
| of recognized script names and their 4-character abbreviations can be obtained | |
| by running this command:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="shell">pcre2test <span class="nt">-LS</span></code></pre></div></section> | |
| <section class="doc-section level-2"><h3 id="_the_general_category_property_for_p_and_p">The general category property for <code class="regex rouge"><span class="pcre2-semantic">\p</span></code> and <code class="regex rouge"><span class="pcre2-semantic">\P</span></code></h3><p>Each character has exactly one Unicode general category property, specified by | |
| a two-letter abbreviation. If only one letter is specified with <code class="regex rouge"><span class="pcre2-semantic">\p</span></code> or <code class="regex rouge"><span class="pcre2-semantic">\P</span></code>, it | |
| includes all the general category properties that start with that letter. In | |
| this case, in the absence of negation, the curly brackets in the escape | |
| sequence are optional; these two examples have the same effect:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">\p{L} | |
| \pL</span></code></pre></div> | |
| <p>The following general category property codes are supported:</p> | |
| <dl class="compact" style="--tab-width: 4"><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">C</span></code></span></dt><dd>Other</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">Cc</span></code></span></dt><dd>Control</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">Cf</span></code></span></dt><dd>Format</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">Cn</span></code></span></dt><dd>Unassigned</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">Co</span></code></span></dt><dd>Private use</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">Cs</span></code></span></dt><dd>Surrogate</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">L</span></code></span></dt><dd>Letter</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">Lc</span></code></span></dt><dd>Cased letter</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">Ll</span></code></span></dt><dd>Lower case letter</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">Lm</span></code></span></dt><dd>Modifier letter</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">Lo</span></code></span></dt><dd>Other letter</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">Lt</span></code></span></dt><dd>Title case letter</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">Lu</span></code></span></dt><dd>Upper case letter</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">M</span></code></span></dt><dd>Mark</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">Mc</span></code></span></dt><dd>Spacing mark</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">Me</span></code></span></dt><dd>Enclosing mark</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">Mn</span></code></span></dt><dd>Non-spacing mark</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">N</span></code></span></dt><dd>Number</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">Nd</span></code></span></dt><dd>Decimal number</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">Nl</span></code></span></dt><dd>Letter number</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">No</span></code></span></dt><dd>Other number</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">P</span></code></span></dt><dd>Punctuation</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">Pc</span></code></span></dt><dd>Connector punctuation</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">Pd</span></code></span></dt><dd>Dash punctuation</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">Pe</span></code></span></dt><dd>Close punctuation</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">Pf</span></code></span></dt><dd>Final punctuation</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">Pi</span></code></span></dt><dd>Initial punctuation</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">Po</span></code></span></dt><dd>Other punctuation</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">Ps</span></code></span></dt><dd>Open punctuation</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">S</span></code></span></dt><dd>Symbol</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">Sc</span></code></span></dt><dd>Currency symbol</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">Sk</span></code></span></dt><dd>Modifier symbol</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">Sm</span></code></span></dt><dd>Mathematical symbol</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">So</span></code></span></dt><dd>Other symbol</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">Z</span></code></span></dt><dd>Separator</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">Zl</span></code></span></dt><dd>Line separator</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">Zp</span></code></span></dt><dd>Paragraph separator</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">Zs</span></code></span></dt><dd>Space separator</dd></div></dl> | |
| <p>Perl originally used the name <code class="regex rouge"><span class="pcre2-semantic">L&</span></code> for the <code class="regex rouge"><span class="pcre2-semantic">Lc</span></code> property. This is still supported | |
| by Perl, but discouraged. PCRE2 also still supports it. This property matches | |
| any character that has the <code class="regex rouge"><span class="pcre2-semantic">Lu</span></code>, <code class="regex rouge"><span class="pcre2-semantic">Ll</span></code>, or <code class="regex rouge"><span class="pcre2-semantic">Lt</span></code> property, in other words, any letter | |
| that is not classified as a modifier or "other". From release 10.45 of PCRE2 | |
| the properties <code class="regex rouge"><span class="pcre2-semantic">Lu</span></code>, <code class="regex rouge"><span class="pcre2-semantic">Ll</span></code>, and <code class="regex rouge"><span class="pcre2-semantic">Lt</span></code> are all treated as <code class="regex rouge"><span class="pcre2-semantic">Lc</span></code> when case-independent | |
| matching is set by the <code class="constant pcre2-api rouge"><span class="no">PCRE2_CASELESS</span></code> option or <code class="regex rouge"><span class="pcre2-semantic">(?i)</span></code> within the pattern. The | |
| other properties are not affected by caseless matching.</p> | |
| <p>The <code class="regex rouge"><span class="pcre2-semantic">Cs</span></code> (Surrogate) property applies only to characters whose code points are in | |
| the range <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-59"><code class="character pcre2-api rouge"><span class="sc">U+D800</span></code><span class="character-card" id="pcre2-character-59" role="tooltip" aria-label="Surrogate code point (U+D800)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="Surrogate code point"></span><span class="character-codepoint" data-codepoint="U+D800"></span></span></span> to <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-60"><code class="character pcre2-api rouge"><span class="sc">U+DFFF</span></code><span class="character-card" id="pcre2-character-60" role="tooltip" aria-label="Surrogate code point (U+DFFF)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="Surrogate code point"></span><span class="character-codepoint" data-codepoint="U+DFFF"></span></span></span>. These characters are no different to any other | |
| character when PCRE2 is not in UTF mode (using the 16-bit or 32-bit library). | |
| However, they are not valid in Unicode strings and so cannot be tested by PCRE2 | |
| in UTF mode, unless UTF validity checking has been turned off (see the | |
| discussion of <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_UTF_CHECK</span></code> in the | |
| <a href="./pcre2api.html"><code>pcre2api</code></a> | |
| page).</p> | |
| <p>The long synonyms for property names that Perl supports (such as <code class="regex rouge"><span class="pcre2-semantic">\p{Letter}</span></code>) | |
| are not supported by PCRE2, nor is it permitted to prefix any of these | |
| properties with "Is".</p> | |
| <p>No character that is in the Unicode table has the Cn (unassigned) property. | |
| Instead, this property is assumed for any code point that is not in the | |
| Unicode table.</p></section> | |
| <section class="doc-section level-2"><h3 id="_binary_yesno_properties_for_p_and_p">Binary (yes/no) properties for <code class="regex rouge"><span class="pcre2-semantic">\p</span></code> and <code class="regex rouge"><span class="pcre2-semantic">\P</span></code></h3><p>Unicode defines a number of binary properties, that is, properties whose only | |
| values are true or false. You can obtain a list of those that are recognized by | |
| <code class="regex rouge"><span class="pcre2-semantic">\p</span></code> and <code class="regex rouge"><span class="pcre2-semantic">\P</span></code>, along with their abbreviations, by running this command:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="shell">pcre2test <span class="nt">-LP</span></code></pre></div></section> | |
| <section class="doc-section level-2"><h3 id="_the_bidi_class_property_for_p_and_p">The Bidi_Class property for <code class="regex rouge"><span class="pcre2-semantic">\p</span></code> and <code class="regex rouge"><span class="pcre2-semantic">\P</span></code></h3><dl class="compact" style="--tab-width: 12"><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\p{Bidi_Class:<em>class</em>}</span></code></span></dt><dd>Matches a character with the given class.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\p{BC:<em>class</em>}</span></code></span></dt><dd>Matches a character with the given class.</dd></div></dl> | |
| <p>The recognized classes are:</p> | |
| <dl class="compact" style="--tab-width: 4"><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">AL</span></code></span></dt><dd>Arabic letter</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">AN</span></code></span></dt><dd>Arabic number</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">B</span></code></span></dt><dd>Paragraph separator</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">BN</span></code></span></dt><dd>Boundary neutral</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">CS</span></code></span></dt><dd>Common separator</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">EN</span></code></span></dt><dd>European number</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">ES</span></code></span></dt><dd>European separator</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">ET</span></code></span></dt><dd>European terminator</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">FSI</span></code></span></dt><dd>First strong isolate</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">L</span></code></span></dt><dd>Left-to-right</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">LRE</span></code></span></dt><dd>Left-to-right embedding</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">LRI</span></code></span></dt><dd>Left-to-right isolate</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">LRO</span></code></span></dt><dd>Left-to-right override</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">NSM</span></code></span></dt><dd>Non-spacing mark</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">ON</span></code></span></dt><dd>Other neutral</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">PDF</span></code></span></dt><dd>Pop directional format</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">PDI</span></code></span></dt><dd>Pop directional isolate</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">R</span></code></span></dt><dd>Right-to-left</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">RLE</span></code></span></dt><dd>Right-to-left embedding</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">RLI</span></code></span></dt><dd>Right-to-left isolate</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">RLO</span></code></span></dt><dd>Right-to-left override</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">S</span></code></span></dt><dd>Segment separator</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">WS</span></code></span></dt><dd>White space</dd></div></dl> | |
| <p>As in all property specifications, an equals sign may be used instead of a | |
| colon and the class names are case-insensitive. Only the short names listed | |
| above are recognized; PCRE2 does not at present support any long alternatives.</p></section> | |
| <section class="doc-section level-2"><h3 id="_extended_grapheme_clusters">Extended grapheme clusters</h3><p>The <code class="regex rouge"><span class="pcre2-semantic">\X</span></code> escape matches any number of Unicode characters that form an "extended | |
| grapheme cluster", and treats the sequence as an atomic group | |
| (see below). | |
| Unicode supports various kinds of composite character by giving each character | |
| a grapheme breaking property, and having rules that use these properties to | |
| define the boundaries of extended grapheme clusters. The rules are defined in | |
| Unicode Standard Annex 29, "Unicode Text Segmentation". Unicode 11.0.0 | |
| abandoned the use of some previous properties that had been used for emojis. | |
| Instead it introduced various emoji-specific properties. PCRE2 uses only the | |
| Extended Pictographic property.</p> | |
| <p><code class="regex rouge"><span class="pcre2-semantic">\X</span></code> always matches at least one character. Then it decides whether to add | |
| additional characters according to the following rules for ending a cluster:</p> | |
| <ol class="arabic compact"><li>End at the end of the subject string.</li><li>Do not end between CR and LF; otherwise end after any control character.</li><li>Do not break Hangul (a Korean script) syllable sequences. Hangul characters | |
| are of five types: L, V, T, LV, and LVT. An L character may be followed by an | |
| L, V, LV, or LVT character; an LV or V character may be followed by a V or T | |
| character; an LVT or T character may be followed only by a T character.</li><li>Do not end before extending characters or spacing marks or the zero-width | |
| joiner (ZWJ) character. Characters with the "mark" property always have the | |
| "extend" grapheme breaking property.</li><li>Do not end after prepend characters.</li><li>Do not end within emoji modifier sequences or emoji ZWJ (zero-width | |
| joiner) sequences. An emoji ZWJ sequence consists of a character with the | |
| Extended_Pictographic property, optionally followed by one or more characters | |
| with the Extend property, followed by the ZWJ character, followed by another | |
| Extended_Pictographic character.</li><li>Do not break within emoji flag sequences. That is, do not break between | |
| regional indicator (RI) characters if there are an odd number of RI characters | |
| before the break point.</li><li>Otherwise, end the cluster.</li></ol></section> | |
| <section class="doc-section level-2"><h3 id="_pcre2s_additional_properties">PCRE2’s additional properties</h3><p>As well as the standard Unicode properties described above, PCRE2 supports four | |
| more that make it possible to convert traditional escape sequences such as <code class="regex rouge"><span class="pcre2-semantic">\w</span></code> | |
| and <code class="regex rouge"><span class="pcre2-semantic">\s</span></code> to use Unicode properties. PCRE2 uses these non-standard, non-Perl | |
| properties internally when <code class="constant pcre2-api rouge"><span class="no">PCRE2_UCP</span></code> is set. However, they may also be used | |
| explicitly. These properties are:</p> | |
| <dl class="compact" style="--tab-width: 4"><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">Xan</span></code></span></dt><dd>Any alphanumeric character</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">Xps</span></code></span></dt><dd>Any POSIX space character</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">Xsp</span></code></span></dt><dd>Any Perl space character</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">Xwd</span></code></span></dt><dd>Any Perl "word" character</dd></div></dl> | |
| <p><code class="regex rouge"><span class="pcre2-semantic">Xan</span></code> matches characters that have either the <code class="regex rouge"><span class="pcre2-semantic">L</span></code> (letter) or the <code class="regex rouge"><span class="pcre2-semantic">N</span></code> (number) | |
| property. <code class="regex rouge"><span class="pcre2-semantic">Xps</span></code> matches the characters tab, linefeed, vertical tab, form feed, or | |
| carriage return, and any other character that has the <code class="regex rouge"><span class="pcre2-semantic">Z</span></code> (separator) property | |
| (this includes the space character). <code class="regex rouge"><span class="pcre2-semantic">Xsp</span></code> is the same as <code class="regex rouge"><span class="pcre2-semantic">Xps</span></code>; in PCRE1 it used | |
| to exclude vertical tab, for Perl compatibility, but Perl changed. <code class="regex rouge"><span class="pcre2-semantic">Xwd</span></code> matches | |
| the same characters as <code class="regex rouge"><span class="pcre2-semantic">Xan</span></code>, plus those that match <code class="regex rouge"><span class="pcre2-semantic">Mn</span></code> (non-spacing mark) or <code class="regex rouge"><span class="pcre2-semantic">Pc</span></code> | |
| (connector punctuation, which includes underscore).</p> | |
| <p>There is another non-standard property, <code class="regex rouge"><span class="pcre2-semantic">Xuc</span></code>, which matches any character that | |
| can be represented by a Universal Character Name in C++ and other programming | |
| languages. These are the characters $, @, ` (grave accent), and all characters | |
| with Unicode code points greater than or equal to <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-61"><code class="character pcre2-api rouge"><span class="sc">U+00A0</span></code><span class="character-card" id="pcre2-character-61" role="tooltip" aria-label="NO-BREAK SPACE (U+00A0)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="NO-BREAK SPACE"></span><span class="character-codepoint" data-codepoint="U+00A0"></span></span></span>, except for the | |
| surrogates <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-62"><code class="character pcre2-api rouge"><span class="sc">U+D800</span></code><span class="character-card" id="pcre2-character-62" role="tooltip" aria-label="Surrogate code point (U+D800)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="Surrogate code point"></span><span class="character-codepoint" data-codepoint="U+D800"></span></span></span> to <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-63"><code class="character pcre2-api rouge"><span class="sc">U+DFFF</span></code><span class="character-card" id="pcre2-character-63" role="tooltip" aria-label="Surrogate code point (U+DFFF)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="Surrogate code point"></span><span class="character-codepoint" data-codepoint="U+DFFF"></span></span></span>. Note that most base (ASCII) characters are | |
| excluded. (Universal Character Names are of the form <code class="regex rouge"><span class="pcre2-semantic">\u<em>HHHH</em></span></code> or <code class="regex rouge"><span class="pcre2-semantic">\U<em>HHHHHHHH</em></span></code> | |
| where H is a hexadecimal digit. Note that the <code class="regex rouge"><span class="pcre2-semantic">Xuc</span></code> property does not match these | |
| sequences but the characters that they represent.)</p></section> | |
| <section class="doc-section level-2"><h3 id="_resetting_the_match_start">Resetting the match start</h3><p>In normal use, the escape sequence <code class="regex rouge"><span class="pcre2-semantic">\K</span></code> causes any previously matched characters | |
| not to be included in the final matched sequence that is returned. For example, | |
| the pattern:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">foo\Kbar</span></code></pre></div> | |
| <p>matches <code class="subject rouge"><span class="pcre2-semantic">foobar</span></code>, but reports that it has matched <code class="subject rouge"><span class="pcre2-semantic">bar</span></code>. <code class="regex rouge"><span class="pcre2-semantic">\K</span></code> does not interact | |
| with anchoring in any way. The pattern:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">^foo\Kbar</span></code></pre></div> | |
| <p>matches only when the subject begins with <code class="subject rouge"><span class="pcre2-semantic">foobar</span></code> (in single line mode), | |
| though it again reports the matched string as <code class="subject rouge"><span class="pcre2-semantic">bar</span></code>. This feature is similar to | |
| a lookbehind assertion | |
| (described below), | |
| but the part of the pattern that precedes <code class="regex rouge"><span class="pcre2-semantic">\K</span></code> is not constrained to match a | |
| limited number of characters, as is required for a lookbehind assertion. The | |
| use of <code class="regex rouge"><span class="pcre2-semantic">\K</span></code> does not interfere with the setting of | |
| captured substrings. | |
| For example, when the pattern</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(foo)\Kbar</span></code></pre></div> | |
| <p>matches <code class="subject rouge"><span class="pcre2-semantic">foobar</span></code>, the first substring is still set to <code class="subject rouge"><span class="pcre2-semantic">foo</span></code>.</p> | |
| <p>From version 5.32.0 Perl forbids the use of <code class="regex rouge"><span class="pcre2-semantic">\K</span></code> in lookaround assertions. From | |
| release 10.38 PCRE2 also forbids this by default. However, the | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ALLOW_LOOKAROUND_BSK</span></code> option can be used when calling | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code> to re-enable the previous behaviour. When this option is | |
| set, <code class="regex rouge"><span class="pcre2-semantic">\K</span></code> is acted upon when it occurs inside positive assertions, but is | |
| ignored in negative assertions. Note that when a pattern such as <code class="regex rouge"><span class="pcre2-semantic">(?=ab\K)</span></code> | |
| matches, the reported start of the match can be greater than the end of the | |
| match. Using <code class="regex rouge"><span class="pcre2-semantic">\K</span></code> in a lookbehind assertion at the start of a pattern can also | |
| lead to odd effects. For example, consider this pattern:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?<=\Kfoo)bar</span></code></pre></div> | |
| <p>If the subject is <code class="subject rouge"><span class="pcre2-semantic">foobar</span></code>, a call to <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> with a starting | |
| offset of 3 succeeds and reports the matching string as <code class="subject rouge"><span class="pcre2-semantic">foobar</span></code>, that is, the | |
| start of the reported match is earlier than where the match started.</p></section> | |
| <section class="doc-section level-2"><h3 id="_simple_assertions">Simple assertions</h3><p>The final use of backslash is for certain simple assertions. An assertion | |
| specifies a condition that has to be met at a particular point in a match, | |
| without consuming any characters from the subject string. The use of | |
| groups for more complicated assertions is described | |
| below. | |
| The backslashed assertions are:</p> | |
| <dl class="compact" style="--tab-width: 4"><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\b</span></code></span></dt><dd>Matches at a word boundary.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\B</span></code></span></dt><dd>Matches when not at a word boundary.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\A</span></code></span></dt><dd>Matches at the start of the subject.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\Z</span></code></span></dt><dd>Matches at the end of the subject; also matches before a newline at the end of the subject.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\z</span></code></span></dt><dd>Matches only at the end of the subject.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">\G</span></code></span></dt><dd>Matches at the first matching position in the subject.</dd></div></dl> | |
| <p>Inside a character class, <code class="regex rouge"><span class="pcre2-semantic">\b</span></code> has a different meaning; it matches the backspace | |
| character. If any other of these assertions appears in a character class, an | |
| "invalid escape sequence" error is generated.</p> | |
| <p>A word boundary is a position in the subject string where the current character | |
| and the previous character do not both match <code class="regex rouge"><span class="pcre2-semantic">\w</span></code> or <code class="regex rouge"><span class="pcre2-semantic">\W</span></code> (i.e. one matches | |
| <code class="regex rouge"><span class="pcre2-semantic">\w</span></code> and the other matches <code class="regex rouge"><span class="pcre2-semantic">\W</span></code>), or the start or end of the string if the | |
| first or last character matches <code class="regex rouge"><span class="pcre2-semantic">\w</span></code>, respectively. When PCRE2 is built with | |
| Unicode support, the meanings of <code class="regex rouge"><span class="pcre2-semantic">\w</span></code> and <code class="regex rouge"><span class="pcre2-semantic">\W</span></code> can be changed by setting the | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_UCP</span></code> option. When this is done, it also affects <code class="regex rouge"><span class="pcre2-semantic">\b</span></code> and <code class="regex rouge"><span class="pcre2-semantic">\B</span></code>. Neither PCRE2 | |
| nor Perl has a separate "start of word" or "end of word" metasequence. However, | |
| whatever follows <code class="regex rouge"><span class="pcre2-semantic">\b</span></code> normally determines which it is. For example, the fragment | |
| <code class="regex rouge"><span class="pcre2-semantic">\ba</span></code> matches <code class="subject rouge"><span class="pcre2-semantic">a</span></code> at the start of a word.</p> | |
| <p>The <code class="regex rouge"><span class="pcre2-semantic">\A</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\Z</span></code>, and <code class="regex rouge"><span class="pcre2-semantic">\z</span></code> assertions differ from the traditional circumflex and | |
| dollar (described in the section <a href="#circumflex-and-dollar">Circumflex and dollar</a>) in that they only ever match at the very | |
| start and end of the subject string, whatever options are set. Thus, they are | |
| independent of multiline mode. These three assertions are not affected by the | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_NOTBOL</span></code> or <code class="constant pcre2-api rouge"><span class="no">PCRE2_NOTEOL</span></code> options, which affect only the behaviour of the | |
| circumflex and dollar metacharacters. However, if the <code class="parameter pcre2-api rouge"><span class="nv">start_offset</span></code> | |
| argument of <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> is non-zero, indicating that matching is to | |
| start at a point other than the beginning of the subject, <code class="regex rouge"><span class="pcre2-semantic">\A</span></code> can never match. | |
| The difference between <code class="regex rouge"><span class="pcre2-semantic">\Z</span></code> and <code class="regex rouge"><span class="pcre2-semantic">\z</span></code> is that <code class="regex rouge"><span class="pcre2-semantic">\Z</span></code> matches before a newline at the | |
| end of the string as well as at the very end, whereas <code class="regex rouge"><span class="pcre2-semantic">\z</span></code> matches only at the | |
| end.</p> | |
| <p>The <code class="regex rouge"><span class="pcre2-semantic">\G</span></code> assertion is true only when the current matching position is at the | |
| start point of the matching process, as specified by the <code class="parameter pcre2-api rouge"><span class="nv">start_offset</span></code> | |
| argument of <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code>. It differs from <code class="regex rouge"><span class="pcre2-semantic">\A</span></code> when the value of | |
| <code class="parameter pcre2-api rouge"><span class="nv">start_offset</span></code> is non-zero. By calling <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> multiple times | |
| with appropriate arguments, you can mimic Perl’s /g option, and it is in this | |
| kind of implementation where <code class="regex rouge"><span class="pcre2-semantic">\G</span></code> can be useful.</p> | |
| <p>Note, however, that PCRE2’s implementation of <code class="regex rouge"><span class="pcre2-semantic">\G</span></code>, being true at the starting | |
| character of the matching process, is subtly different from Perl’s, which | |
| defines it as true at the end of the previous match. In Perl, these can be | |
| different when the previously matched string was empty. Because PCRE2 does just | |
| one match at a time, it cannot reproduce this behaviour.</p> | |
| <p>If all the alternatives of a pattern begin with <code class="regex rouge"><span class="pcre2-semantic">\G</span></code>, the expression is anchored | |
| to the starting match position, and the "anchored" flag is set in the compiled | |
| regular expression.</p></section></section> | |
| <section class="doc-section level-1"><h2 id="circumflex-and-dollar">Circumflex and dollar</h2><p>The circumflex and dollar metacharacters are zero-width assertions. That is, | |
| they test for a particular condition being true without consuming any | |
| characters from the subject string. These two metacharacters are concerned with | |
| matching the starts and ends of lines. If the newline convention is set so that | |
| only the two-character sequence CRLF is recognized as a newline, isolated CR | |
| and LF characters are treated as ordinary data characters, and are not | |
| recognized as newlines.</p> | |
| <p>Outside a character class, in the default matching mode, the circumflex | |
| character is an assertion that is true only if the current matching point is at | |
| the start of the subject string. If the <code class="parameter pcre2-api rouge"><span class="nv">start_offset</span></code> argument of | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> is non-zero, or if <code class="constant pcre2-api rouge"><span class="no">PCRE2_NOTBOL</span></code> is set, circumflex can | |
| never match if the <code class="constant pcre2-api rouge"><span class="no">PCRE2_MULTILINE</span></code> option is unset. Inside a character class, | |
| circumflex has an entirely different meaning | |
| (see below).</p> | |
| <p>Circumflex need not be the first character of the pattern if a number of | |
| alternatives are involved, but it should be the first thing in each alternative | |
| in which it appears if the pattern is ever to match that branch. If all | |
| possible alternatives start with a circumflex, that is, if the pattern is | |
| constrained to match only at the start of the subject, it is said to be an | |
| "anchored" pattern. (There are also other constructs that can cause a pattern | |
| to be anchored.)</p> | |
| <p>The dollar character is an assertion that is true only if the current matching | |
| point is at the end of the subject string, or immediately before a newline at | |
| the end of the string (by default), unless <code class="constant pcre2-api rouge"><span class="no">PCRE2_NOTEOL</span></code> is set. Note, however, | |
| that it does not actually match the newline. Dollar need not be the last | |
| character of the pattern if a number of alternatives are involved, but it | |
| should be the last item in any branch in which it appears. Dollar has no | |
| special meaning in a character class.</p> | |
| <p>The meaning of dollar can be changed so that it matches only at the very end of | |
| the string, by setting the <code class="constant pcre2-api rouge"><span class="no">PCRE2_DOLLAR_ENDONLY</span></code> option at compile time. This | |
| does not affect the <code class="regex rouge"><span class="pcre2-semantic">\Z</span></code> assertion.</p> | |
| <p>The meanings of the circumflex and dollar metacharacters are changed if the | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_MULTILINE</span></code> option is set. When this is the case, a dollar character | |
| matches before any newlines in the string, as well as at the very end, and a | |
| circumflex matches immediately after internal newlines as well as at the start | |
| of the subject string. It does not match after a newline that ends the string, | |
| for compatibility with Perl. However, this can be changed by setting the | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_ALT_CIRCUMFLEX</span></code> option.</p> | |
| <p>For example, the pattern <code class="regex rouge"><span class="pcre2-semantic">^abc$</span></code> matches the subject string <code class="subject rouge"><span class="pcre2-semantic">def\nabc</span></code> (where | |
| <code class="regex rouge"><span class="pcre2-semantic">\n</span></code> represents a newline) in multiline mode, but not otherwise. Consequently, | |
| patterns that are anchored in single line mode because all branches start with | |
| ^ are not anchored in multiline mode, and a match for circumflex is possible | |
| when the <code class="parameter pcre2-api rouge"><span class="nv">start_offset</span></code> argument of <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> is non-zero. The | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_DOLLAR_ENDONLY</span></code> option is ignored if <code class="constant pcre2-api rouge"><span class="no">PCRE2_MULTILINE</span></code> is set.</p> | |
| <p>When the newline convention (see | |
| "Newline conventions" | |
| below) recognizes the two-character sequence CRLF as a newline, this is | |
| preferred, even if the single characters CR and LF are also recognized as | |
| newlines. For example, if the newline convention is "any", a multiline mode | |
| circumflex matches before <code class="subject rouge"><span class="pcre2-semantic">xyz</span></code> in the string <code class="subject rouge"><span class="pcre2-semantic">abc\r\nxyz</span></code> rather than after | |
| CR, even though CR on its own is a valid newline. (It also matches at the very | |
| start of the string, of course.)</p> | |
| <p>Note that the sequences <code class="regex rouge"><span class="pcre2-semantic">\A</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\Z</span></code>, and <code class="regex rouge"><span class="pcre2-semantic">\z</span></code> can be used to match the start and | |
| end of the subject in both modes, and if all branches of a pattern start with | |
| <code class="regex rouge"><span class="pcre2-semantic">\A</span></code> it is always anchored, whether or not <code class="constant pcre2-api rouge"><span class="no">PCRE2_MULTILINE</span></code> is set.</p></section> | |
| <section class="doc-section level-1"><h2 id="_full_stop_period_dot_and_n">Full stop (period, dot) and <code class="regex rouge"><span class="pcre2-semantic">\n</span></code></h2><p>Outside a character class, a dot in the pattern matches any one character in | |
| the subject string except (by default) a character that signifies the end of a | |
| line. One or more characters may be specified as line terminators (see | |
| "Newline conventions" | |
| above).</p> | |
| <p>Dot never matches a single line-ending character. When the two-character | |
| sequence CRLF is the only line ending, dot does not match CR if it is | |
| immediately followed by LF, but otherwise it matches all characters (including | |
| isolated CRs and LFs). When ANYCRLF is selected for line endings, no occurrences | |
| of CR of LF match dot. When all Unicode line endings are being recognized, dot | |
| does not match CR or LF or any of the other line ending characters.</p> | |
| <p>The behaviour of dot with regard to newlines can be changed. If the | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_DOTALL</span></code> option is set, a dot matches any one character, without exception. | |
| If the two-character sequence CRLF is present in the subject string, it takes | |
| two dots to match it.</p> | |
| <p>The handling of dot is entirely independent of the handling of circumflex and | |
| dollar, the only relationship being that they both involve newlines. Dot has no | |
| special meaning in a character class.</p> | |
| <p>The escape sequence <code class="regex rouge"><span class="pcre2-semantic">\N</span></code> when not followed by an opening brace behaves like a | |
| dot, except that it is not affected by the <code class="constant pcre2-api rouge"><span class="no">PCRE2_DOTALL</span></code> option. In other words, | |
| it matches any character except one that signifies the end of a line.</p> | |
| <p>When <code class="regex rouge"><span class="pcre2-semantic">\N</span></code> is followed by an opening brace it has a different meaning. See the | |
| section <a href="#non-printing-characters">Non-printing characters</a> | |
| above for details. Perl also uses <code class="regex rouge"><span class="pcre2-semantic">\N{<em>name</em>}</span></code> to specify characters by Unicode | |
| name; PCRE2 does not support this.</p></section> | |
| <section class="doc-section level-1"><h2 id="_matching_a_single_code_unit">Matching a single code unit</h2><p>Outside a character class, the escape sequence <code class="regex rouge"><span class="pcre2-semantic">\C</span></code> matches any one code unit, | |
| whether or not a UTF mode is set. In the 8-bit library, one code unit is one | |
| byte; in the 16-bit library it is a 16-bit unit; in the 32-bit library it is a | |
| 32-bit unit. Unlike a dot, <code class="regex rouge"><span class="pcre2-semantic">\C</span></code> always matches line-ending characters. The | |
| feature is provided in Perl in order to match individual bytes in UTF-8 mode, | |
| but it is unclear how it can usefully be used.</p> | |
| <p>Because <code class="regex rouge"><span class="pcre2-semantic">\C</span></code> breaks up characters into individual code units, matching one unit | |
| with <code class="regex rouge"><span class="pcre2-semantic">\C</span></code> in UTF-8 or UTF-16 mode means that the rest of the string may start | |
| with a malformed UTF character. This has undefined results, because PCRE2 | |
| assumes that it is matching character by character in a valid UTF string (by | |
| default it checks the subject string’s validity at the start of processing | |
| unless the <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_UTF_CHECK</span></code> or <code class="constant pcre2-api rouge"><span class="no">PCRE2_MATCH_INVALID_UTF</span></code> option is used).</p> | |
| <p>An application can lock out the use of <code class="regex rouge"><span class="pcre2-semantic">\C</span></code> by setting the | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_NEVER_BACKSLASH_C</span></code> option when compiling a pattern. It is also possible to | |
| build PCRE2 with the use of <code class="regex rouge"><span class="pcre2-semantic">\C</span></code> permanently disabled.</p> | |
| <p>PCRE2 does not allow <code class="regex rouge"><span class="pcre2-semantic">\C</span></code> to appear in lookbehind assertions | |
| (described below) | |
| in UTF-8 or UTF-16 modes, because this would make it impossible to calculate | |
| the length of the lookbehind. Neither the alternative matching function | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code> nor the JIT optimizer support <code class="regex rouge"><span class="pcre2-semantic">\C</span></code> in these UTF modes. | |
| The former gives a match-time error; the latter fails to optimize and so the | |
| match is always run using the interpreter.</p> | |
| <p>In the 32-bit library, however, <code class="regex rouge"><span class="pcre2-semantic">\C</span></code> is always supported (when not explicitly | |
| locked out) because it always matches a single code unit, whether or not UTF-32 | |
| is specified.</p> | |
| <p>In general, the <code class="regex rouge"><span class="pcre2-semantic">\C</span></code> escape sequence is best avoided. However, one way of using | |
| it that avoids the problem of malformed UTF-8 or UTF-16 characters is to use a | |
| lookahead to check the length of the next character, as in this pattern, which | |
| could be used with a UTF-8 string (ignore white space and line breaks):</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?| (?=[\x00-\x7f])(\C) | | |
| (?=[\x80-\x{7ff}])(\C)(\C) | | |
| (?=[\x{800}-\x{ffff}])(\C)(\C)(\C) | | |
| (?=[\x{10000}-\x{1fffff}])(\C)(\C)(\C)(\C))</span></code></pre></div> | |
| <p>In this example, a group that starts with <code class="regex rouge"><span class="pcre2-semantic">(?|</span></code> resets the capturing parentheses | |
| numbers in each alternative (see | |
| "Duplicate Group Numbers" | |
| below). The assertions at the start of each branch check the next UTF-8 | |
| character for values whose encoding uses 1, 2, 3, or 4 bytes, respectively. The | |
| character’s individual bytes are then captured by the appropriate number of | |
| <code class="regex rouge"><span class="pcre2-semantic">\C</span></code> groups.</p></section> | |
| <section class="doc-section level-1"><h2 id="_square_brackets_and_character_classes">Square brackets and character classes</h2><p>An opening square bracket introduces a character class, terminated by a closing | |
| square bracket. A closing square bracket on its own is not special by default. | |
| If a closing square bracket is required as a member of the class, it should be | |
| the first data character in the class (after an initial circumflex, if present) | |
| or escaped with a backslash. This means that, by default, an empty class cannot | |
| be defined. However, if the <code class="constant pcre2-api rouge"><span class="no">PCRE2_ALLOW_EMPTY_CLASS</span></code> option is set, a closing | |
| square bracket at the start does end the (empty) class.</p> | |
| <p>A character class matches a single character in the subject. A matched | |
| character must be in the set of characters defined by the class, unless the | |
| first character in the class definition is a circumflex, in which case the | |
| subject character must not be in the set defined by the class. If a circumflex | |
| is actually required as a member of the class, ensure it is not the first | |
| character, or escape it with a backslash.</p> | |
| <p>For example, the character class <code class="regex rouge"><span class="pcre2-semantic">[aeiou]</span></code> matches any lower case English vowel, | |
| whereas <code class="regex rouge"><span class="pcre2-semantic">[^aeiou]</span></code> matches all other characters. Note that a circumflex is just a | |
| convenient notation for specifying the characters that are in the class by | |
| enumerating those that are not. A class that starts with a circumflex is not an | |
| assertion; it still consumes a character from the subject string, and therefore | |
| it fails to match if the current pointer is at the end of the string.</p> | |
| <p>Characters in a class may be specified by their code points using <code class="regex rouge"><span class="pcre2-semantic">\o</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\x</span></code>, or | |
| <code class="regex rouge"><span class="pcre2-semantic">\N{U+<em>hh...</em>}</span></code> in the usual way. When caseless matching is set, any letters in a | |
| class represent both their upper case and lower case versions, so for example, | |
| a caseless <code class="regex rouge"><span class="pcre2-semantic">[aeiou]</span></code> matches <code class="subject rouge"><span class="pcre2-semantic">A</span></code> as well as <code class="subject rouge"><span class="pcre2-semantic">a</span></code>, and a caseless <code class="regex rouge"><span class="pcre2-semantic">[^aeiou]</span></code> does not | |
| match <code class="subject rouge"><span class="pcre2-semantic">A</span></code>, whereas a caseful version would. Note that there are two ASCII | |
| characters, K and S, that, in addition to their lower case ASCII equivalents, | |
| are case-equivalent with Unicode <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-64"><code class="character pcre2-api rouge"><span class="sc">U+212A</span></code><span class="character-card" id="pcre2-character-64" role="tooltip" aria-label="KELVIN SIGN (U+212A)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character="K"></span><span class="character-name" data-character-name="KELVIN SIGN"></span><span class="character-codepoint" data-codepoint="U+212A"></span></span></span> (Kelvin sign) and <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-65"><code class="character pcre2-api rouge"><span class="sc">U+017F</span></code><span class="character-card" id="pcre2-character-65" role="tooltip" aria-label="LATIN SMALL LETTER LONG S (U+017F)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character="ſ"></span><span class="character-name" data-character-name="LATIN SMALL LETTER LONG S"></span><span class="character-codepoint" data-codepoint="U+017F"></span></span></span> (long S) | |
| respectively when either <code class="constant pcre2-api rouge"><span class="no">PCRE2_UTF</span></code> or <code class="constant pcre2-api rouge"><span class="no">PCRE2_UCP</span></code> is set. If you do not want | |
| these ASCII/non-ASCII case equivalences, you can suppress them by setting | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_CASELESS_RESTRICT</span></code>, either as an option in a compile context, or by | |
| including <code class="regex rouge"><span class="pcre2-semantic">(*CASELESS_RESTRICT)</span></code> or <code class="regex rouge"><span class="pcre2-semantic">(?r)</span></code> within a pattern.</p> | |
| <p>Characters that might indicate line breaks are never treated in any special way | |
| when matching character classes, whatever line-ending sequence is in use, and | |
| whatever setting of the <code class="constant pcre2-api rouge"><span class="no">PCRE2_DOTALL</span></code> and <code class="constant pcre2-api rouge"><span class="no">PCRE2_MULTILINE</span></code> options is used. A | |
| class such as <code class="regex rouge"><span class="pcre2-semantic">[^a]</span></code> always matches one of these characters.</p> | |
| <p>The generic character type escape sequences <code class="regex rouge"><span class="pcre2-semantic">\d</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\D</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\h</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\H</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\p</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\P</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\s</span></code>, | |
| <code class="regex rouge"><span class="pcre2-semantic">\S</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\v</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\V</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\w</span></code>, and <code class="regex rouge"><span class="pcre2-semantic">\W</span></code> may appear in a character class, and add the | |
| characters that they match to the class. For example, <code class="regex rouge"><span class="pcre2-semantic">[\dABCDEF]</span></code> matches any | |
| hexadecimal digit. In UTF modes, the <code class="constant pcre2-api rouge"><span class="no">PCRE2_UCP</span></code> option affects the meanings of | |
| <code class="regex rouge"><span class="pcre2-semantic">\d</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\s</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\w</span></code> and their upper case partners, just as it does when they appear | |
| outside a character class, as described in the section | |
| <a href="#generic-character-types">Generic character types</a> | |
| above. The escape sequence <code class="regex rouge"><span class="pcre2-semantic">\b</span></code> has a different meaning inside a character | |
| class; it matches the backspace character. The sequences <code class="regex rouge"><span class="pcre2-semantic">\B</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\R</span></code>, and <code class="regex rouge"><span class="pcre2-semantic">\X</span></code> are | |
| not special inside a character class. Like any other unrecognized escape | |
| sequences, they cause an error. The same is true for <code class="regex rouge"><span class="pcre2-semantic">\N</span></code> when not followed by | |
| an opening brace.</p> | |
| <p>The minus (hyphen) character can be used to specify a range of characters in a | |
| character class. For example, <code class="regex rouge"><span class="pcre2-semantic">[d-m]</span></code> matches any letter between d and m, | |
| inclusive. If a minus character is required in a class, it must be escaped with | |
| a backslash or appear in a position where it cannot be interpreted as | |
| indicating a range, typically as the first or last character in the class, | |
| or immediately after a range. For example, <code class="regex rouge"><span class="pcre2-semantic">[b-d-z]</span></code> matches letters in the range | |
| b to d, a hyphen character, or z.</p> | |
| <p>There is some special treatment for alphabetic ranges in EBCDIC environments; | |
| see the section <a href="#ebcdic-environments">EBCDIC environments</a> | |
| below.</p> | |
| <p>Perl treats a hyphen as a literal if it appears before or after a POSIX class | |
| (see below) or before or after a character type escape such as <code class="regex rouge"><span class="pcre2-semantic">\d</span></code> or <code class="regex rouge"><span class="pcre2-semantic">\H</span></code>. | |
| However, unless the hyphen is the last character in the class, Perl outputs a | |
| warning in its warning mode, as this is most likely a user error. As PCRE2 has | |
| no facility for warning, an error is given in these cases.</p> | |
| <p>It is not possible to have the literal character <code class="regex rouge"><span class="pcre2-semantic">]</span></code> as the end character of a | |
| range. A pattern such as <code class="regex rouge"><span class="pcre2-semantic">[W-]46]</span></code> is interpreted as a class of two characters | |
| (<code>W</code> and <code>-</code>) followed by a literal string <code class="regex rouge"><span class="pcre2-semantic">46]</span></code>, so it would match <code class="subject rouge"><span class="pcre2-semantic">W46]</span></code> or | |
| <code class="subject rouge"><span class="pcre2-semantic">-46]</span></code>. However, if the <code class="regex rouge"><span class="pcre2-semantic">]</span></code> is escaped with a backslash it is interpreted as | |
| the end of a range, so <code class="regex rouge"><span class="pcre2-semantic">[W-\]46]</span></code> is interpreted as a class containing a range | |
| and two other characters. The octal or hexadecimal representation of <code class="regex rouge"><span class="pcre2-semantic">]</span></code> can | |
| also be used to end a range.</p> | |
| <p>Ranges normally include all code points between the start and end characters, | |
| inclusive. They can also be used for code points specified numerically, for | |
| example <code class="regex rouge"><span class="pcre2-semantic">[\000-\037]</span></code>. Ranges can include any characters that are valid for the | |
| current mode. In any UTF mode, the so-called "surrogate" characters (those | |
| whose code points lie between <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-66"><code class="character pcre2-api rouge"><span class="sc">0xd800</span></code><span class="character-card" id="pcre2-character-66" role="tooltip" aria-label="Surrogate code point (U+D800)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="Surrogate code point"></span><span class="character-codepoint" data-codepoint="U+D800"></span></span></span> and <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-67"><code class="character pcre2-api rouge"><span class="sc">0xdfff</span></code><span class="character-card" id="pcre2-character-67" role="tooltip" aria-label="Surrogate code point (U+DFFF)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="Surrogate code point"></span><span class="character-codepoint" data-codepoint="U+DFFF"></span></span></span> inclusive) may not be specified | |
| explicitly by default (the <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ALLOW_SURROGATE_ESCAPES</span></code> option disables | |
| this check). However, ranges such as <code class="regex rouge"><span class="pcre2-semantic">[\x{d7ff}-\x{e000}]</span></code>, which include the | |
| surrogates, are always permitted.</p> | |
| <p>If a range that includes letters is used when caseless matching is set, it | |
| matches the letters in either case. For example, <code class="regex rouge"><span class="pcre2-semantic">[W-c]</span></code> is equivalent to | |
| <code class="regex rouge"><span class="pcre2-semantic">[][\\^_`wxyzabc]</span></code>, matched caselessly, and in a non-UTF mode, if character | |
| tables for a French locale are in use, <code class="regex rouge"><span class="pcre2-semantic">[\xc8-\xcb]</span></code> matches accented E | |
| characters in both cases.</p> | |
| <p>A circumflex can conveniently be used with the upper case character types to | |
| specify a more restricted set of characters than the matching lower case type. | |
| For example, the class <code class="regex rouge"><span class="pcre2-semantic">[^\W_]</span></code> matches any letter or digit, but not underscore, | |
| whereas <code class="regex rouge"><span class="pcre2-semantic">[\w]</span></code> includes underscore. A positive character class should be read as | |
| "something OR something OR …" and a negative class as "NOT something AND NOT | |
| something AND NOT …".</p> | |
| <p>The metacharacters that are recognized in character classes are backslash, | |
| hyphen (when it can be interpreted as specifying a range), circumflex | |
| (only at the start), and the terminating closing square bracket. An opening | |
| square bracket is also special when it can be interpreted as introducing a | |
| POSIX class (see | |
| "Posix character classes" | |
| below), or a special compatibility feature (see | |
| "Compatibility feature for word boundaries" | |
| below. Escaping any non-alphanumeric character in a class turns it into a | |
| literal, whether or not it would otherwise be a metacharacter.</p></section> | |
| <section class="doc-section level-1"><h2 id="_perl_extended_character_classes">Perl extended character classes</h2><p>From release 10.45 PCRE2 supports Perl’s <code class="regex rouge"><span class="pcre2-semantic">(?[...])</span></code> extended character class | |
| syntax. This can be used to perform set operations such as intersection on | |
| character classes.</p> | |
| <p>The syntax permitted within <code class="regex rouge"><span class="pcre2-semantic">(?[...])</span></code> is quite different to ordinary character | |
| classes. Inside the extended class, there is an expression syntax consisting of | |
| "atoms", operators, and ordinary parentheses <code class="regex rouge"><span class="pcre2-semantic">()</span></code> used for grouping. Such | |
| classes always have the Perl <code class="regex rouge"><span class="pcre2-semantic">/xx</span></code> modifier (PCRE2 option <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED_MORE</span></code>) | |
| turned on within them. This means that literal space and tab characters are | |
| ignored everywhere in the class.</p> | |
| <p>The allowed atoms are individual characters specified by escape sequences such | |
| as <code class="regex rouge"><span class="pcre2-semantic">\n</span></code> or <code class="regex rouge"><span class="pcre2-semantic">\x{123}</span></code>, character types such as <code class="regex rouge"><span class="pcre2-semantic">\d</span></code>, POSIX classes such as | |
| <code class="regex rouge"><span class="pcre2-semantic">[:alpha:]</span></code>, and nested ordinary (non-extended) character classes. For example, | |
| in <code class="regex rouge"><span class="pcre2-semantic">(?[\d & [...]])</span></code> the nested class <code class="regex rouge"><span class="pcre2-semantic">[...]</span></code> follows the usual rules for ordinary | |
| character classes, in which parentheses are not metacharacters, and character | |
| literals and ranges are permitted.</p> | |
| <p>Character literals and ranges may not appear outside a nested ordinary | |
| character class because they are not atoms in the extended syntax. The extended | |
| syntax does not introduce any additional escape sequences, so <code class="regex rouge"><span class="pcre2-semantic">(?[\y])</span></code> is an | |
| unknown escape, as it would be in <code class="regex rouge"><span class="pcre2-semantic">[\y]</span></code>.</p> | |
| <p>In the extended syntax, <code class="regex rouge"><span class="pcre2-semantic">^</span></code> does not negate a class (except within an | |
| ordinary class nested inside an extended class); it is instead a binary | |
| operator.</p> | |
| <p>The binary operators are <code class="regex rouge"><span class="pcre2-semantic">&</span></code> (intersection), <code class="regex rouge"><span class="pcre2-semantic">|</span></code> or <code class="regex rouge"><span class="pcre2-semantic">+</span></code> (union), <code class="regex rouge"><span class="pcre2-semantic">-</span></code> | |
| (subtraction) and <code class="regex rouge"><span class="pcre2-semantic">^</span></code> (symmetric difference). These are left-associative and | |
| <code class="regex rouge"><span class="pcre2-semantic">&</span></code> has higher (tighter) precedence, while the others have equal lower precedence. | |
| The one prefix unary operator is <code class="regex rouge"><span class="pcre2-semantic">!</span></code> (complement), with highest | |
| precedence.</p></section> | |
| <section class="doc-section level-1"><h2 id="_uts18_extended_character_classes">UTS#18 extended character classes</h2><p>The <code class="constant pcre2-api rouge"><span class="no">PCRE2_ALT_EXTENDED_CLASS</span></code> option enables an alternative to Perl’s <code class="regex rouge"><span class="pcre2-semantic">(?[...])</span></code> | |
| syntax, allowing instead extended class behaviour inside ordinary <code class="regex rouge"><span class="pcre2-semantic">[...]</span></code> | |
| character classes. This altered syntax for <code class="regex rouge"><span class="pcre2-semantic">[...]</span></code> classes is loosely described | |
| by the Unicode standard UTS#18. The <code class="constant pcre2-api rouge"><span class="no">PCRE2_ALT_EXTENDED_CLASS</span></code> option does not | |
| prevent use of <code class="regex rouge"><span class="pcre2-semantic">(?[...])</span></code> classes; it just changes the meaning of all | |
| <code class="regex rouge"><span class="pcre2-semantic">[...]</span></code> classes that are not nested inside a Perl <code class="regex rouge"><span class="pcre2-semantic">(?[...])</span></code> class.</p> | |
| <p>Firstly, in ordinary Perl <code class="regex rouge"><span class="pcre2-semantic">[...]</span></code> syntax, an expression such as <code class="regex rouge"><span class="pcre2-semantic">[a[]</span></code> is a | |
| character class with two literal characters <code class="regex rouge"><span class="pcre2-semantic">a</span></code> and <code class="regex rouge"><span class="pcre2-semantic">[</span></code>, but in UTS#18 extended | |
| classes the "[" character becomes an additional metacharacter within classes, | |
| denoting the start of a nested class, so a literal <code class="regex rouge"><span class="pcre2-semantic">[</span></code> must be escaped as <code class="regex rouge"><span class="pcre2-semantic">\[</span></code>.</p> | |
| <p>Secondly, within the UTS#18 extended syntax, there are operators <code class="regex rouge"><span class="pcre2-semantic">||</span></code>, <code class="regex rouge"><span class="pcre2-semantic">&&</span></code>, | |
| <code class="regex rouge"><span class="pcre2-semantic">--</span></code> and <code class="regex rouge"><span class="pcre2-semantic">~~</span></code> which denote character class union, intersection, subtraction, | |
| and symmetric difference respectively. In standard Perl syntax, these would | |
| simply be needlessly-repeated literals (except for <code class="regex rouge"><span class="pcre2-semantic">--</span></code> which could be the | |
| start or end of a range). In UTS#18 extended classes these operators can be used | |
| in constructs such as <code class="regex rouge"><span class="pcre2-semantic">[\p{L}--[QW]]</span></code> for "Unicode letters, other than Q and W". | |
| A literal <code class="regex rouge"><span class="pcre2-semantic">-</span></code> at the start or end of a range must be escaped, so while | |
| <code class="regex rouge"><span class="pcre2-semantic">[--1]</span></code> in Perl syntax is the range from hyphen to 1, it must be | |
| escaped as <code class="regex rouge"><span class="pcre2-semantic">[\--1]</span></code> | |
| in UTS#18 extended classes.</p> | |
| <p>Unlike Perl’s <code class="regex rouge"><span class="pcre2-semantic">(?[...])</span></code> extended classes, the <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED_MORE</span></code> option to | |
| ignore space and tab characters is not automatically enabled for UTS#18 | |
| extended classes, but it is honoured if set.</p> | |
| <p>Extended UTS#18 classes can be nested, and nested classes are themselves | |
| extended classes (unlike Perl, where nested classes must be simple classes). | |
| For example, <code class="regex rouge"><span class="pcre2-semantic">[\p{L}&&[\p{Thai}||\p{Greek}]]</span></code> matches any letter that is in | |
| the Thai or Greek scripts. Note that this means that no special grouping | |
| characters (such as the parentheses used in Perl’s <code class="regex rouge"><span class="pcre2-semantic">(?[...])</span></code> class syntax) are | |
| needed.</p> | |
| <p>Individual class items (literal characters, literal ranges, properties such as | |
| <code class="regex rouge"><span class="pcre2-semantic">\d</span></code> or <code class="regex rouge"><span class="pcre2-semantic">\p{...}</span></code>, and nested classes) can be combined by juxtaposition or by an | |
| operator. Juxtaposition is the implicit union operator, and binds more tightly | |
| than any explicit operator. Thus a sequence of literals and/or ranges behaves | |
| as if it is enclosed in square brackets. For example, <code class="regex rouge"><span class="pcre2-semantic">[A-Z0-9&&[^E8]]</span></code> is the | |
| same as <code class="regex rouge"><span class="pcre2-semantic">[[A-Z0-9]&&[^E8]]</span></code>, which matches any upper case alphanumeric character | |
| except "E" or "8".</p> | |
| <p>Precedence between the explicit operators is not defined, so mixing operators | |
| is a syntax error. For example, <code class="regex rouge"><span class="pcre2-semantic">[A&&B--C]</span></code> is an error, but | |
| <code class="regex rouge"><span class="pcre2-semantic">[A&&[B--C]]</span></code> is valid.</p> | |
| <p>This is an emerging syntax which is being adopted gradually across the regex | |
| ecosystem: for example JavaScript adopted the <code class="regex rouge"><span class="pcre2-semantic">/v</span></code> flag in ECMAScript 2024; | |
| Python’s <code>re</code> module reserves the syntax for future use with a FutureWarning | |
| for unescaped use of <code class="regex rouge"><span class="pcre2-semantic">[</span></code> as a literal within character classes. Due to UTS#18 | |
| providing insufficient guidance, engines interpret the syntax differently. | |
| Rust’s <code>regex</code> crate and Python’s <code>regex</code> PyPi module both implement UTS#18 | |
| extended classes, but with slight incompatibilities (<code class="regex rouge"><span class="pcre2-semantic">[A||B&&C]</span></code> is parsed as | |
| <code class="regex rouge"><span class="pcre2-semantic">[A||[B&&C]]</span></code> in Python’s <code>regex</code> but as <code class="regex rouge"><span class="pcre2-semantic">[[A||B]&&C]</span></code> in Rust’s <code>regex</code>).</p> | |
| <p>PCRE2’s syntax adds syntax restrictions similar to ECMAScript’s <code class="regex rouge"><span class="pcre2-semantic">/v</span></code> flag, so | |
| that all the UTS#18 extended classes accepted as valid by PCRE2 have the | |
| property that they are interpreted either with the same behaviour, or as | |
| invalid, by all other major engines. Please file an issue if you are aware of | |
| cross-engine differences in behaviour between PCRE2 and another major engine.</p></section> | |
| <section class="doc-section level-1"><h2 id="_posix_character_classes">POSIX character classes</h2><p>Perl supports the POSIX notation for character classes. This uses names | |
| enclosed by <code class="regex rouge"><span class="pcre2-semantic">[:</span></code> and <code class="regex rouge"><span class="pcre2-semantic">:]</span></code> within the enclosing square brackets. PCRE2 also supports | |
| this notation, in both ordinary and extended classes. For example,</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">[01[:alpha:]%]</span></code></pre></div> | |
| <p>matches <code class="subject rouge"><span class="pcre2-semantic">0</span></code>, <code class="subject rouge"><span class="pcre2-semantic">1</span></code>, any alphabetic character, or <code class="subject rouge"><span class="pcre2-semantic">%</span></code>. The supported class names | |
| are:</p> | |
| <dl class="compact" style="--tab-width: 6"><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">[:alnum:]</span></code></span></dt><dd>Letters and digits.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">[:alpha:]</span></code></span></dt><dd>Letters.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">[:ascii:]</span></code></span></dt><dd>Character codes 0–127.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">[:blank:]</span></code></span></dt><dd>Space or tab only.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">[:cntrl:]</span></code></span></dt><dd>Control characters.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">[:digit:]</span></code></span></dt><dd>Decimal digits (same as <code class="regex rouge"><span class="pcre2-semantic">\d</span></code>).</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">[:graph:]</span></code></span></dt><dd>Printing characters, excluding space.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">[:lower:]</span></code></span></dt><dd>Lower case letters.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">[:print:]</span></code></span></dt><dd>Printing characters, including space.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">[:punct:]</span></code></span></dt><dd>Printing characters, excluding letters, digits, and space.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">[:space:]</span></code></span></dt><dd>White space (the same as <code class="regex rouge"><span class="pcre2-semantic">\s</span></code> from PCRE2 8.34).</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">[:upper:]</span></code></span></dt><dd>Upper case letters.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">[:word:]</span></code></span></dt><dd>"Word" characters (same as <code class="regex rouge"><span class="pcre2-semantic">\w</span></code>).</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">[:xdigit:]</span></code></span></dt><dd>Hexadecimal digits.</dd></div></dl> | |
| <p>The default "space" characters are HT (9), LF (10), VT (11), FF (12), CR (13), | |
| and space (32). If locale-specific matching is taking place, the list of space | |
| characters may be different; there may be fewer or more of them. "Space" and | |
| <code class="regex rouge"><span class="pcre2-semantic">\s</span></code> match the same set of characters, as do "word" and <code class="regex rouge"><span class="pcre2-semantic">\w</span></code>.</p> | |
| <p>The name "word" is a Perl extension, and "blank" is a GNU extension from Perl | |
| 5.8. Another Perl extension is negation, which is indicated by a ^ character | |
| after the colon. For example,</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">[12[:^digit:]]</span></code></pre></div> | |
| <p>matches <code class="subject rouge"><span class="pcre2-semantic">1</span></code>, <code class="subject rouge"><span class="pcre2-semantic">2</span></code>, or any non-digit. PCRE2 (and Perl) also recognize the POSIX | |
| syntax <code class="regex rouge"><span class="pcre2-semantic">[.ch.]</span></code> and <code class="regex rouge"><span class="pcre2-semantic">[=ch=]</span></code> where <code class="subject rouge"><span class="pcre2-semantic">ch</span></code> is a "collating element", but these are not | |
| supported, and an error is given if they are encountered.</p> | |
| <p>By default, characters with values greater than 127 do not match any of the | |
| POSIX character classes, although this may be different for characters in the | |
| range 128–255 when locale-specific matching is happening. However, in UCP mode, | |
| unless certain options are set (see below), some of the classes are changed so | |
| that Unicode character properties are used. This is achieved by replacing | |
| POSIX classes with other sequences, as follows:</p> | |
| <dl class="compact" style="--tab-width: 6"><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">[:alnum:]</span></code></span></dt><dd>Becomes <code class="regex rouge"><span class="pcre2-semantic">\p{Xan}</span></code></dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">[:alpha:]</span></code></span></dt><dd>Becomes <code class="regex rouge"><span class="pcre2-semantic">\p{L}</span></code></dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">[:blank:]</span></code></span></dt><dd>Becomes <code class="regex rouge"><span class="pcre2-semantic">\h</span></code></dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">[:cntrl:]</span></code></span></dt><dd>Becomes <code class="regex rouge"><span class="pcre2-semantic">\p{Cc}</span></code></dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">[:digit:]</span></code></span></dt><dd>Becomes <code class="regex rouge"><span class="pcre2-semantic">\p{Nd}</span></code></dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">[:lower:]</span></code></span></dt><dd>Becomes <code class="regex rouge"><span class="pcre2-semantic">\p{Ll}</span></code></dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">[:space:]</span></code></span></dt><dd>Becomes <code class="regex rouge"><span class="pcre2-semantic">\p{Xps}</span></code></dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">[:upper:]</span></code></span></dt><dd>Becomes <code class="regex rouge"><span class="pcre2-semantic">\p{Lu}</span></code></dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">[:word:]</span></code></span></dt><dd>Becomes <code class="regex rouge"><span class="pcre2-semantic">\p{Xwd}</span></code></dd></div></dl> | |
| <p>Negated versions, such as <code class="regex rouge"><span class="pcre2-semantic">[:^alpha:]</span></code> use <code class="regex rouge"><span class="pcre2-semantic">\P</span></code> instead of <code class="regex rouge"><span class="pcre2-semantic">\p</span></code>.</p> | |
| <p>Four other POSIX | |
| classes are handled specially in UCP mode:</p> | |
| <dl class="spaced" style="--tab-width: 6"><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">[:graph:]</span></code></span></dt><dd>This matches characters that have glyphs that mark the page when printed. In | |
| Unicode property terms, it matches all characters with the L, M, N, P, S, or Cf | |
| properties, except for:<dl class="compact" style="--tab-width: 12"><div class="dlist-item"><dt><span><span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-68"><code class="character pcre2-api rouge"><span class="sc">U+061C</span></code><span class="character-card" id="pcre2-character-68" role="tooltip" aria-label="ARABIC LETTER MARK (U+061C)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="ARABIC LETTER MARK"></span><span class="character-codepoint" data-codepoint="U+061C"></span></span></span></span></dt><dd>Arabic Letter Mark</dd></div><div class="dlist-item"><dt><span><span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-69"><code class="character pcre2-api rouge"><span class="sc">U+180E</span></code><span class="character-card" id="pcre2-character-69" role="tooltip" aria-label="MONGOLIAN VOWEL SEPARATOR (U+180E)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="MONGOLIAN VOWEL SEPARATOR"></span><span class="character-codepoint" data-codepoint="U+180E"></span></span></span></span></dt><dd>Mongolian Vowel Separator</dd></div><div class="dlist-item"><dt><span><span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-70"><code class="character pcre2-api rouge"><span class="sc">U+2066</span></code><span class="character-card" id="pcre2-character-70" role="tooltip" aria-label="LEFT-TO-RIGHT ISOLATE (U+2066)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="LEFT-TO-RIGHT ISOLATE"></span><span class="character-codepoint" data-codepoint="U+2066"></span></span></span>–<span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-71"><code class="character pcre2-api rouge"><span class="sc">U+2069</span></code><span class="character-card" id="pcre2-character-71" role="tooltip" aria-label="POP DIRECTIONAL ISOLATE (U+2069)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="POP DIRECTIONAL ISOLATE"></span><span class="character-codepoint" data-codepoint="U+2069"></span></span></span></span></dt><dd>Various "isolates"</dd></div></dl></dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">[:print:]</span></code></span></dt><dd>This matches the same characters as <code class="regex rouge"><span class="pcre2-semantic">[:graph:]</span></code> plus space characters that are | |
| not controls, that is, characters with the Zs property.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">[:punct:]</span></code></span></dt><dd>This matches all characters that have the Unicode P (punctuation) property, | |
| plus those characters with code points less than 256 that have the S (Symbol) | |
| property.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">[:xdigit:]</span></code></span></dt><dd>In addition to the ASCII hexadecimal digits, this also matches the "fullwidth" | |
| versions of those characters, whose Unicode code points start at <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-72"><code class="character pcre2-api rouge"><span class="sc">U+FF10</span></code><span class="character-card" id="pcre2-character-72" role="tooltip" aria-label="FULLWIDTH DIGIT ZERO (U+FF10)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character="0"></span><span class="character-name" data-character-name="FULLWIDTH DIGIT ZERO"></span><span class="character-codepoint" data-codepoint="U+FF10"></span></span></span>. This | |
| is a change that was made in PCRE2 release 10.43 for Perl compatibility.</dd></div></dl> | |
| <p>The other POSIX classes are unchanged by <code class="constant pcre2-api rouge"><span class="no">PCRE2_UCP</span></code>, and match only characters | |
| with code points less than 256.</p> | |
| <p>There are two options that can be used to restrict the POSIX classes to ASCII | |
| characters when <code class="constant pcre2-api rouge"><span class="no">PCRE2_UCP</span></code> is set. The option <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ASCII_DIGIT</span></code> affects | |
| just <code class="regex rouge"><span class="pcre2-semantic">[:digit:]</span></code> and <code class="regex rouge"><span class="pcre2-semantic">[:xdigit:]</span></code>. Within a pattern, this can be set and unset by | |
| <code class="regex rouge"><span class="pcre2-semantic">(?aT)</span></code> and <code class="regex rouge"><span class="pcre2-semantic">(?-aT)</span></code>. The <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ASCII_POSIX</span></code> option disables UCP processing | |
| for all POSIX classes, including <code class="regex rouge"><span class="pcre2-semantic">[:digit:]</span></code> and <code class="regex rouge"><span class="pcre2-semantic">[:xdigit:]</span></code>. Within a pattern, | |
| <code class="regex rouge"><span class="pcre2-semantic">(?aP)</span></code> and <code class="regex rouge"><span class="pcre2-semantic">(?-aP)</span></code> set and unset both these options for consistency.</p></section> | |
| <section class="doc-section level-1"><h2 id="_compatibility_feature_for_word_boundaries">Compatibility feature for word boundaries</h2><p>In the POSIX.2 compliant library that was included in 4.4BSD Unix, the ugly | |
| syntax [[:<:]] and [[:>:]] is used for matching "start of word" and "end of | |
| word". PCRE2 treats these items as follows:</p> | |
| <dl class="compact" style="--tab-width: 6"><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">[[:<:]]</span></code></span></dt><dd>Is converted to <code class="regex rouge"><span class="pcre2-semantic">\b(?=\w)</span></code>.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">[[:>:]]</span></code></span></dt><dd>Is converted to <code class="regex rouge"><span class="pcre2-semantic">\b(?<=\w)</span></code>.</dd></div></dl> | |
| <p>Only these exact character sequences are recognized. A sequence such as | |
| [a[:<:]b] provokes error for an unrecognized POSIX class name. This support is | |
| not compatible with Perl. It is provided to help migrations from other | |
| environments, and is best not used in any new patterns. Note that <code class="regex rouge"><span class="pcre2-semantic">\b</span></code> matches | |
| at the start and the end of a word (see | |
| "Simple assertions" | |
| above), and in a Perl-style pattern the preceding or following character | |
| normally shows which is wanted, without the need for the assertions that are | |
| used above in order to give exactly the POSIX behaviour. Note also that the | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_UCP</span></code> option changes the meaning of <code class="regex rouge"><span class="pcre2-semantic">\w</span></code> (and therefore <code class="regex rouge"><span class="pcre2-semantic">\b</span></code>) by default, so | |
| it also affects these POSIX sequences.</p></section> | |
| <section class="doc-section level-1"><h2 id="_vertical_bar_pipe">Vertical bar (pipe)</h2><p>Vertical bar characters are used to separate alternative patterns. For example, | |
| the pattern</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">gilbert|sullivan</span></code></pre></div> | |
| <p>matches either <code class="subject rouge"><span class="pcre2-semantic">gilbert</span></code> or <code class="subject rouge"><span class="pcre2-semantic">sullivan</span></code>. Any number of alternatives may appear, | |
| and an empty alternative is permitted (matching the empty string). The matching | |
| process tries each alternative in turn, from left to right, and the first one | |
| that succeeds is used. If the alternatives are within a group | |
| (defined below), | |
| "succeeds" means matching the rest of the main pattern as well as the | |
| alternative in the group.</p></section> | |
| <section class="doc-section level-1"><h2 id="internal-option-setting">Internal option setting</h2><p>The settings of several options can be changed within a pattern by a sequence | |
| of letters enclosed between <code class="regex rouge"><span class="pcre2-semantic">(?</span></code> and <code class="regex rouge"><span class="pcre2-semantic">)</span></code>. The following are Perl-compatible, | |
| and are described in detail in the | |
| <a href="./pcre2api.html"><code>pcre2api</code></a> | |
| documentation. The option letters are:</p> | |
| <dl class="compact" style="--tab-width: 4"><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">i</span></code></span></dt><dd>For <code class="constant pcre2-api rouge"><span class="no">PCRE2_CASELESS</span></code></dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">m</span></code></span></dt><dd>For <code class="constant pcre2-api rouge"><span class="no">PCRE2_MULTILINE</span></code></dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">n</span></code></span></dt><dd>For <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_AUTO_CAPTURE</span></code></dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">s</span></code></span></dt><dd>For <code class="constant pcre2-api rouge"><span class="no">PCRE2_DOTALL</span></code></dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">x</span></code></span></dt><dd>For <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED</span></code></dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">xx</span></code></span></dt><dd>For <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED_MORE</span></code></dd></div></dl> | |
| <p>For example, <code class="regex rouge"><span class="pcre2-semantic">(?im)</span></code> sets caseless, multiline matching. It is also possible to | |
| unset these options by preceding the relevant letters with a hyphen, for | |
| example <code class="regex rouge"><span class="pcre2-semantic">(?-im)</span></code>. The two "extended" options are not independent; unsetting | |
| either one cancels the effects of both of them.</p> | |
| <p>A combined setting and unsetting such as <code class="regex rouge"><span class="pcre2-semantic">(?im-sx)</span></code>, which sets <code class="constant pcre2-api rouge"><span class="no">PCRE2_CASELESS</span></code> | |
| and <code class="constant pcre2-api rouge"><span class="no">PCRE2_MULTILINE</span></code> while unsetting <code class="constant pcre2-api rouge"><span class="no">PCRE2_DOTALL</span></code> and <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED</span></code>, is also | |
| permitted. Only one hyphen may appear in the options string. If a letter | |
| appears both before and after the hyphen, the option is unset. An empty options | |
| setting <code class="regex rouge"><span class="pcre2-semantic">(?)</span></code> is allowed. Needless to say, it has no effect.</p> | |
| <p>If the first character following <code class="regex rouge"><span class="pcre2-semantic">(?</span></code> is a circumflex, it causes all of the above | |
| options to be unset. Letters may follow the circumflex to cause some options to | |
| be re-instated, but a hyphen may not appear.</p> | |
| <p>Some PCRE2-specific options can be changed by the same mechanism using these | |
| pairs or individual letters:</p> | |
| <dl class="compact" style="--tab-width: 4"><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">aD</span></code></span></dt><dd>For <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ASCII_BSD</span></code></dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">aS</span></code></span></dt><dd>For <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ASCII_BSS</span></code></dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">aW</span></code></span></dt><dd>For <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ASCII_BSW</span></code></dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">aP</span></code></span></dt><dd>For <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ASCII_POSIX</span></code> and <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ASCII_DIGIT</span></code></dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">aT</span></code></span></dt><dd>For <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ASCII_DIGIT</span></code></dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">r</span></code></span></dt><dd>For <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_CASELESS_RESTRICT</span></code></dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">J</span></code></span></dt><dd>For <code class="constant pcre2-api rouge"><span class="no">PCRE2_DUPNAMES</span></code></dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">U</span></code></span></dt><dd>For <code class="constant pcre2-api rouge"><span class="no">PCRE2_UNGREEDY</span></code></dd></div></dl> | |
| <p>However, except for <code class="regex rouge"><span class="pcre2-semantic">r</span></code>, these are not unset by <code class="regex rouge"><span class="pcre2-semantic">(?^)</span></code>, which is equivalent to | |
| <code class="regex rouge"><span class="pcre2-semantic">(?-imnrsx)</span></code>. If <code class="regex rouge"><span class="pcre2-semantic">a</span></code> is not followed by any of the upper case letters shown | |
| above, it sets (or unsets) all the ASCII options.</p> | |
| <p><code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ASCII_DIGIT</span></code> has no additional effect when <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_ASCII_POSIX</span></code> | |
| is set, but including it in <code class="regex rouge"><span class="pcre2-semantic">(?aP)</span></code> means that <code class="regex rouge"><span class="pcre2-semantic">(?-aP)</span></code> suppresses all ASCII | |
| restrictions for POSIX classes.</p> | |
| <p>When one of these option changes occurs at top level (that is, not inside group | |
| parentheses), the change applies until a subsequent change, or the end of the | |
| pattern. An option change within a group (see below for a description of | |
| groups) affects only that part of the group that follows it. At the end of the | |
| group these options are reset to the state they were before the group. For | |
| example,</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(a(?i)b)c</span></code></pre></div> | |
| <p>matches <code class="subject rouge"><span class="pcre2-semantic">abc</span></code> and <code class="subject rouge"><span class="pcre2-semantic">aBc</span></code> and no other strings (assuming <code class="constant pcre2-api rouge"><span class="no">PCRE2_CASELESS</span></code> is not set | |
| externally). Any changes made in one alternative do carry on into subsequent | |
| branches within the same group. For example,</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(a(?i)b|c)</span></code></pre></div> | |
| <p>matches <code class="subject rouge"><span class="pcre2-semantic">ab</span></code>, <code class="subject rouge"><span class="pcre2-semantic">aB</span></code>, <code class="subject rouge"><span class="pcre2-semantic">c</span></code>, and <code class="subject rouge"><span class="pcre2-semantic">C</span></code>, even though when matching <code class="subject rouge"><span class="pcre2-semantic">C</span></code> the first | |
| branch is abandoned before the option setting. This is because the effects of | |
| option settings happen at compile time. There would be some very weird | |
| behaviour otherwise.</p> | |
| <p>As a convenient shorthand, if any option settings are required at the start of | |
| a non-capturing group (see the section <a href="#groups">Groups</a>), the option letters may | |
| appear between the <code class="regex rouge"><span class="pcre2-semantic">?</span></code> and the <code class="regex rouge"><span class="pcre2-semantic">:</span></code>. Thus the two patterns</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?i:saturday|sunday) | |
| (?:(?i)saturday|sunday)</span></code></pre></div> | |
| <p>match exactly the same set of strings. Because alternative branches are tried | |
| from left to right, and options are not reset until the end of the group is | |
| reached, an option setting in one branch does affect subsequent branches, so | |
| the above patterns match <code class="subject rouge"><span class="pcre2-semantic">SUNDAY</span></code> as well as <code class="subject rouge"><span class="pcre2-semantic">Saturday</span></code>.</p> | |
| <aside class="admonition-block note" role="note"><h6 class="block-title label-only"><span class="title-label">Note: </span></h6><p>There are other PCRE2-specific options, applying to the whole | |
| pattern, which can be set by the application when the compiling function is | |
| called. In addition, the pattern can contain special leading sequences such as | |
| <code class="regex rouge"><span class="pcre2-semantic">(*CRLF)</span></code> to override what the application has set or what has been defaulted. | |
| Details are given in the section <a href="#newline-sequences">Newline sequences</a> | |
| above. There are also the <code class="regex rouge"><span class="pcre2-semantic">(*UTF)</span></code> and <code class="regex rouge"><span class="pcre2-semantic">(*UCP)</span></code> leading sequences that can be used | |
| to set UTF and Unicode property modes; they are equivalent to setting 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, respectively. However, the application can set | |
| the <code class="constant pcre2-api rouge"><span class="no">PCRE2_NEVER_UTF</span></code> or <code class="constant pcre2-api rouge"><span class="no">PCRE2_NEVER_UCP</span></code> options, which lock out the use of the | |
| <code class="regex rouge"><span class="pcre2-semantic">(*UTF)</span></code> and <code class="regex rouge"><span class="pcre2-semantic">(*UCP)</span></code> sequences.</p></aside></section> | |
| <section class="doc-section level-1"><h2 id="groups">Groups</h2><p>Groups are delimited by parentheses (round brackets), which can be nested. | |
| Turning part of a pattern into a group does two things:</p> | |
| <ol class="arabic spaced"><li><p>It localizes a set of alternatives. For example, the pattern</p><div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">cat(aract|erpillar|)</span></code></pre></div> | |
| <p>matches <code class="subject rouge"><span class="pcre2-semantic">cataract</span></code>, <code class="subject rouge"><span class="pcre2-semantic">caterpillar</span></code>, or <code class="subject rouge"><span class="pcre2-semantic">cat</span></code>. Without the parentheses, it would | |
| match <code class="subject rouge"><span class="pcre2-semantic">cataract</span></code>, <code class="subject rouge"><span class="pcre2-semantic">erpillar</span></code> or an empty string.</p></li><li><p>It creates a "capture group". This means that, when the whole pattern | |
| matches, the portion of the subject string that matched the group is passed | |
| back to the caller, separately from the portion that matched the whole pattern. | |
| (This applies only to the traditional matching function; the DFA matching | |
| function does not support capturing.)</p><p>Opening parentheses are counted from left to right (starting from 1) to obtain | |
| numbers for capture groups. For example, if the string <code class="subject rouge"><span class="pcre2-semantic">the red king</span></code> is | |
| matched against the pattern</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">the ((red|white) (king|queen))</span></code></pre></div> | |
| <p>the captured substrings are <code class="subject rouge"><span class="pcre2-semantic">red king</span></code>, <code class="subject rouge"><span class="pcre2-semantic">red</span></code>, and <code class="subject rouge"><span class="pcre2-semantic">king</span></code>, and are numbered 1, | |
| 2, and 3, respectively.</p></li></ol> | |
| <p>The fact that plain parentheses fulfil two functions is not always helpful. | |
| There are often times when grouping is required without capturing. If an | |
| opening parenthesis is followed by a question mark and a colon, the group | |
| does not do any capturing, and is not counted when computing the number of any | |
| subsequent capture groups. For example, if the string <code class="subject rouge"><span class="pcre2-semantic">the white queen</span></code> | |
| is matched against the pattern</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">the ((?:red|white) (king|queen))</span></code></pre></div> | |
| <p>the captured substrings are <code class="subject rouge"><span class="pcre2-semantic">white queen</span></code> and <code class="subject rouge"><span class="pcre2-semantic">queen</span></code>, and are numbered 1 and 2. The maximum number of capture groups is 65,535.</p> | |
| <p>As a convenient shorthand, if any option settings are required at the start of | |
| a non-capturing group, the option letters may appear between the <code class="regex rouge"><span class="pcre2-semantic">?</span></code> and the | |
| <code class="regex rouge"><span class="pcre2-semantic">:</span></code> (see the section <a href="#groups">Groups</a>).</p></section> | |
| <section class="doc-section level-1"><h2 id="duplicate-group-numbers">Duplicate group numbers</h2><p>Perl 5.10 introduced a feature whereby each alternative in a group uses the | |
| same numbers for its capturing parentheses. Such a group starts with <code class="regex rouge"><span class="pcre2-semantic">(?|</span></code> and is | |
| itself a non-capturing group. For example, consider this pattern:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?|(Sat)ur|(Sun))day</span></code></pre></div> | |
| <p>Because the two alternatives are inside a <code class="regex rouge"><span class="pcre2-semantic">(?|</span></code> group, both sets of capturing | |
| parentheses are numbered one. Thus, when the pattern matches, you can look | |
| at captured substring number one, whichever alternative matched. This construct | |
| is useful when you want to capture part, but not all, of one of a number of | |
| alternatives. Inside a <code class="regex rouge"><span class="pcre2-semantic">(?|</span></code> group, parentheses are numbered as usual, but the | |
| number is reset at the start of each branch. The numbers of any capturing | |
| parentheses that follow the whole group start after the highest number used in | |
| any branch. The following example is taken from the Perl documentation. The | |
| numbers underneath show in which buffer the captured content will be stored.</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="text"># before ---------------branch-reset----------- after | |
| / ( a ) (?| x ( y ) z | (p (q) r) | (t) u (v) ) ( z ) /x | |
| # 1 2 2 3 2 3 4</code></pre></div> | |
| <p>A backreference to a capture group uses the most recent value that is set for | |
| the group. The following pattern matches <code class="subject rouge"><span class="pcre2-semantic">abcabc</span></code> or <code class="subject rouge"><span class="pcre2-semantic">defdef</span></code>:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?|(abc)|(def))\1</span></code></pre></div> | |
| <p>In contrast, a subroutine call to a capture group always refers to the | |
| first one in the pattern with the given number. The following pattern matches | |
| <code class="subject rouge"><span class="pcre2-semantic">abcabc</span></code> or <code class="subject rouge"><span class="pcre2-semantic">defabc</span></code>:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?|(abc)|(def))(?1)</span></code></pre></div> | |
| <p>A relative reference such as <code class="regex rouge"><span class="pcre2-semantic">(?-1)</span></code> is no different: it is just a convenient way | |
| of computing an absolute group number.</p> | |
| <p>If a | |
| condition test | |
| for a group’s having matched refers to a non-unique number, the test is | |
| true if any group with that number has matched.</p> | |
| <p>An alternative approach to using this "branch reset" feature is to use | |
| duplicate named groups, as described in the section <a href="#named-capture-groups">Named capture groups</a>.</p></section> | |
| <section class="doc-section level-1"><h2 id="named-capture-groups">Named capture groups</h2><p>Identifying capture groups by number is simple, but it can be very hard to keep | |
| track of the numbers in complicated patterns. Furthermore, if an expression is | |
| modified, the numbers may change. To help with this difficulty, PCRE2 supports | |
| the naming of capture groups. This feature was not added to Perl until release | |
| 5.10. Python had the feature earlier, and PCRE1 introduced it at release 4.0, | |
| using the Python syntax. PCRE2 supports both the Perl and the Python syntax.</p> | |
| <p>In PCRE2, a capture group can be named in one of three ways: <code class="regex rouge"><span class="pcre2-semantic">(?<<em>name</em>>…)</span></code> or | |
| <code class="regex rouge"><span class="pcre2-semantic">(?'<em>name</em>'…)</span></code> as in Perl, or <code class="regex rouge"><span class="pcre2-semantic">(?P<<em>name</em>>…)</span></code> as in Python. Names may be up to | |
| 128 code units long. When <code class="constant pcre2-api rouge"><span class="no">PCRE2_UTF</span></code> is not set, they may contain only ASCII | |
| alphanumeric characters and underscores, but must start with a non-digit. When | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_UTF</span></code> is set, the syntax of group names is extended to allow any Unicode | |
| letter or Unicode decimal digit. In other words, group names must match one of | |
| these patterns:</p> | |
| <dl class="compact" style="--tab-width: 4"><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">^[_A-Za-z][_A-Za-z0-9]*\z</span></code> </span></dt><dd>when <code class="constant pcre2-api rouge"><span class="no">PCRE2_UTF</span></code> is not set</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">^[<em>\p{L}][</em>\p{L}\p{Nd}]*\z</span></code> </span></dt><dd>when <code class="constant pcre2-api rouge"><span class="no">PCRE2_UTF</span></code> is set</dd></div></dl> | |
| <p>References to capture groups from other parts of the pattern, such as | |
| backreferences, | |
| recursion, | |
| and | |
| conditions, | |
| can all be made by name as well as by number.</p> | |
| <p>Named capture groups are allocated numbers as well as names, exactly as | |
| if the names were not present. In both PCRE2 and Perl, capture groups | |
| are primarily identified by numbers; any names are just aliases for these | |
| numbers. The PCRE2 API provides function calls for extracting the complete | |
| name-to-number translation table from a compiled pattern, as well as | |
| convenience functions for extracting captured substrings by name.</p> | |
| <p>Warning: When more than one capture group has the same number, as | |
| described in the section <a href="#duplicate-group-numbers">Duplicate group numbers</a>, a name given to one of them applies to all | |
| of them. Perl allows identically numbered groups to have different names. | |
| Consider this pattern, where there are two capture groups, both numbered 1:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?|(?<AA>aa)|(?<BB>bb))</span></code></pre></div> | |
| <p>Perl allows this, with both names AA and BB as aliases of group 1. Thus, after | |
| a successful match, both names yield the same value (either <code class="subject rouge"><span class="pcre2-semantic">aa</span></code> or <code class="subject rouge"><span class="pcre2-semantic">bb</span></code>).</p> | |
| <p>In an attempt to reduce confusion, PCRE2 does not allow the same group number | |
| to be associated with more than one name. The example above provokes a | |
| compile-time error. However, there is still scope for confusion. Consider this | |
| pattern:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?|(?<AA>aa)|(bb))</span></code></pre></div> | |
| <p>Although the second group number 1 is not explicitly named, the name AA is | |
| still an alias for any group 1. Whether the pattern matches <code class="subject rouge"><span class="pcre2-semantic">aa</span></code> or <code class="subject rouge"><span class="pcre2-semantic">bb</span></code>, a | |
| reference by name to group AA yields the matched string.</p> | |
| <p>By default, a name must be unique within a pattern, except that duplicate names | |
| are permitted for groups with the same number, for example:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?|(?<AA>aa)|(?<AA>bb))</span></code></pre></div> | |
| <p>The duplicate name constraint can be disabled by setting the <code class="constant pcre2-api rouge"><span class="no">PCRE2_DUPNAMES</span></code> | |
| option at compile time, or by the use of <code class="regex rouge"><span class="pcre2-semantic">(?J)</span></code> within the pattern, as described | |
| in the section <a href="#internal-option-setting">Internal option setting</a> | |
| above.</p> | |
| <p>Duplicate names can be useful for patterns where only one instance of the named | |
| capture group can match. Suppose you want to match the name of a weekday, | |
| either as a 3-letter abbreviation or as the full name, and in both cases you | |
| want to extract the abbreviation. This pattern (ignoring the line breaks) does | |
| the job:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?J) | |
| (?<DN>Mon|Fri|Sun)(?:day)?| | |
| (?<DN>Tue)(?:sday)?| | |
| (?<DN>Wed)(?:nesday)?| | |
| (?<DN>Thu)(?:rsday)?| | |
| (?<DN>Sat)(?:urday)?</span></code></pre></div> | |
| <p>There are five capture groups, but only one is ever set after a match. The | |
| convenience functions for extracting the data by name returns the substring for | |
| the first (and in this example, the only) group of that name that matched. This | |
| saves searching to find which numbered group it was. (An alternative way of | |
| solving this problem is to use a "branch reset" group, as described in the | |
| section <a href="#duplicate-group-numbers">Duplicate group numbers</a>.)</p> | |
| <p>If you make a backreference to a non-unique named group from elsewhere in the | |
| pattern, the groups to which the name refers are checked in the order in which | |
| they appear in the overall pattern. The first one that is set is used for the | |
| reference. For example, this pattern matches both <code class="subject rouge"><span class="pcre2-semantic">foofoo</span></code> and <code class="subject rouge"><span class="pcre2-semantic">barbar</span></code> but not | |
| <code class="subject rouge"><span class="pcre2-semantic">foobar</span></code> or <code class="subject rouge"><span class="pcre2-semantic">barfoo</span></code>:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?J)(?:(?<n>foo)|(?<n>bar))\k<n></span></code></pre></div> | |
| <p>If you make a subroutine call to a non-unique named group, the one that | |
| corresponds to the first occurrence of the name is used. In the absence of | |
| duplicate numbers this is the one with the lowest number.</p> | |
| <p>If you use a named reference in a condition | |
| test (see the | |
| section <a href="#conditional-groups">Conditional groups</a> | |
| below), either to check whether a capture group has matched, or to check for | |
| recursion, all groups with the same name are tested. If the condition is true | |
| for any one of them, the overall condition is true. This is the same behaviour | |
| as testing by number. For further details of the interfaces for handling named | |
| capture groups, see the | |
| <a href="./pcre2api.html"><code>pcre2api</code></a> | |
| documentation.</p></section> | |
| <section class="doc-section level-1"><h2 id="_repetition">Repetition</h2><p>Repetition is specified by quantifiers, which may follow any one of these | |
| items:</p> | |
| <ul class="compact"><li>a literal data character</li><li>the dot metacharacter</li><li>the <code class="regex rouge"><span class="pcre2-semantic">\C</span></code> escape sequence</li><li>the <code class="regex rouge"><span class="pcre2-semantic">\R</span></code> escape sequence</li><li>the <code class="regex rouge"><span class="pcre2-semantic">\X</span></code> escape sequence</li><li>any escape sequence that matches a single character</li><li>a character class</li><li>a backreference</li><li>a parenthesized group (including lookaround assertions)</li><li>a subroutine call (recursive or otherwise)</li></ul> | |
| <p>If a quantifier does not follow a repeatable item, an error occurs. The | |
| general repetition quantifier specifies a minimum and maximum number of | |
| permitted matches by giving two numbers in curly brackets (braces), separated | |
| by a comma. The numbers must be no greater than 65,535, and the first must be less | |
| than or equal to the second. For example,</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">z{2,4}</span></code></pre></div> | |
| <p>matches <code class="subject rouge"><span class="pcre2-semantic">zz</span></code>, <code class="subject rouge"><span class="pcre2-semantic">zzz</span></code>, or <code class="subject rouge"><span class="pcre2-semantic">zzzz</span></code>. A closing brace on its own is not a special | |
| character. If the second number is omitted, but the comma is present, there is | |
| no upper limit; if the second number and the comma are both omitted, the | |
| quantifier specifies an exact number of required matches. Thus</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">[aeiou]{3,}</span></code></pre></div> | |
| <p>matches at least 3 successive vowels, but may match many more, whereas</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">\d{8}</span></code></pre></div> | |
| <p>matches exactly 8 digits. If the first number is omitted, the lower limit is | |
| taken as zero; in this case the upper limit must be present.</p> | |
| <p><code class="regex rouge"><span class="pcre2-semantic">X{,4}</span></code> is interpreted as <code class="regex rouge"><span class="pcre2-semantic">X{0,4}</span></code>.</p> | |
| <p>This is a change in behaviour that happened in Perl 5.34.0 and PCRE2 10.43. In | |
| earlier versions such a sequence was not interpreted as a quantifier. Other | |
| regular expression engines may behave either way.</p> | |
| <p>If the characters that follow an opening brace do not match the syntax of a | |
| quantifier, the brace is taken as a literal character. In particular, this | |
| means that <code class="regex rouge"><span class="pcre2-semantic">{,}</span></code> is a literal string of three characters.</p> | |
| <p>Note that not every opening brace is potentially the start of a quantifier | |
| because braces are used in other items such as <code class="regex rouge"><span class="pcre2-semantic">\N{U+345}</span></code> or <code class="regex rouge"><span class="pcre2-semantic">\k{<em>name</em>}</span></code>.</p> | |
| <p>In UTF modes, quantifiers apply to characters rather than to individual code | |
| units. Thus, for example, <code class="regex rouge"><span class="pcre2-semantic">\x{100}{2}</span></code> matches two characters, each of | |
| which is represented by a two-byte sequence in a UTF-8 string. Similarly, | |
| <code class="regex rouge"><span class="pcre2-semantic">\X{3}</span></code> matches three Unicode extended grapheme clusters, each of which may be | |
| several code units long (and they may be of different lengths).</p> | |
| <p>The quantifier <code class="regex rouge"><span class="pcre2-semantic">{0}</span></code> is permitted, causing the expression to behave as if the | |
| previous item and the quantifier were not present. This may be useful for | |
| capture groups that are referenced as | |
| subroutines | |
| from elsewhere in the pattern (but see also the section | |
| <a href="#defining-capture-groups">Defining capture groups for use by reference only</a> | |
| below). Except for parenthesized groups, items that have a <code class="regex rouge"><span class="pcre2-semantic">{0}</span></code> quantifier are | |
| omitted from the compiled pattern.</p> | |
| <p>For convenience, the three most common quantifiers have single-character | |
| abbreviations:</p> | |
| <dl class="compact" style="--tab-width: 4"><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">*</span></code></span></dt><dd>Is equivalent to <code class="regex rouge"><span class="pcre2-semantic">{0,}</span></code>.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">+</span></code></span></dt><dd>Is equivalent to <code class="regex rouge"><span class="pcre2-semantic">{1,}</span></code>.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">?</span></code></span></dt><dd>Is equivalent to <code class="regex rouge"><span class="pcre2-semantic">{0,1}</span></code>.</dd></div></dl> | |
| <p>It is possible to construct infinite loops by following a group that can match | |
| no characters with a quantifier that has no upper limit, for example:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(a?)*</span></code></pre></div> | |
| <p>Earlier versions of Perl and PCRE1 used to give an error at compile time for | |
| such patterns. However, because there are cases where this can be useful, such | |
| patterns are now accepted, but whenever an iteration of such a group matches no | |
| characters, matching moves on to the next item in the pattern instead of | |
| repeatedly matching an empty string. This does not prevent backtracking into | |
| any of the iterations if a subsequent item fails to match.</p> | |
| <p>By default, quantifiers are "greedy", that is, they match as much as possible | |
| (up to the maximum number of permitted repetitions), without causing the rest | |
| of the pattern to fail. The classic example of where this gives problems is in | |
| trying to match comments in C programs. These appear between <code class="c rouge" data-lang="c"><span class="o">/</span><span class="p">*</span></code> and <code class="c rouge" data-lang="c"><span class="err">*/</span></code> and | |
| within the comment, individual <code>*</code> and <code>/</code> characters may appear. An attempt to | |
| match C comments by applying the pattern</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">/\*.*\*/</span></code></pre></div> | |
| <p>to the string</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="text">/* first comment */ not comment /* second comment */</code></pre></div> | |
| <p>fails, because it matches the entire string owing to the greediness of the <code class="regex rouge"><span class="pcre2-semantic">.*</span></code> | |
| item. However, if a quantifier is followed by a question mark, it ceases to be | |
| greedy, and instead matches the minimum number of times possible, so the | |
| pattern</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">/\*.*?\*/</span></code></pre></div> | |
| <p>does the right thing with C comments. The meaning of the various quantifiers is | |
| not otherwise changed, just the preferred number of matches. Do not confuse | |
| this use of question mark with its use as a quantifier in its own right. | |
| Because it has two uses, it can sometimes appear doubled, as in</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">\d??\d</span></code></pre></div> | |
| <p>which matches one digit by preference, but can match two if that is the only | |
| way the rest of the pattern matches.</p> | |
| <p>If the <code class="constant pcre2-api rouge"><span class="no">PCRE2_UNGREEDY</span></code> option is set (an option that is not available in Perl), | |
| the quantifiers are not greedy by default, but individual ones can be made | |
| greedy by following them with a question mark. In other words, it inverts the | |
| default behaviour.</p> | |
| <p>When a parenthesized group is quantified with a minimum repeat count that | |
| is greater than 1 or with a limited maximum, more memory is required for the | |
| compiled pattern, in proportion to the size of the minimum or maximum.</p> | |
| <p>If a pattern starts with <code class="regex rouge"><span class="pcre2-semantic">.*</span></code> or <code class="regex rouge"><span class="pcre2-semantic">.{0,}</span></code> and the <code class="constant pcre2-api rouge"><span class="no">PCRE2_DOTALL</span></code> option (equivalent | |
| to Perl’s <code class="regex rouge"><span class="pcre2-semantic">/s</span></code>) is set, thus allowing the dot to match newlines, the pattern is | |
| implicitly anchored, because whatever follows will be tried against every | |
| character position in the subject string, so there is no point in retrying the | |
| overall match at any position after the first. PCRE2 normally treats such a | |
| pattern as though it were preceded by <code class="regex rouge"><span class="pcre2-semantic">\A</span></code>.</p> | |
| <p>In cases where it is known that the subject string contains no newlines, it is | |
| worth setting <code class="constant pcre2-api rouge"><span class="no">PCRE2_DOTALL</span></code> in order to obtain this optimization, or | |
| alternatively, using <code class="regex rouge"><span class="pcre2-semantic">^</span></code> to indicate anchoring explicitly.</p> | |
| <p>However, there are some cases where the optimization cannot be used. When <code class="regex rouge"><span class="pcre2-semantic">.*</span></code> | |
| is inside capturing parentheses that are the subject of a backreference | |
| elsewhere in the pattern, a match at the start may fail where a later one | |
| succeeds. Consider, for example:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(.*)abc\1</span></code></pre></div> | |
| <p>If the subject is <code class="subject rouge"><span class="pcre2-semantic">xyz123abc123</span></code> the match point is the fourth character. For | |
| this reason, such a pattern is not implicitly anchored.</p> | |
| <p>Another case where implicit anchoring is not applied is when the leading <code class="regex rouge"><span class="pcre2-semantic">.*</span></code> is | |
| inside an atomic group. Once again, a match at the start may fail where a later | |
| one succeeds. Consider this pattern:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?>.*?a)b</span></code></pre></div> | |
| <p>It matches <code class="subject rouge"><span class="pcre2-semantic">ab</span></code> in the subject <code class="subject rouge"><span class="pcre2-semantic">aab</span></code>. The use of the backtracking control verbs | |
| <code class="regex rouge"><span class="pcre2-semantic">(*PRUNE)</span></code> and <code class="regex rouge"><span class="pcre2-semantic">(*SKIP)</span></code> also disable this optimization. To do so explicitly, | |
| either pass the compile option <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_DOTSTAR_ANCHOR</span></code>, or call | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_set_optimize()</span></code> with a <code class="constant pcre2-api rouge"><span class="no">PCRE2_DOTSTAR_ANCHOR_OFF</span></code> directive.</p> | |
| <p>When a capture group is repeated, the value captured is the substring that | |
| matched the final iteration. For example, after</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(tweedle[dume]{3}\s*)+</span></code></pre></div> | |
| <p>has matched <code class="subject rouge"><span class="pcre2-semantic">tweedledum tweedledee</span></code> the value of the captured substring is | |
| <code class="subject rouge"><span class="pcre2-semantic">tweedledee</span></code>. However, if there are nested capture groups, the corresponding | |
| captured values may have been set in previous iterations. For example, after</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(a|(b))+</span></code></pre></div> | |
| <p>matches <code class="subject rouge"><span class="pcre2-semantic">aba</span></code> the value of the second captured substring is <code class="subject rouge"><span class="pcre2-semantic">b</span></code>.</p></section> | |
| <section class="doc-section level-1"><h2 id="_atomic_grouping_and_possessive_quantifiers">Atomic grouping and possessive quantifiers</h2><p>With both maximizing ("greedy") and minimizing ("ungreedy" or "lazy") | |
| repetition, failure of what follows normally causes the repeated item to be | |
| re-evaluated to see if a different number of repeats allows the rest of the | |
| pattern to match. Sometimes it is useful to prevent this, either to change the | |
| nature of the match, or to cause it fail earlier than it otherwise might, when | |
| the author of the pattern knows there is no point in carrying on.</p> | |
| <p>Consider, for example, the pattern <code class="regex rouge"><span class="pcre2-semantic">\d+foo</span></code> when applied to the subject line | |
| <code class="subject rouge"><span class="pcre2-semantic">123456bar</span></code>.</p> | |
| <p>After matching all 6 digits and then failing to match <code class="subject rouge"><span class="pcre2-semantic">foo</span></code>, the normal | |
| action of the matcher is to try again with only 5 digits matching the <code class="regex rouge"><span class="pcre2-semantic">\d+</span></code> | |
| item, and then with 4, and so on, before ultimately failing. "Atomic grouping" | |
| (a term taken from Jeffrey Friedl’s book) provides the means for specifying | |
| that once a group has matched, it is not to be re-evaluated in this way.</p> | |
| <p>If we use atomic grouping for the previous example, the matcher gives up | |
| immediately on failing to match <code class="subject rouge"><span class="pcre2-semantic">foo</span></code> the first time. The notation is a kind of | |
| special parenthesis, starting with <code class="regex rouge"><span class="pcre2-semantic">(?></span></code> as in this example:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?>\d+)foo</span></code></pre></div> | |
| <p>Perl 5.28 introduced an experimental alphabetic form starting with <code class="regex rouge"><span class="pcre2-semantic">(*</span></code> which may | |
| be easier to remember:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(*atomic:\d+)foo</span></code></pre></div> | |
| <p>This kind of parenthesized group "locks up" the part of the pattern it contains | |
| once it has matched, and a failure further into the pattern is prevented from | |
| backtracking into it. Backtracking past it to previous items, however, works as | |
| normal.</p> | |
| <p>An alternative description is that a group of this type matches exactly the | |
| string of characters that an identical standalone pattern would match, if | |
| anchored at the current point in the subject string.</p> | |
| <p>Atomic groups are not capture groups. Simple cases such as the above example | |
| can be thought of as a maximizing repeat that must swallow everything it can. | |
| So, while both <code class="regex rouge"><span class="pcre2-semantic">\d+</span></code> and <code class="regex rouge"><span class="pcre2-semantic">\d+?</span></code> are prepared to adjust the number of digits they | |
| match in order to make the rest of the pattern match, <code class="regex rouge"><span class="pcre2-semantic">(?>\d+)</span></code> can only match | |
| an entire sequence of digits.</p> | |
| <p>Atomic groups in general can of course contain arbitrarily complicated | |
| expressions, and can be nested. However, when the contents of an atomic | |
| group is just a single repeated item, as in the example above, a simpler | |
| notation, called a "possessive quantifier" can be used. This consists of an | |
| additional <code class="regex rouge"><span class="pcre2-semantic">+</span></code> character following a quantifier. Using this notation, the | |
| previous example can be rewritten as</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">\d++foo</span></code></pre></div> | |
| <p>Note that a possessive quantifier can be used with an entire group, for | |
| example:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(abc|xyz){2,3}+</span></code></pre></div> | |
| <p>Possessive quantifiers are always greedy; the setting of the <code class="constant pcre2-api rouge"><span class="no">PCRE2_UNGREEDY</span></code> | |
| option is ignored. They are a convenient notation for the simpler forms of | |
| atomic group. However, there is no difference in the meaning of a possessive | |
| quantifier and the equivalent atomic group, though there may be a performance | |
| difference; possessive quantifiers should be slightly faster.</p> | |
| <p>The possessive quantifier syntax is an extension to the Perl 5.8 syntax. | |
| Jeffrey Friedl originated the idea (and the name) in the first edition of his | |
| book. Mike McCloskey liked it, so implemented it when he built Sun’s Java | |
| package, and PCRE1 copied it from there. It found its way into Perl at release | |
| 5.10.</p> | |
| <p>PCRE2 has an optimization that automatically "possessifies" certain simple | |
| pattern constructs. For example, the sequence <code class="regex rouge"><span class="pcre2-semantic">A+B</span></code> is treated as <code class="regex rouge"><span class="pcre2-semantic">A++B</span></code> because | |
| there is no point in backtracking into a sequence of A’s when B must follow. | |
| This feature can be disabled by the <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_AUTO_POSSESS</span></code> option, by calling | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_set_optimize()</span></code> with a <code class="constant pcre2-api rouge"><span class="no">PCRE2_AUTO_POSSESS_OFF</span></code> directive, or by | |
| starting the pattern with <code class="regex rouge"><span class="pcre2-semantic">(*NO_AUTO_POSSESS)</span></code>.</p> | |
| <p>When a pattern contains an unlimited repeat inside a group that can itself be | |
| repeated an unlimited number of times, the use of an atomic group is the only | |
| way to avoid some failing matches taking a very long time indeed. The pattern</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(\D+|<\d+>)*[!?]</span></code></pre></div> | |
| <p>matches an unlimited number of substrings that either consist of non-digits, or | |
| digits enclosed in <>, followed by either ! or ?. When it matches, it runs | |
| quickly. However, if it is applied to</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="text">aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa</code></pre></div> | |
| <p>it takes a long time before reporting failure. This is because the string can | |
| be divided between the internal <code class="regex rouge"><span class="pcre2-semantic">\D+</span></code> repeat and the external <code class="regex rouge"><span class="pcre2-semantic">*</span></code> repeat in a | |
| large number of ways, and all have to be tried. (The example uses <code class="regex rouge"><span class="pcre2-semantic">[!?]</span></code> rather | |
| than a single character at the end, because both PCRE2 and Perl have an | |
| optimization that allows for fast failure when a single character is used. They | |
| remember the last single character that is required for a match, and fail early | |
| if it is not present in the string.) If the pattern is changed so that it uses | |
| an atomic group, like this:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">((?>\D+)|<\d+>)*[!?]</span></code></pre></div> | |
| <p>sequences of non-digits cannot be broken, and failure happens quickly.</p></section> | |
| <section class="doc-section level-1"><h2 id="_backreferences">Backreferences</h2><p>Outside a character class, a backslash followed by a digit greater than 0 (and | |
| possibly further digits) is a backreference to a capture group earlier (that | |
| is, to its left) in the pattern, provided there have been that many previous | |
| capture groups.</p> | |
| <p>However, if the decimal number following the backslash is less than 8, it is | |
| always taken as a backreference, and causes an error only if there are not that | |
| many capture groups in the entire pattern. In other words, the group that is | |
| referenced need not be to the left of the reference for numbers less than 8. A | |
| "forward backreference" of this type can make sense when a repetition is | |
| involved and the group to the right has participated in an earlier iteration.</p> | |
| <p>It is not possible to have a numerical "forward backreference" to a group whose | |
| number is 8 or more using this syntax because a sequence such as <code class="regex rouge"><span class="pcre2-semantic">\50</span></code> is | |
| interpreted as a character defined in octal. See the subsection | |
| <a href="#non-printing-characters">Non-printing characters</a> | |
| above | |
| for further details of the handling of digits following a backslash. Other | |
| forms of backreferencing do not suffer from this restriction. In particular, | |
| there is no problem when named capture groups are used (see below).</p> | |
| <p>Another way of avoiding the ambiguity inherent in the use of digits following a | |
| backslash is to use the <code class="regex rouge"><span class="pcre2-semantic">\g</span></code> escape sequence. This escape must be followed by a | |
| signed or unsigned number, optionally enclosed in braces. These examples are | |
| all identical ways of matching <code class="subject rouge"><span class="pcre2-semantic">ring, ring</span></code>:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(ring), \1 | |
| (ring), \g1 | |
| (ring), \g{1}</span></code></pre></div> | |
| <p>An unsigned number specifies an absolute reference without the ambiguity that | |
| is present in the older syntax. It is also useful when literal digits follow | |
| the reference. A signed number is a relative reference. Consider this example:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(abc(def)ghi)\g{-1}</span></code></pre></div> | |
| <p>The sequence <code class="regex rouge"><span class="pcre2-semantic">\g{-1}</span></code> is a reference to the capture group whose number is one | |
| less than the number of the next group to be started, so in this example (where | |
| the next group would be numbered 3) is it equivalent to <code class="regex rouge"><span class="pcre2-semantic">\2</span></code>, and <code class="regex rouge"><span class="pcre2-semantic">\g{-2}</span></code> would | |
| be equivalent to <code class="regex rouge"><span class="pcre2-semantic">\1</span></code>. Note that if this construct is inside a capture group, | |
| that group is included in the count, so in this example <code class="regex rouge"><span class="pcre2-semantic">\g{-2}</span></code> also refers to | |
| group 1:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(A)(\g{-2}B)</span></code></pre></div> | |
| <p>The use of relative references can be helpful in long patterns, and also in | |
| patterns that are created by joining together fragments that contain references | |
| within themselves.</p> | |
| <p>The sequence <code class="regex rouge"><span class="pcre2-semantic">\g{+1}</span></code> is a reference to the next capture group that is started | |
| after this item, and <code class="regex rouge"><span class="pcre2-semantic">\g{+2}</span></code> refers to the one after that, and so on. This kind | |
| of forward reference can be useful in patterns that repeat. Perl does not | |
| support the use of <code class="regex rouge"><span class="pcre2-semantic">+</span></code> in this way.</p> | |
| <p>A backreference matches whatever actually most recently matched the capture | |
| group in the current subject string, rather than anything at all that matches | |
| the group (see | |
| "Groups as subroutines" | |
| below for a way of doing that). So the pattern</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(sens|respons)e and \1ibility</span></code></pre></div> | |
| <p>matches <code class="subject rouge"><span class="pcre2-semantic">sense and sensibility</span></code> and <code class="subject rouge"><span class="pcre2-semantic">response and responsibility</span></code>, but not | |
| "sense and responsibility". If caseful matching is in force at the time of the | |
| backreference, the case of letters is relevant. For example,</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">((?i)rah)\s+\1</span></code></pre></div> | |
| <p>matches <code class="subject rouge"><span class="pcre2-semantic">rah rah</span></code> and <code class="subject rouge"><span class="pcre2-semantic">RAH RAH</span></code>, but not <code class="subject rouge"><span class="pcre2-semantic">RAH rah</span></code>, even though the original | |
| capture group is matched caselessly.</p> | |
| <p>There are several different ways of writing backreferences to named capture | |
| groups. The .NET syntax is <code class="regex rouge"><span class="pcre2-semantic">\k{<em>name</em>}</span></code>, the Python syntax is <code class="regex rouge"><span class="pcre2-semantic">(?=<em>name</em>)</span></code>, and the | |
| original Perl syntax is <code class="regex rouge"><span class="pcre2-semantic">\k<<em>name</em>></span></code> or <code class="regex rouge"><span class="pcre2-semantic">\k'<em>name</em>'</span></code>. All of these are now supported | |
| by both Perl and PCRE2. Perl 5.10’s unified backreference syntax, in which <code class="regex rouge"><span class="pcre2-semantic">\g</span></code> | |
| can be used for both numeric and named references, is also supported by PCRE2. | |
| We could rewrite the above example in any of the following ways:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?<p1>(?i)rah)\s+\k<p1> | |
| (?'p1'(?i)rah)\s+\k{p1} | |
| (?P<p1>(?i)rah)\s+(?P=p1) | |
| (?<p1>(?i)rah)\s+\g{p1}</span></code></pre></div> | |
| <p>A capture group that is referenced by name may appear in the pattern before or | |
| after the reference.</p> | |
| <p>There may be more than one backreference to the same group. If a group has not | |
| actually been used in a particular match, backreferences to it always fail by | |
| default. For example, the pattern</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(a|(bc))\2</span></code></pre></div> | |
| <p>always fails if it starts to match <code class="subject rouge"><span class="pcre2-semantic">a</span></code> rather than <code class="subject rouge"><span class="pcre2-semantic">bc</span></code>. However, if the | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_MATCH_UNSET_BACKREF</span></code> option is set at compile time, a backreference to an | |
| unset value matches an empty string.</p> | |
| <p>Because there may be many capture groups in a pattern, all digits following a | |
| backslash are taken as part of a potential backreference number. If the pattern | |
| continues with a digit character, some delimiter must be used to terminate the | |
| backreference. If the <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED</span></code> or <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED_MORE</span></code> option is set, this | |
| can be white space. Otherwise, the <code class="regex rouge"><span class="pcre2-semantic">\g{}</span></code> syntax or an empty comment (see | |
| "Comments" | |
| below) can be used.</p> | |
| <section class="doc-section level-2"><h3 id="_recursive_backreferences">Recursive backreferences</h3><p>A backreference that occurs inside the group to which it refers fails when the | |
| group is first used, so, for example, (a\1) never matches. However, such | |
| references can be useful inside repeated groups. For example, the pattern</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(a|b\1)+</span></code></pre></div> | |
| <p>matches any number of <code class="subject rouge"><span class="pcre2-semantic">a</span></code> characters and also <code class="subject rouge"><span class="pcre2-semantic">aba</span></code>, <code class="subject rouge"><span class="pcre2-semantic">ababbaa</span></code>, etc. At each iteration of | |
| the group, the backreference matches the character string corresponding to the | |
| previous iteration. In order for this to work, the pattern must be such that | |
| the first iteration does not need to match the backreference. This can be done | |
| using alternation, as in the example above, or by a quantifier with a minimum | |
| of zero.</p> | |
| <p>For versions of PCRE2 less than 10.25, backreferences of this type used to | |
| cause the group that they reference to be treated as an | |
| atomic group. | |
| This restriction no longer applies, and backtracking into such groups can occur | |
| as normal.</p></section></section> | |
| <section class="doc-section level-1"><h2 id="_assertions">Assertions</h2><p>An assertion is a test that does not consume any characters. The test must | |
| succeed for the match to continue. The simple assertions coded as <code class="regex rouge"><span class="pcre2-semantic">\b</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\B</span></code>, | |
| <code class="regex rouge"><span class="pcre2-semantic">\A</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\G</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\Z</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\z</span></code>, <code class="regex rouge"><span class="pcre2-semantic">^</span></code> and <code class="regex rouge"><span class="pcre2-semantic">$</span></code> are described | |
| above.</p> | |
| <p>More complicated assertions are coded as parenthesized groups. If matching such | |
| a group succeeds, matching continues after it, but with the matching position | |
| in the subject string reset to what it was before the assertion was processed.</p> | |
| <p>A special kind of assertion, called a "scan substring" assertion, matches a | |
| subpattern against a previously captured substring. This is described in the | |
| section <a href="#scan-substring-assertions">Scan substring assertions</a> | |
| below. It is a PCRE2 extension, not compatible with Perl.</p> | |
| <p>The other goup-based assertions are of two kinds: those that look ahead of the | |
| current position in the subject string, and those that look behind it, and in | |
| each case an assertion may be positive (must match for the assertion to be | |
| true) or negative (must not match for the assertion to be true).</p> | |
| <p>The Perl-compatible lookaround assertions are atomic. If an assertion is true, | |
| but there is a subsequent matching failure, there is no backtracking into the | |
| assertion. However, there are some cases where non-atomic assertions can be | |
| useful. PCRE2 has some support for these, described in the section | |
| <a href="#non-atomic-assertions">Non-atomic assertions</a> | |
| below, but they are not Perl-compatible.</p> | |
| <p>A lookaround assertion may appear as the condition in a | |
| conditional group | |
| (see below). In this case, the result of matching the assertion determines | |
| which branch of the condition is followed.</p> | |
| <p>Assertion groups are not capture groups. If an assertion contains capture | |
| groups within it, these are counted for the purposes of numbering the capture | |
| groups in the whole pattern. Within each branch of an assertion, locally | |
| captured substrings may be referenced in the usual way. For example, a sequence | |
| such as <code class="regex rouge"><span class="pcre2-semantic">(.)\g{-1}</span></code> can be used to check that two adjacent characters are the | |
| same.</p> | |
| <p>When a branch within an assertion fails to match, any substrings that were | |
| captured are discarded (as happens with any pattern branch that fails to | |
| match). A negative assertion is true only when all its branches fail to match; | |
| this means that no captured substrings are ever retained after a successful | |
| negative assertion. When an assertion contains a matching branch, what happens | |
| depends on the type of assertion.</p> | |
| <p>For a positive assertion, internally captured substrings in the successful | |
| branch are retained, and matching continues with the next pattern item after | |
| the assertion. For a negative assertion, a matching branch means that the | |
| assertion is not true. If such an assertion is being used as a condition in a | |
| conditional group | |
| (see below), captured substrings are retained, because matching continues with | |
| the "no" branch of the condition. For other failing negative assertions, | |
| control passes to the previous backtracking point, thus discarding any captured | |
| strings within the assertion.</p> | |
| <p>Most assertion groups may be repeated; though it makes no sense to assert the | |
| same thing several times, the side effect of capturing in positive assertions | |
| may occasionally be useful. However, an assertion that forms the condition for | |
| a conditional group may not be quantified. PCRE2 used to restrict the | |
| repetition of assertions, but from release 10.35 the only restriction is that | |
| an unlimited maximum repetition is changed to be one more than the minimum. For | |
| example, <code class="regex rouge"><span class="pcre2-semantic">{3,}</span></code> is treated as <code class="regex rouge"><span class="pcre2-semantic">{3,4}</span></code>.</p> | |
| <section class="doc-section level-2"><h3 id="_alphabetic_assertion_names">Alphabetic assertion names</h3><p>Traditionally, symbolic sequences such as <code class="regex rouge"><span class="pcre2-semantic">(?=</span></code> and <code class="regex rouge"><span class="pcre2-semantic">(?<=</span></code> have been used to | |
| specify lookaround assertions. Perl 5.28 introduced some experimental | |
| alphabetic alternatives which might be easier to remember. They all start with | |
| <code class="regex rouge"><span class="pcre2-semantic">(*</span></code> instead of <code class="regex rouge"><span class="pcre2-semantic">(?</span></code> and must be written using lower case letters. PCRE2 supports | |
| the following synonyms:</p> | |
| <dl class="spaced" style="--tab-width: 12"><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">(*positive_lookahead:</span></code><br><code class="regex rouge"><span class="pcre2-semantic">(*pla:</span></code></span></dt><dd>Is the same as <code class="regex rouge"><span class="pcre2-semantic">(?=</span></code>.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">(*negative_lookahead:</span></code><br><code class="regex rouge"><span class="pcre2-semantic">(*nla:</span></code></span></dt><dd>Is the same as <code class="regex rouge"><span class="pcre2-semantic">(?!</span></code>.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">(*positive_lookbehind:</span></code><br><code class="regex rouge"><span class="pcre2-semantic">(*plb:</span></code></span></dt><dd>Is the same as <code class="regex rouge"><span class="pcre2-semantic">(?<=</span></code>.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">(*negative_lookbehind:</span></code><br><code class="regex rouge"><span class="pcre2-semantic">(*nlb:</span></code></span></dt><dd>Is the same as <code class="regex rouge"><span class="pcre2-semantic">(?<!</span></code>.</dd></div></dl> | |
| <p>For example, <code class="regex rouge"><span class="pcre2-semantic">(*pla:<em>foo</em>)</span></code> is the same assertion as <code class="regex rouge"><span class="pcre2-semantic">(?=<em>foo</em>)</span></code>. In the following | |
| sections, the various assertions are described using the original symbolic | |
| forms.</p></section> | |
| <section class="doc-section level-2"><h3 id="_lookahead_assertions">Lookahead assertions</h3><p>Lookahead assertions start with <code class="regex rouge"><span class="pcre2-semantic">(?=</span></code> for positive assertions and <code class="regex rouge"><span class="pcre2-semantic">(?!</span></code> for | |
| negative assertions. For example,</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">\w+(?=;)</span></code></pre></div> | |
| <p>matches a word followed by a semicolon, but does not include the semicolon in | |
| the match, and</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">foo(?!bar)</span></code></pre></div> | |
| <p>matches any occurrence of <code class="subject rouge"><span class="pcre2-semantic">foo</span></code> that is not followed by <code class="subject rouge"><span class="pcre2-semantic">bar</span></code>. Note that the | |
| apparently similar pattern</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?!foo)bar</span></code></pre></div> | |
| <p>does not find an occurrence of <code class="subject rouge"><span class="pcre2-semantic">bar</span></code> that is preceded by something other than | |
| <code class="subject rouge"><span class="pcre2-semantic">foo</span></code>; it finds any occurrence of <code class="subject rouge"><span class="pcre2-semantic">bar</span></code> whatsoever, because the assertion | |
| <code class="regex rouge"><span class="pcre2-semantic">(?!foo)</span></code> is always true when the next three characters are <code class="subject rouge"><span class="pcre2-semantic">bar</span></code>. A | |
| lookbehind assertion is needed to achieve the other effect.</p> | |
| <p>If you want to force a matching failure at some point in a pattern, the most | |
| convenient way to do it is with <code class="regex rouge"><span class="pcre2-semantic">(?!)</span></code> because an empty string always matches, so | |
| an assertion that requires there not to be an empty string must always fail. | |
| The backtracking control verb <code class="regex rouge"><span class="pcre2-semantic">(*FAIL)</span></code> or <code class="regex rouge"><span class="pcre2-semantic">(*F)</span></code> is a synonym for <code class="regex rouge"><span class="pcre2-semantic">(?!)</span></code>.</p></section> | |
| <section class="doc-section level-2"><h3 id="_lookbehind_assertions">Lookbehind assertions</h3><p>Lookbehind assertions start with <code class="regex rouge"><span class="pcre2-semantic">(?<=</span></code> for positive assertions and <code class="regex rouge"><span class="pcre2-semantic">(?<!</span></code> for | |
| negative assertions. For example,</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?<!foo)bar</span></code></pre></div> | |
| <p>does find an occurrence of <code class="subject rouge"><span class="pcre2-semantic">bar</span></code> that is not preceded by <code class="subject rouge"><span class="pcre2-semantic">foo</span></code>. The contents of | |
| a lookbehind assertion are restricted such that there must be a known maximum | |
| to the lengths of all the strings it matches. There are two cases:</p> | |
| <p>If every top-level alternative matches a fixed length, for example</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?<=colour|color)</span></code></pre></div> | |
| <p>there is a limit of 65,535 characters to the lengths, which do not have to be | |
| the same, as this example demonstrates. This is the only kind of lookbehind | |
| supported by PCRE2 versions earlier than 10.43 and by the alternative matching | |
| function <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code>.</p> | |
| <p>In PCRE2 10.43 and later, <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> supports lookbehind assertions in | |
| which one or more top-level alternatives can match more than one string length, | |
| for example</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?<=colou?r)</span></code></pre></div> | |
| <p>The maximum matching length for any branch of the lookbehind is limited to a | |
| value set by the calling program (default 255 characters). Unlimited repetition | |
| (for example <code class="regex rouge"><span class="pcre2-semantic">\d*</span></code>) is not supported. In some cases, the escape sequence <code class="regex rouge"><span class="pcre2-semantic">\K</span></code> | |
| (see above) | |
| can be used instead of a lookbehind assertion at the start of a pattern to get | |
| round the length limit restriction.</p> | |
| <p>In UTF-8 and UTF-16 modes, PCRE2 does not allow the <code class="regex rouge"><span class="pcre2-semantic">\C</span></code> escape (which matches a | |
| single code unit even in a UTF mode) to appear in lookbehind assertions, | |
| because it makes it impossible to calculate the length of the lookbehind. The | |
| <code class="regex rouge"><span class="pcre2-semantic">\X</span></code> and <code class="regex rouge"><span class="pcre2-semantic">\R</span></code> escapes, which can match different numbers of code units, are never | |
| permitted in lookbehinds.</p> | |
| <p>"Subroutine" | |
| calls (see below) such as <code class="regex rouge"><span class="pcre2-semantic">(?2)</span></code> or <code class="regex rouge"><span class="pcre2-semantic">(?&X)</span></code> are permitted in lookbehinds, as long | |
| as the called capture group matches a limited-length string. However, | |
| recursion, | |
| that is, a "subroutine" call into a group that is already active, | |
| is not supported.</p> | |
| <p>PCRE2 supports backreferences in lookbehinds, but only if certain conditions | |
| are met. The <code class="constant pcre2-api rouge"><span class="no">PCRE2_MATCH_UNSET_BACKREF</span></code> option must not be set, there must be no | |
| use of <code class="regex rouge"><span class="pcre2-semantic">(?|</span></code> in the pattern (it creates duplicate group numbers), and if the | |
| backreference is by name, the name must be unique. Of course, the referenced | |
| group must itself match a limited length substring. The following pattern | |
| matches words containing at least two characters that begin and end with the | |
| same character:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic"> \b(\w)\w++(?<=\1)</span></code></pre></div> | |
| <p>Possessive quantifiers can be used in conjunction with lookbehind assertions to | |
| specify efficient matching at the end of subject strings. Consider a simple | |
| pattern such as</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">abcd$</span></code></pre></div> | |
| <p>when applied to a long string that does not match. Because matching proceeds | |
| from left to right, PCRE2 will look for each <code class="subject rouge"><span class="pcre2-semantic">a</span></code> in the subject and then see if | |
| what follows matches the rest of the pattern. If the pattern is specified as</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">^.*abcd$</span></code></pre></div> | |
| <p>the initial <code class="regex rouge"><span class="pcre2-semantic">.*</span></code> matches the entire string at first, but when this fails (because | |
| there is no following <code class="subject rouge"><span class="pcre2-semantic">a</span></code>), it backtracks to match all but the last character, | |
| then all but the last two characters, and so on. Once again the search for <code class="subject rouge"><span class="pcre2-semantic">a</span></code> | |
| covers the entire string, from right to left, so we are no better off. However, | |
| if the pattern is written as</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">^.*+(?<=abcd)</span></code></pre></div> | |
| <p>there can be no backtracking for the <code class="regex rouge"><span class="pcre2-semantic">.*+</span></code> item because of the possessive | |
| quantifier; it can match only the entire string. The subsequent lookbehind | |
| assertion does a single test on the last four characters. If it fails, the | |
| match fails immediately. For long strings, this approach makes a significant | |
| difference to the processing time.</p></section> | |
| <section class="doc-section level-2"><h3 id="_using_multiple_assertions">Using multiple assertions</h3><p>Several assertions (of any sort) may occur in succession. For example,</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?<=\d{3})(?<!999)foo</span></code></pre></div> | |
| <p>matches <code class="subject rouge"><span class="pcre2-semantic">foo</span></code> preceded by three digits that are not <code class="subject rouge"><span class="pcre2-semantic">999</span></code>. Notice that each of | |
| the assertions is applied independently at the same point in the subject | |
| string. First there is a check that the previous three characters are all | |
| digits, and then there is a check that the same three characters are not <code class="subject rouge"><span class="pcre2-semantic">999</span></code>. | |
| This pattern does <em>not</em> match <code class="subject rouge"><span class="pcre2-semantic">foo</span></code> preceded by six characters, the first | |
| of which are digits and the last three of which are not <code class="subject rouge"><span class="pcre2-semantic">999</span></code>. For example, it | |
| doesn’t match <code class="subject rouge"><span class="pcre2-semantic">123abcfoo</span></code>. A pattern to do that is</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?<=\d{3}...)(?<!999)foo</span></code></pre></div> | |
| <p>This time the first assertion looks at the preceding six characters, checking | |
| that the first three are digits, and then the second assertion checks that the | |
| preceding three characters are not <code class="subject rouge"><span class="pcre2-semantic">999</span></code>.</p> | |
| <p>Assertions can be nested in any combination. For example,</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?<=(?<!foo)bar)baz</span></code></pre></div> | |
| <p>matches an occurrence of <code class="subject rouge"><span class="pcre2-semantic">baz</span></code> that is preceded by <code class="subject rouge"><span class="pcre2-semantic">bar</span></code> which in turn is not | |
| preceded by <code class="subject rouge"><span class="pcre2-semantic">foo</span></code>, while</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?<=\d{3}(?!999)...)foo</span></code></pre></div> | |
| <p>is another pattern that matches <code class="subject rouge"><span class="pcre2-semantic">foo</span></code> preceded by three digits and any three | |
| characters that are not <code class="subject rouge"><span class="pcre2-semantic">999</span></code>.</p></section></section> | |
| <section class="doc-section level-1"><h2 id="non-atomic-assertions">Non-atomic assertions</h2><p>Traditional lookaround assertions are atomic. That is, if an assertion is true, | |
| but there is a subsequent matching failure, there is no backtracking into the | |
| assertion. However, there are some cases where non-atomic positive assertions | |
| can be useful. PCRE2 provides these using the following syntax:</p> | |
| <dl class="spaced" style="--tab-width: 6"><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">(*non_atomic_positive_lookahead:</span></code><br><code class="regex rouge"><span class="pcre2-semantic">(*napla:</span></code><br><code class="regex rouge"><span class="pcre2-semantic">(?*</span></code></span></dt><dd>Non-atomic positive lookahead.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">(*non_atomic_positive_lookbehind:</span></code><br><code class="regex rouge"><span class="pcre2-semantic">(*naplb:</span></code><br><code class="regex rouge"><span class="pcre2-semantic">(?<*</span></code></span></dt><dd>Non-atomic positive lookbehind.</dd></div></dl> | |
| <p>Consider the problem of finding the right-most word in a string that also | |
| appears earlier in the string, that is, it must appear at least twice in total. | |
| This pattern returns the required result as captured substring 1:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">^(?x)(*napla: .* \b(\w++)) (?> .*? \b\1\b ){2}</span></code></pre></div> | |
| <p>For a subject such as <code class="subject rouge"><span class="pcre2-semantic">word1 word2 word3 word2 word3 word4</span></code> the result is | |
| <code class="subject rouge"><span class="pcre2-semantic">word3</span></code>. How does it work? At the start, <code class="regex rouge"><span class="pcre2-semantic">^(?x)</span></code> anchors the pattern and sets the | |
| <code class="regex rouge"><span class="pcre2-semantic">x</span></code> option, which causes white space (introduced for readability) to be | |
| ignored. Inside the assertion, the greedy <code class="regex rouge"><span class="pcre2-semantic">.*</span></code> at first consumes the entire | |
| string, but then has to backtrack until the rest of the assertion can match a | |
| word, which is captured by group 1. In other words, when the assertion first | |
| succeeds, it captures the right-most word in the string.</p> | |
| <p>The current matching point is then reset to the start of the subject, and the | |
| rest of the pattern match checks for two occurrences of the captured word, | |
| using an ungreedy <code class="regex rouge"><span class="pcre2-semantic">.*?</span></code> to scan from the left. If this succeeds, we are done, but | |
| if the last word in the string does not occur twice, this part of the pattern | |
| fails. If a traditional atomic lookahead <code class="regex rouge"><span class="pcre2-semantic">(?=</span></code> or <code class="regex rouge"><span class="pcre2-semantic">(*pla:</span></code> had been used, the | |
| assertion could not be re-entered, and the whole match would fail. The pattern | |
| would succeed only if the very last word in the subject was found twice.</p> | |
| <p>Using a non-atomic lookahead, however, means that when the last word does not | |
| occur twice in the string, the lookahead can backtrack and find the second-last | |
| word, and so on, until either the match succeeds, or all words have been | |
| tested.</p> | |
| <p>Two conditions must be met for a non-atomic assertion to be useful: the | |
| contents of one or more capturing groups must change after a backtrack into the | |
| assertion, and there must be a backreference to a changed group later in the | |
| pattern. If this is not the case, the rest of the pattern match fails exactly | |
| as before because nothing has changed, so using a non-atomic assertion just | |
| wastes resources.</p> | |
| <p>There is one exception to backtracking into a non-atomic assertion. If an | |
| <code class="regex rouge"><span class="pcre2-semantic">(*ACCEPT)</span></code> control verb is triggered, the assertion succeeds atomically. That | |
| is, a subsequent match failure cannot backtrack into the assertion.</p> | |
| <p>Non-atomic assertions are not supported by the alternative matching function | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code>. They are supported by JIT, but only if they do not | |
| contain any control verbs such as <code class="regex rouge"><span class="pcre2-semantic">(*ACCEPT)</span></code>. (This may change in future). Note | |
| that assertions that appear as conditions for | |
| conditional groups | |
| (see below) must be atomic.</p></section> | |
| <section class="doc-section level-1"><h2 id="scan-substring-assertions">Scan substring assertions</h2><p>A special kind of assertion, not compatible with Perl, makes it possible to | |
| check the contents of a captured substring by matching it with a subpattern. | |
| Because this involves capturing, this feature is not supported by | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code>.</p> | |
| <p>A scan substring assertion starts with the sequence <code class="regex rouge"><span class="pcre2-semantic">(*scan_substring:</span></code> or | |
| <code class="regex rouge"><span class="pcre2-semantic">(*scs:</span></code> which is followed by a list of substring numbers (absolute or relative) | |
| and/or substring names enclosed in single quotes or angle brackets, all within | |
| parentheses. The rest of the item is the subpattern that is applied to the | |
| substring, as shown in these examples:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(*scan_substring:(1)...) | |
| (*scs:(-2)...) | |
| (*scs:('AB')...) | |
| (*scs:(1,'AB',-2)...)</span></code></pre></div> | |
| <p>The list of groups is checked in the order they are given, and it is the | |
| contents of the first one that is found to be set that are scanned. When | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_DUPNAMES</span></code> is set and there are ambiguous group names, all groups with the | |
| same name are checked in numerical order. A scan substring assertion fails if | |
| none of the groups it references have been set.</p> | |
| <p>The pattern match on the substring is always anchored, that is, it must match | |
| from the start of the substring. There is no "bumpalong" if it does not match | |
| at the start. The end of the subject is temporarily reset to be the end of the | |
| substring, so <code class="regex rouge"><span class="pcre2-semantic">\Z</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\z</span></code>, and <code class="regex rouge"><span class="pcre2-semantic">$</span></code> will match there. However, the start of the | |
| subject is <em>not</em> reset. This means that <code class="regex rouge"><span class="pcre2-semantic">^</span></code> matches only if the substring is | |
| actually at the start of the main subject, but it also means that lookbehind | |
| assertions into what precedes the substring are possible.</p> | |
| <p>Here is a very simple example: find a word that contains the rare (in English) | |
| sequence of letters <code class="subject rouge"><span class="pcre2-semantic">rh</span></code> not at the start:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">\b(\w++)(*scs:(1).+rh)</span></code></pre></div> | |
| <p>The first group captures a word which is then scanned by the second group. | |
| This example does not actually need this heavyweight feature; the same match | |
| can be achieved with:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">\b\w+?rh\w*\b</span></code></pre></div> | |
| <p>When things are more complicated, however, scanning a captured substring can be | |
| a useful way to describe the required match. For exmple, there is a rather | |
| complicated pattern in the PCRE2 test data that checks an entire subject string | |
| for a palindrome, that is, the sequence of letters is the same in both | |
| directions. Suppose you want to search for individual words of two or more | |
| characters such as "level" that are palindromes:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(\b\w{2,}+\b)(*scs:(1)...palindrome-matching-pattern...)</span></code></pre></div> | |
| <p>Within a substring scanning subpattern, references to other groups work as | |
| normal. Capturing groups may appear, and will retain their values during | |
| ongoing matching if the assertion succeeds.</p></section> | |
| <section class="doc-section level-1"><h2 id="_script_runs">Script runs</h2><p>In concept, a script run is a sequence of characters that are all from the same | |
| Unicode script such as Latin or Greek. However, because some scripts are | |
| commonly used together, and because some diacritical and other marks are used | |
| with multiple scripts, it is not that simple. There is a full description of | |
| the rules that PCRE2 uses in the section | |
| <a href="./pcre2unicode.html#script-runs">Script runs</a> | |
| in the | |
| <a href="./pcre2unicode.html"><code>pcre2unicode</code></a> | |
| documentation.</p> | |
| <p>If part of a pattern is enclosed between <code class="regex rouge"><span class="pcre2-semantic">(*script_run:</span></code> or <code class="regex rouge"><span class="pcre2-semantic">(*sr:</span></code> and a closing | |
| parenthesis, it fails if the sequence of characters that it matches are not a | |
| script run. After a failure, normal backtracking occurs. Script runs can be | |
| used to detect spoofing attacks using characters that look the same, but are | |
| from different scripts. The string <code class="subject rouge"><span class="pcre2-semantic">paypal.com</span></code> is an infamous example, where | |
| the letters could be a mixture of Latin and Cyrillic. This pattern ensures that | |
| the matched characters in a sequence of non-spaces that follow white space are | |
| a script run:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">\s+(*sr:\S+)</span></code></pre></div> | |
| <p>To be sure that they are all from the Latin script (for example), a lookahead | |
| can be used:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">\s+(?=\p{Latin})(*sr:\S+)</span></code></pre></div> | |
| <p>This works as long as the first character is expected to be a character in that | |
| script, and not (for example) punctuation, which is allowed with any script. If | |
| this is not the case, a more creative lookahead is needed. For example, if | |
| digits, underscore, and dots are permitted at the start:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">\s+(?=[0-9_.]*\p{Latin})(*sr:\S+)</span></code></pre></div> | |
| <p>In many cases, backtracking into a script run pattern fragment is not | |
| desirable. The script run can employ an atomic group to prevent this. Because | |
| this is a common requirement, a shorthand notation is provided by | |
| <code class="regex rouge"><span class="pcre2-semantic">(*atomic_script_run:</span></code> or <code class="regex rouge"><span class="pcre2-semantic">(*asr:</span></code></p> | |
| <dl class="compact" style="--tab-width: 6"><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">(*asr:...)</span></code></span></dt><dd>Is the same as <code class="regex rouge"><span class="pcre2-semantic">(*sr:(?>...))</span></code>.</dd></div></dl> | |
| <p>Note that the atomic group is inside the script run. Putting it outside would | |
| not prevent backtracking into the script run pattern.</p> | |
| <p>Support for script runs is not available if PCRE2 is compiled without Unicode | |
| support. A compile-time error is given if any of the above constructs is | |
| encountered. Script runs are not supported by the alternate matching function, | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_dfa_match()</span></code> because they use the same mechanism as capturing | |
| parentheses.</p> | |
| <p>Warning: The <code class="regex rouge"><span class="pcre2-semantic">(*ACCEPT)</span></code> control verb | |
| (see below) | |
| should not be used within a script run group, because it causes an immediate | |
| exit from the group, bypassing the script run checking.</p></section> | |
| <section class="doc-section level-1"><h2 id="conditional-groups">Conditional groups</h2><p>It is possible to cause the matching process to obey a pattern fragment | |
| conditionally or to choose between two alternative fragments, depending on | |
| the result of an assertion, or whether a specific capture group has | |
| already been matched. The two possible forms of conditional group are:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?(<em>condition</em>)<em>yes-pattern</em>) | |
| (?(<em>condition</em>)<em>yes-pattern</em>|<em>no-pattern</em>)</span></code></pre></div> | |
| <p>If the condition is satisfied, the yes-pattern is used; otherwise the | |
| no-pattern (if present) is used. An absent no-pattern is equivalent to an empty | |
| string (it always matches). If there are more than two alternatives in the | |
| group, a compile-time error occurs. Each of the two alternatives may itself | |
| contain nested groups of any form, including conditional groups; the | |
| restriction to two alternatives applies only at the level of the condition | |
| itself. This pattern fragment is an example where the alternatives are complex:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?(1) (A|B|C) | (D | (?(2)E|F) | E) )</span></code></pre></div> | |
| <p>There are five kinds of condition: references to capture groups, references to | |
| recursion, two pseudo-conditions called DEFINE and VERSION, and assertions.</p> | |
| <section class="doc-section level-2"><h3 id="_checking_for_a_used_capture_group_by_number">Checking for a used capture group by number</h3><p>If the text between the parentheses consists of a sequence of digits, the | |
| condition is true if a capture group of that number has previously matched. If | |
| there is more than one capture group with the same number (see the earlier | |
| section about duplicate group numbers), | |
| the condition is true if any of them have matched. An alternative notation, | |
| which is a PCRE2 extension, not supported by Perl, is to precede the digits | |
| with a plus or minus sign. In this case, the group number is relative rather | |
| than absolute. The most recently opened capture group (which could be enclosing | |
| this condition) can be referenced by <code class="regex rouge"><span class="pcre2-semantic">(?(-1)</span></code>, the next most recent by <code class="regex rouge"><span class="pcre2-semantic">(?(-2)</span></code>, | |
| and so on. Inside loops it can also make sense to refer to subsequent groups. | |
| The next capture group to be opened can be referenced as <code class="regex rouge"><span class="pcre2-semantic">(?(+1)</span></code>, and so on. The | |
| value zero in any of these forms is not used; it provokes a compile-time error.</p> | |
| <p>Consider the following pattern, which contains non-significant white space to | |
| make it more readable (assume the <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED</span></code> option) and to divide it into | |
| three parts for ease of discussion:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">( \( )? [^()]+ (?(1) \) )</span></code></pre></div> | |
| <p>The first part matches an optional opening parenthesis, and if that | |
| character is present, sets it as the first captured substring. The second part | |
| matches one or more characters that are not parentheses. The third part is a | |
| conditional group that tests whether or not the first capture group | |
| matched. If it did, that is, if subject started with an opening parenthesis, | |
| the condition is true, and so the yes-pattern is executed and a closing | |
| parenthesis is required. Otherwise, since no-pattern is not present, the | |
| conditional group matches nothing. In other words, this pattern matches a | |
| sequence of non-parentheses, optionally enclosed in parentheses.</p> | |
| <p>If you were embedding this pattern in a larger one, you could use a relative | |
| reference:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">...other stuff... ( \( )? [^()]+ (?(-1) \) ) ...</span></code></pre></div> | |
| <p>This makes the fragment independent of the parentheses in the larger pattern.</p></section> | |
| <section class="doc-section level-2"><h3 id="_checking_for_a_used_capture_group_by_name">Checking for a used capture group by name</h3><p>Perl uses the syntax <code class="regex rouge"><span class="pcre2-semantic">(?(<<em>name</em>>)...)</span></code> or <code class="regex rouge"><span class="pcre2-semantic">(?('<em>name</em>')...)</span></code> to test for a used | |
| capture group by name. For compatibility with earlier versions of PCRE1, which | |
| had this facility before Perl, the syntax <code class="regex rouge"><span class="pcre2-semantic">(?(<em>name</em>)...)</span></code> is also recognized. | |
| Note, however, that undelimited names consisting of the letter R followed by | |
| digits are ambiguous (see the section <a href="#checking-pattern-recursion">Checking for pattern recursion</a>). Rewriting the above example | |
| to use a named group gives this:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?<OPEN> \( )? [^()]+ (?(<OPEN>) \) )</span></code></pre></div> | |
| <p>If the name used in a condition of this kind is a duplicate, the test is | |
| applied to all groups of the same name, and is true if any one of them has | |
| matched.</p></section> | |
| <section class="doc-section level-2"><h3 id="checking-pattern-recursion">Checking for pattern recursion</h3><p>"Recursion" in this sense refers to any subroutine-like call from one part of | |
| the pattern to another, whether or not it is actually recursive. See the | |
| sections <a href="#recursive-patterns">Recursive patterns</a> | |
| and | |
| <a href="#groups-as-subroutines">Groups as subroutines</a> | |
| below for details of recursion and subroutine calls.</p> | |
| <p>If a condition is the string <code class="regex rouge"><span class="pcre2-semantic">(R)</span></code>, and there is no capture group with the name | |
| R, the condition is true if matching is currently in a recursion or subroutine | |
| call to the whole pattern or any capture group. If digits follow the letter R, | |
| and there is no group with that name, the condition is true if the most recent | |
| call is into a group with the given number, which must exist somewhere in the | |
| overall pattern. This is a contrived example that is equivalent to <code class="regex rouge"><span class="pcre2-semantic">a+b</span></code>:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">((?(R1)a+|(?1)b))</span></code></pre></div> | |
| <p>However, in both cases, if there is a capture group with a matching name, the | |
| condition tests for its being set, as described in the section above, instead | |
| of testing for recursion. For example, creating a group with the name R1 by | |
| adding <code class="regex rouge"><span class="pcre2-semantic">(?<R1>)</span></code> to the above pattern completely changes its meaning.</p> | |
| <p>If a name preceded by ampersand follows the letter R, for example:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?(R&<em>name</em>)...)</span></code></pre></div> | |
| <p>the condition is true if the most recent recursion is into a group of that name | |
| (which must exist within the pattern).</p> | |
| <p>This condition does not check the entire recursion stack. It tests only the | |
| current level. If the name used in a condition of this kind is a duplicate, the | |
| test is applied to all groups of the same name, and is true if any one of | |
| them is the most recent recursion.</p> | |
| <p>At "top level", all these recursion test conditions are false.</p></section> | |
| <section class="doc-section level-2"><h3 id="defining-capture-groups">Defining capture groups for use by reference only</h3><p>If the condition is the string <code class="regex rouge"><span class="pcre2-semantic">(DEFINE)</span></code>, the condition is always false, even if | |
| there is a group with the name DEFINE. In this case, there may be only one | |
| alternative in the rest of the conditional group. It is always skipped if | |
| control reaches this point in the pattern; the idea of DEFINE is that it can be | |
| used to define subroutines that can be referenced from elsewhere. (The use of | |
| subroutines | |
| is described below.) For example, a pattern to match an IPv4 address such as | |
| <code class="subject rouge"><span class="pcre2-semantic">192.168.23.245</span></code> could be written like this (ignore white space and line | |
| breaks):</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?(DEFINE) (?<byte> 2[0-4]\d | 25[0-5] | 1\d\d | [1-9]?\d) ) | |
| \b (?&byte) (\.(?&byte)){3} \b</span></code></pre></div> | |
| <p>The first part of the pattern is a DEFINE group inside which another group | |
| named "byte" is defined. This matches an individual component of an IPv4 | |
| address (a number less than 256). When matching takes place, this part of the | |
| pattern is skipped because DEFINE acts like a false condition. The rest of the | |
| pattern uses references to the named group to match the four dot-separated | |
| components of an IPv4 address, insisting on a word boundary at each end.</p></section> | |
| <section class="doc-section level-2"><h3 id="_checking_the_pcre2_version">Checking the PCRE2 version</h3><p>Programs that link with a PCRE2 library can check the version by calling | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_config()</span></code> with appropriate arguments. Users of applications that do | |
| not have access to the underlying code cannot do this. A special "condition" | |
| called VERSION exists to allow such users to discover which version of PCRE2 | |
| they are dealing with by using this condition to match a string such as | |
| <code class="subject rouge"><span class="pcre2-semantic">yesno</span></code>. VERSION must be followed either by <code class="regex rouge"><span class="pcre2-semantic">=</span></code> or <code class="regex rouge"><span class="pcre2-semantic">>=</span></code> and a version number. | |
| For example:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?(VERSION>=10.4)yes|no)</span></code></pre></div> | |
| <p>This pattern matches <code class="subject rouge"><span class="pcre2-semantic">yes</span></code> if the PCRE2 version is greater or equal to 10.4, or | |
| <code class="subject rouge"><span class="pcre2-semantic">no</span></code> otherwise. The fractional part of the version number could be ommited.</p></section> | |
| <section class="doc-section level-2"><h3 id="_assertion_conditions">Assertion conditions</h3><p>If the condition is not in any of the above formats, it must be a parenthesized | |
| assertion. This may be a positive or negative lookahead or lookbehind | |
| assertion. However, it must be a traditional atomic assertion, not one of the | |
| non-atomic assertions.</p> | |
| <p>Consider this pattern, again containing non-significant white space, and with | |
| the two alternatives on the second line:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?(?=[^a-z]*[a-z]) | |
| \d{2}-[a-z]{3}-\d{2} | \d{2}-\d{2}-\d{2} )</span></code></pre></div> | |
| <p>The condition is a positive lookahead assertion that matches an optional | |
| sequence of non-letters followed by a letter. In other words, it tests for the | |
| presence of at least one letter in the subject. If a letter is found, the | |
| subject is matched against the first alternative; otherwise it is matched | |
| against the second. This pattern matches strings in one of the two forms | |
| <code class="subject rouge"><span class="pcre2-semantic"><em>dd</em>-<em>aaa</em>-<em>dd</em></span></code> or <code class="subject rouge"><span class="pcre2-semantic"><em>dd</em>-<em>dd</em>-<em>dd</em></span></code>, where <em>aaa</em> are letters and <em>dd</em> are digits.</p> | |
| <p>When an assertion that is a condition contains capture groups, any | |
| capturing that occurs in a matching branch is retained afterwards, for both | |
| positive and negative assertions, because matching always continues after the | |
| assertion, whether it succeeds or fails. (Compare non-conditional assertions, | |
| for which captures are retained only for positive assertions that succeed.)</p></section></section> | |
| <section class="doc-section level-1"><h2 id="_comments">Comments</h2><p>There are two ways of including comments in patterns that are processed by | |
| PCRE2. In both cases, the start of the comment must not be in a character | |
| class, nor in the middle of any other sequence of related characters such as | |
| <code class="regex rouge"><span class="pcre2-semantic">(?:</span></code> or a group name or number or a Unicode property name. The characters that | |
| make up a comment play no part in the pattern matching.</p> | |
| <p>The sequence <code class="regex rouge"><span class="pcre2-semantic">(?#</span></code> marks the start of a comment that continues up to the next | |
| closing parenthesis. Nested parentheses are not permitted. If the | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED</span></code> or <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED_MORE</span></code> option is set, an unescaped # character | |
| also introduces a comment, which in this case continues to immediately after | |
| the next newline character or character sequence in the pattern. Which | |
| characters are interpreted as newlines is controlled by an option passed to the | |
| compiling function or by a special sequence at the start of the pattern, as | |
| described in the section <a href="#newline-conventions">Newline conventions</a> | |
| above. Note that the end of this type of comment is a literal newline sequence | |
| in the pattern; escape sequences that happen to represent a newline do not | |
| count. For example, consider this pattern when <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED</span></code> is set, and the | |
| default newline convention (a single linefeed character) is in force:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">abc #comment \n still comment</span></code></pre></div> | |
| <p>On encountering the # character, <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code> skips along, looking for | |
| a newline in the pattern. The sequence <code class="regex rouge"><span class="pcre2-semantic">\n</span></code> is still literal at this stage, so | |
| it does not terminate the comment. Only an actual character with the code value | |
| <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-73"><code class="character pcre2-api rouge"><span class="sc">0x0a</span></code><span class="character-card" id="pcre2-character-73" 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> (the default newline) does so.</p></section> | |
| <section class="doc-section level-1"><h2 id="recursive-patterns">Recursive patterns</h2><p>Consider the problem of matching a string in parentheses, allowing for | |
| unlimited nested parentheses. Without the use of recursion, the best that can | |
| be done is to use a pattern that matches up to some fixed depth of nesting. It | |
| is not possible to handle an arbitrary nesting depth.</p> | |
| <p>For some time, Perl has provided a facility that allows regular expressions to | |
| recurse (amongst other things). It does this by interpolating Perl code in the | |
| expression at run time, and the code can refer to the expression itself. A Perl | |
| pattern using code interpolation to solve the parentheses problem can be | |
| created like this:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="perl"><span class="nv">$re</span> <span class="o">=</span> <span class="sx">qr{\( (?: (?>[^()]+) | (?p{$re}) )* \)}</span><span class="nv">x</span><span class="p">;</span></code></pre></div> | |
| <p>The <code class="regex rouge"><span class="pcre2-semantic">(?p{...})</span></code> item interpolates Perl code at run time, and in this case refers | |
| recursively to the pattern in which it appears.</p> | |
| <p>Obviously, PCRE2 cannot support the interpolation of Perl code. Instead, it | |
| supports special syntax for recursion of the entire pattern, and also for | |
| individual capture group recursion. After its introduction in PCRE1 and Python, | |
| this kind of recursion was subsequently introduced into Perl at release 5.10.</p> | |
| <p>A special item that consists of <code class="regex rouge"><span class="pcre2-semantic">(?</span></code> followed by a number greater than zero and a | |
| closing parenthesis is a recursive subroutine call of the capture group of the | |
| given number, provided that it occurs inside that group. (If not, it is a | |
| non-recursive subroutine | |
| call, which is described in the section <a href="#groups-as-subroutines">Groups as subroutines</a>.) The special item <code class="regex rouge"><span class="pcre2-semantic">(?R)</span></code> or <code class="regex rouge"><span class="pcre2-semantic">(?0)</span></code> is | |
| a recursive call of the entire regular expression.</p> | |
| <p>This PCRE2 pattern solves the nested parentheses problem (assume the | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED</span></code> option is set so that white space is ignored):</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">\( ( [^()]++ | (?R) )* \)</span></code></pre></div> | |
| <p>First it matches an opening parenthesis. Then it matches any number of | |
| substrings which can either be a sequence of non-parentheses, or a recursive | |
| match of the pattern itself (that is, a correctly parenthesized substring). | |
| Finally there is a closing parenthesis. Note the use of a possessive quantifier | |
| to avoid backtracking into sequences of non-parentheses.</p> | |
| <p>If this were part of a larger pattern, you would not want to recurse the entire | |
| pattern, so instead you could use this:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">( \( ( [^()]++ | (?1) )* \) )</span></code></pre></div> | |
| <p>We have put the pattern into parentheses, and caused the recursion to refer to | |
| them instead of the whole pattern.</p> | |
| <p>In a larger pattern, keeping track of parenthesis numbers can be tricky. This | |
| is made easier by the use of relative references. Instead of <code class="regex rouge"><span class="pcre2-semantic">(?1)</span></code> in the | |
| pattern above you can write <code class="regex rouge"><span class="pcre2-semantic">(?-2)</span></code> to refer to the second most recently opened | |
| parentheses preceding the recursion. In other words, a negative number counts | |
| capturing parentheses leftwards from the point at which it is encountered.</p> | |
| <p>Be aware however, that if | |
| duplicate capture group numbers | |
| are in use, relative references refer to the earliest group with the | |
| appropriate number. Consider, for example:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?|(a)|(b)) (c) (?-2)</span></code></pre></div> | |
| <p>The first two capture groups <code class="regex rouge"><span class="pcre2-semantic">(a)</span></code> and <code class="regex rouge"><span class="pcre2-semantic">(b)</span></code> are both numbered 1, and group <code class="regex rouge"><span class="pcre2-semantic">(c)</span></code> | |
| is number 2. When the reference <code class="regex rouge"><span class="pcre2-semantic">(?-2)</span></code> is encountered, the second most recently | |
| opened parentheses has the number 1, but it is the first such group (the <code class="regex rouge"><span class="pcre2-semantic">(a)</span></code> | |
| group) to which the recursion refers. This would be the same if an absolute | |
| reference <code class="regex rouge"><span class="pcre2-semantic">(?1)</span></code> was used. In other words, relative references are just a | |
| shorthand for computing a group number.</p> | |
| <p>It is also possible to refer to subsequent capture groups, by writing | |
| references such as <code class="regex rouge"><span class="pcre2-semantic">(?+2)</span></code>. However, these cannot be recursive because the | |
| reference is not inside the parentheses that are referenced. They are always | |
| non-recursive subroutine | |
| calls, as described in the section <a href="#groups-as-subroutines">Groups as subroutines</a>.</p> | |
| <p>An alternative approach is to use named parentheses. The Perl syntax for this | |
| is <code class="regex rouge"><span class="pcre2-semantic">(?&<em>name</em>)</span></code>; PCRE1’s earlier syntax <code class="regex rouge"><span class="pcre2-semantic">(?P><em>name</em>)</span></code> is also supported. We could | |
| rewrite the above example as follows:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?<pn> \( ( [^()]++ | (?&pn) )* \) )</span></code></pre></div> | |
| <p>If there is more than one group with the same name, the earliest one is | |
| used.</p> | |
| <p>The example pattern that we have been looking at contains nested unlimited | |
| repeats, and so the use of a possessive quantifier for matching strings of | |
| non-parentheses is important when applying the pattern to strings that do not | |
| match. For example, when this pattern is applied to</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa()</span></code></pre></div> | |
| <p>it yields "no match" quickly. However, if a possessive quantifier is not used, | |
| the match runs for a very long time indeed because there are so many different | |
| ways the <code class="regex rouge"><span class="pcre2-semantic">+</span></code> and <code class="regex rouge"><span class="pcre2-semantic">*</span></code> repeats can carve up the subject, and all have to be tested | |
| before failure can be reported.</p> | |
| <p>At the end of a match, the values of capturing parentheses are those from | |
| the outermost level. If you want to obtain intermediate values, a callout | |
| function can be used (see below and the | |
| <a href="./pcre2callout.html"><code>pcre2callout</code></a> | |
| documentation). If the pattern above is matched against</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(ab(cd)ef)</span></code></pre></div> | |
| <p>the value for the inner capturing parentheses (numbered 2) is <code class="subject rouge"><span class="pcre2-semantic">ef</span></code>, which is | |
| the last value taken on at the top level. If a capture group is not matched at | |
| the top level, its final captured value is unset, even if it was (temporarily) | |
| set at a deeper level during the matching process.</p> | |
| <p>Do not confuse the <code class="regex rouge"><span class="pcre2-semantic">(?R)</span></code> item with the condition <code class="regex rouge"><span class="pcre2-semantic">(R)</span></code>, which tests for recursion. | |
| Consider this pattern, which matches text in angle brackets, allowing for | |
| arbitrary nesting. Only digits are allowed in nested brackets (that is, when | |
| recursing), whereas any characters are permitted at the outer level.</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">< (?: (?(R) \d++ | [^<>]*+) | (?R)) * ></span></code></pre></div> | |
| <p>In this pattern, <code class="regex rouge"><span class="pcre2-semantic">(?(R)</span></code> is the start of a conditional group, with two different | |
| alternatives for the recursive and non-recursive cases. The <code class="regex rouge"><span class="pcre2-semantic">(?R)</span></code> item is the | |
| actual recursive call.</p> | |
| <section class="doc-section level-2"><h3 id="_differences_in_recursion_processing_between_pcre2_and_perl">Differences in recursion processing between PCRE2 and Perl</h3><p>Some former differences between PCRE2 and Perl no longer exist.</p> | |
| <p>Before release 10.30, recursion processing in PCRE2 differed from Perl in that | |
| a recursive subroutine call was always treated as an atomic group. That is, | |
| once it had matched some of the subject string, it was never re-entered, even | |
| if it contained untried alternatives and there was a subsequent matching | |
| failure. (Historical note: PCRE implemented recursion before Perl did.)</p> | |
| <p>Starting with release 10.30, recursive subroutine calls are no longer treated | |
| as atomic. That is, they can be re-entered to try unused alternatives if there | |
| is a matching failure later in the pattern. This is now compatible with the way | |
| Perl works. If you want a subroutine call to be atomic, you must explicitly | |
| enclose it in an atomic group.</p> | |
| <p>Supporting backtracking into recursions simplifies certain types of recursive | |
| pattern. For example, this pattern matches palindromic strings:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">^((.)(?1)\2|.?)$</span></code></pre></div> | |
| <p>The second branch in the group matches a single central character in the | |
| palindrome when there are an odd number of characters, or nothing when there | |
| are an even number of characters, but in order to work it has to be able to try | |
| the second case when the rest of the pattern match fails. If you want to match | |
| typical palindromic phrases, the pattern has to ignore all non-word characters, | |
| which can be done like this:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">^\W*+((.)\W*+(?1)\W*+\2|\W*+.?)\W*+$</span></code></pre></div> | |
| <p>If run with the <code class="constant pcre2-api rouge"><span class="no">PCRE2_CASELESS</span></code> option, this pattern matches phrases such as <code class="subject rouge"><span class="pcre2-semantic">A | |
| man, a plan, a canal: Panama!</span></code>. Note the use of the possessive quantifier <code class="regex rouge"><span class="pcre2-semantic">*+</span></code> to | |
| avoid backtracking into sequences of non-word characters. Without this, PCRE2 | |
| takes a great deal longer (ten times or more) to match typical phrases, and | |
| Perl takes so long that you think it has gone into a loop.</p> | |
| <p>Another way in which PCRE2 and Perl used to differ in their recursion | |
| processing is in the handling of captured values. Formerly in Perl, when a | |
| group was called recursively or as a subroutine (see the section | |
| <a href="#groups-as-subroutines">Groups as subroutines</a>), it | |
| had no access to any values that were captured outside the recursion, whereas | |
| in PCRE2 these values can be referenced. Consider this pattern:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">^(.)(\1|a(?2))</span></code></pre></div> | |
| <p>This pattern matches <code class="subject rouge"><span class="pcre2-semantic">bab</span></code>. The first capturing parentheses match <code class="subject rouge"><span class="pcre2-semantic">b</span></code>, then in | |
| the second group, when the backreference <code class="regex rouge"><span class="pcre2-semantic">\1</span></code> fails to match <code class="subject rouge"><span class="pcre2-semantic">b</span></code>, the second | |
| alternative matches <code class="subject rouge"><span class="pcre2-semantic">a</span></code> and then recurses. In the recursion, <code class="regex rouge"><span class="pcre2-semantic">\1</span></code> does now match | |
| <code class="subject rouge"><span class="pcre2-semantic">b</span></code> and so the whole match succeeds. This match used to fail in Perl, but in | |
| later versions (I tried 5.024) it now works.</p></section> | |
| <section class="doc-section level-2"><h3 id="groups-as-subroutines">Groups as subroutines</h3><p>If the syntax for a recursive group call (either by number or by name) is used | |
| outside the parentheses to which it refers, it operates a bit like a subroutine | |
| in a programming language. More accurately, PCRE2 treats the referenced group | |
| as an independent subpattern which it tries to match at the current matching | |
| position. The called group may be defined before or after the reference. A | |
| numbered reference can be absolute or relative, as in these examples:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(...(absolute)...)...(?2)... | |
| (...(relative)...)...(?-1)... | |
| (...(?+1)...(relative)...</span></code></pre></div> | |
| <p>An earlier example pointed out that the pattern</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(sens|respons)e and \1ibility</span></code></pre></div> | |
| <p>matches <code class="subject rouge"><span class="pcre2-semantic">sense and sensibility</span></code> and <code class="subject rouge"><span class="pcre2-semantic">response and responsibility</span></code>, but not | |
| <code class="subject rouge"><span class="pcre2-semantic">sense and responsibility</span></code>. If instead the pattern</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(sens|respons)e and (?1)ibility</span></code></pre></div> | |
| <p>is used, it does match <code class="subject rouge"><span class="pcre2-semantic">sense and responsibility</span></code> as well as the other two | |
| strings. Another example is given in the discussion of DEFINE above.</p> | |
| <p>Like recursions, subroutine calls used to be treated as atomic, but this | |
| changed at PCRE2 release 10.30, so backtracking into subroutine calls can now | |
| occur. However, any capturing parentheses that are set during the subroutine | |
| call revert to their previous values afterwards.</p> | |
| <p>Processing options such as case-independence are fixed when a group is | |
| defined, so if it is used as a subroutine, such options cannot be changed for | |
| different calls. For example, consider this pattern:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(abc)(?i:(?-1))</span></code></pre></div> | |
| <p>It matches <code class="subject rouge"><span class="pcre2-semantic">abcabc</span></code>. It does not match <code class="subject rouge"><span class="pcre2-semantic">abcABC</span></code> because the change of | |
| processing option does not affect the called group.</p> | |
| <p>The behaviour of | |
| backtracking control verbs | |
| in groups when called as subroutines is described in the section | |
| <a href="#backtracking-verbs-in-subroutines">Backtracking verbs in subroutines</a> | |
| below.</p></section> | |
| <section class="doc-section level-2"><h3 id="_recursion_and_subroutines_with_returned_capture_groups">Recursion and subroutines with returned capture groups</h3><p>Since PCRE2 10.47, recursion and subroutine calls may also specify a list of | |
| capture groups to return. This is a PCRE2 syntax extension not supported by | |
| Perl. The pattern matching recurses into the referenced expression as described | |
| above, however, when the recursion returns to the calling expression the | |
| subgroups captured during the recursion can be retained when the calling | |
| expression’s context is restored.</p> | |
| <p>When used as a subroutine, this allows the subroutine’s capture groups to | |
| be used as return values.</p> | |
| <p>Only the specific capture groups listed by the caller will be retained, using | |
| the following syntax:</p> | |
| <dl class="spaced" style="--tab-width: 14"><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">(?R(<em>grouplist</em>))</span></code><br><code class="regex rouge"><span class="pcre2-semantic">(?<em>n</em>(<em>grouplist</em>))</span></code><br><code class="regex rouge"><span class="pcre2-semantic">(?+<em>n</em>(<em>grouplist</em>))</span></code></span></dt><dd>Recurse the whole pattern, returning capture groups.</dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">(?-<em>n</em>(<em>grouplist</em>))</span></code><br><code class="regex rouge"><span class="pcre2-semantic">(?&<em>name</em>(<em>grouplist</em>))</span></code><br><code class="regex rouge"><span class="pcre2-semantic">(?P><em>name</em>(<em>grouplist</em>))</span></code></span></dt><dd>Call a subroutine, returning capture groups.</dd></div></dl> | |
| <p>The list of capture groups <em>grouplist</em> is a comma-separated list of (absolute | |
| or relative) group numbers, and group names enclosed in single quotes or angle | |
| brackets.</p> | |
| <p>Here is an example which first uses the DEFINE condition to create a re-usable | |
| routine for matching a weekday, then calls that subroutine and retains the | |
| groups it captures for use later:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?x: # ignore whitespace for clarity | |
| # Define the routine "weekendday" which matches Saturday or | |
| # Sunday, and returns the Sat/Sun prefix as \k<short>. | |
| (?(DEFINE) (?<weekendday> | |
| (?|(?<short>Sat)urday|(?<short>Sun)day) ) ) | |
| # Call the routine. Matches "Saturday,Sat" or "Sunday,Sun". | |
| (?&weekendday(<short>)),\k<short> )</span></code></pre></div> | |
| <p>This feature is not available using the Oniguruma syntax <code class="regex rouge"><span class="pcre2-semantic">\g<...></span></code> or <code class="regex rouge"><span class="pcre2-semantic">\g'...'</span></code> | |
| below.</p></section> | |
| <section class="doc-section level-2"><h3 id="_oniguruma_subroutine_syntax">Oniguruma subroutine syntax</h3><p>For compatibility with Oniguruma, the non-Perl syntax <code class="regex rouge"><span class="pcre2-semantic">\g</span></code> followed by a name or | |
| a number enclosed either in angle brackets or single quotes, is an alternative | |
| syntax for calling a group as a subroutine, possibly recursively. Here are two | |
| of the examples used above, rewritten using this syntax:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?<pn> \( ( (?>[^()]+) | \g<pn> )* \) ) | |
| (sens|respons)e and \g'1'ibility</span></code></pre></div> | |
| <p>PCRE2 supports an extension to Oniguruma: if a number is preceded by a | |
| plus or a minus sign it is taken as a relative reference. For example:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(abc)(?i:\g<-1>)</span></code></pre></div> | |
| <p>Note that <code class="regex rouge"><span class="pcre2-semantic">\g{...}</span></code> (Perl syntax) and <code class="regex rouge"><span class="pcre2-semantic">\g<...></span></code> (Oniguruma syntax) are <em>not</em> | |
| synonymous. The former is a backreference; the latter is a subroutine call.</p></section></section> | |
| <section class="doc-section level-1"><h2 id="_callouts">Callouts</h2><p>Perl has a feature whereby using the sequence <code class="regex rouge"><span class="pcre2-semantic">(?{...})</span></code> causes arbitrary Perl | |
| code to be obeyed in the middle of matching a regular expression. This makes it | |
| possible, amongst other things, to extract different substrings that match the | |
| same pair of parentheses when there is a repetition.</p> | |
| <p>PCRE2 provides a similar feature, but of course it cannot obey arbitrary Perl | |
| code. The feature is called "callout". The caller of PCRE2 provides an external | |
| function by putting its entry point in a match context using the function | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_set_callout()</span></code>, and then passing that context 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>. If no match context is passed, or if the callout | |
| entry point is set to NULL, callout points will be passed over silently during | |
| matching. To disallow callouts in the pattern syntax, you may use the | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTRA_NEVER_CALLOUT</span></code> option.</p> | |
| <p>Within a regular expression, <code class="regex rouge"><span class="pcre2-semantic">(?C<em>arg</em>)</span></code> indicates a point at which the external | |
| function is to be called. There are two kinds of callout: those with a | |
| numerical argument and those with a string argument. <code class="regex rouge"><span class="pcre2-semantic">(?C)</span></code> on its own with no | |
| argument is treated as <code class="regex rouge"><span class="pcre2-semantic">(?C0)</span></code>. A numerical argument allows the application to | |
| distinguish between different callouts. String arguments were added for release | |
| 10.20 to make it possible for script languages that use PCRE2 to embed short | |
| scripts within patterns in a similar way to Perl.</p> | |
| <p>During matching, when PCRE2 reaches a callout point, the external function is | |
| called. It is provided with the number or string argument of the callout, the | |
| position in the pattern, and one item of data that is also set in the match | |
| block. The callout function may cause matching to proceed, to backtrack, or to | |
| fail.</p> | |
| <p>By default, PCRE2 implements a number of optimizations at matching time, and | |
| one side-effect is that sometimes callouts are skipped. If you need all | |
| possible callouts to happen, you need to set options that disable the relevant | |
| optimizations. More details, including a complete description of the | |
| programming interface to the callout function, are given in the | |
| <a href="./pcre2callout.html"><code>pcre2callout</code></a> | |
| documentation.</p> | |
| <section class="doc-section level-2"><h3 id="_callouts_with_numerical_arguments">Callouts with numerical arguments</h3><p>If you just want to have a means of identifying different callout points, put a | |
| number no greater than 255 after the letter C. For example, this pattern has two | |
| callout points:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?C1)abc(?C2)def</span></code></pre></div> | |
| <p>If the <code class="constant pcre2-api rouge"><span class="no">PCRE2_AUTO_CALLOUT</span></code> flag is passed to <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code>, numerical | |
| callouts are automatically installed before each item in the pattern. They are | |
| all numbered 255. If there is a conditional group in the pattern whose | |
| condition is an assertion, an additional callout is inserted just before the | |
| condition. An explicit callout may also be set at this position, as in this | |
| example:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?(?C9)(?=a)abc|def)</span></code></pre></div> | |
| <p>Note that this applies only to assertion conditions, not to other types of | |
| condition.</p></section> | |
| <section class="doc-section level-2"><h3 id="_callouts_with_string_arguments">Callouts with string arguments</h3><p>A delimited string may be used instead of a number as a callout argument. The | |
| starting delimiter must be one of <code class="regex rouge"><span class="pcre2-semantic">`</span></code>, <code class="regex rouge"><span class="pcre2-semantic">'</span></code>, <code class="regex rouge"><span class="pcre2-semantic">"</span></code>, <code class="regex rouge"><span class="pcre2-semantic">^</span></code>, <code class="regex rouge"><span class="pcre2-semantic">%</span></code>, <code class="regex rouge"><span class="pcre2-semantic">#</span></code>, <code class="regex rouge"><span class="pcre2-semantic">$</span></code> or <code class="regex rouge"><span class="pcre2-semantic">{</span></code> and the ending delimiter is | |
| the same as the start, except for <code class="regex rouge"><span class="pcre2-semantic">{</span></code>, where the ending delimiter is <code class="regex rouge"><span class="pcre2-semantic">}</span></code>. If the | |
| ending delimiter is needed within the string, it must be doubled. For | |
| example:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(?C'ab ''c'' d')xyz(?C{any text})pqr</span></code></pre></div> | |
| <p>The doubling is removed before the string is passed to the callout function.</p></section></section> | |
| <section class="doc-section level-1"><h2 id="_backtracking_control">Backtracking control</h2><p>There are a number of special "Backtracking Control Verbs" (to use Perl’s | |
| terminology) that modify the behaviour of backtracking during matching. They | |
| are generally of the form <code class="regex rouge"><span class="pcre2-semantic">(*VERB)</span></code> or <code class="regex rouge"><span class="pcre2-semantic">(*VERB:<em>NAME</em>)</span></code>. Some verbs take either form, | |
| and may behave differently depending on whether or not a name argument is | |
| present. The names are not required to be unique within the pattern.</p> | |
| <p>By default, for compatibility with Perl, a name is any sequence of characters | |
| that does not include a closing parenthesis. The name is not processed in | |
| any way, and it is not possible to include a closing parenthesis in the name. | |
| This can be changed by setting the <code class="constant pcre2-api rouge"><span class="no">PCRE2_ALT_VERBNAMES</span></code> option, but the result | |
| is no longer Perl-compatible.</p> | |
| <p>When <code class="constant pcre2-api rouge"><span class="no">PCRE2_ALT_VERBNAMES</span></code> is set, backslash processing is applied to verb names | |
| and only an unescaped closing parenthesis terminates the name. However, the | |
| only backslash items that are permitted are <code class="regex rouge"><span class="pcre2-semantic">\Q</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\E</span></code>, and sequences such as | |
| <code class="regex rouge"><span class="pcre2-semantic">\x{100}</span></code> that define character code points. Character type escapes such as <code class="regex rouge"><span class="pcre2-semantic">\d</span></code> | |
| are faulted.</p> | |
| <p>A closing parenthesis can be included in a name either as <code class="regex rouge"><span class="pcre2-semantic">\)</span></code> or between <code class="regex rouge"><span class="pcre2-semantic">\Q</span></code> | |
| and <code class="regex rouge"><span class="pcre2-semantic">\E</span></code>. In addition to backslash processing, if the <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED</span></code> or | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED_MORE</span></code> option is also set, unescaped white space in verb names is | |
| skipped, and #-comments are recognized, exactly as in the rest of the pattern. | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED</span></code> and <code class="constant pcre2-api rouge"><span class="no">PCRE2_EXTENDED_MORE</span></code> do not affect verb names unless | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_ALT_VERBNAMES</span></code> is also set.</p> | |
| <p>The maximum length of a name is 255 in the 8-bit library and 65,535 in the | |
| 16-bit and 32-bit libraries. If the name is empty, that is, if the closing | |
| parenthesis immediately follows the colon, the effect is as if the colon were | |
| not there. Any number of these verbs may occur in a pattern. Except for | |
| <code class="regex rouge"><span class="pcre2-semantic">(*ACCEPT)</span></code>, they may not be quantified.</p> | |
| <p>Since these verbs are specifically related to backtracking, most of them can be | |
| used only when the pattern is to be matched using the traditional matching | |
| function or JIT, because they use backtracking algorithms. With the exception | |
| of <code class="regex rouge"><span class="pcre2-semantic">(*FAIL)</span></code>, which behaves like a failing negative assertion, the backtracking | |
| control verbs cause an error if encountered by the DFA matching function.</p> | |
| <p>The behaviour of these verbs in | |
| repeated groups, | |
| assertions, | |
| and in | |
| capture groups called as subroutines | |
| (whether or not recursively) is documented below.</p> | |
| <section class="doc-section level-2"><h3 id="_optimizations_that_affect_backtracking_verbs">Optimizations that affect backtracking verbs</h3><p>PCRE2 contains some optimizations that are used to speed up matching by running | |
| some checks at the start of each match attempt. For example, it may know the | |
| minimum length of matching subject, or that a particular character must be | |
| present. When one of these optimizations bypasses the running of a match, any | |
| included backtracking verbs will not, of course, be processed. You can suppress | |
| the start-of-match optimizations by setting the <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_START_OPTIMIZE</span></code> option | |
| when calling <code class="function pcre2-api rouge"><span class="nf">pcre2_compile()</span></code>, by calling <code class="function pcre2-api rouge"><span class="nf">pcre2_set_optimize()</span></code> with a | |
| <code class="constant pcre2-api rouge"><span class="no">PCRE2_START_OPTIMIZE_OFF</span></code> directive, or by starting the pattern with | |
| <code class="regex rouge"><span class="pcre2-semantic">(*NO_START_OPT)</span></code>. There is more discussion of this option in the section | |
| <a href="./pcre2api.html#compiling-a-pattern">Compiling a pattern</a> | |
| in the | |
| <a href="./pcre2api.html"><code>pcre2api</code></a> | |
| documentation.</p> | |
| <p>Experiments with Perl suggest that it too has similar optimizations, and like | |
| PCRE2, turning them off can change the result of a match.</p></section> | |
| <section class="doc-section level-2"><h3 id="_verbs_that_act_immediately">Verbs that act immediately</h3><p>The following verbs act as soon as they are encountered.</p> | |
| <dl class="spaced" style="--tab-width: 4"><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">(*ACCEPT)</span></code> or <code class="regex rouge"><span class="pcre2-semantic">(*ACCEPT:<em>NAME</em>)</span></code></span></dt><dd><p>This verb causes the match to end successfully, skipping the remainder of the | |
| pattern. However, when it is inside a capture group that is called as a | |
| subroutine, only that group is ended successfully. Matching then continues | |
| at the outer level. If <code class="regex rouge"><span class="pcre2-semantic">(*ACCEPT)</span></code> in triggered in a positive assertion, the | |
| assertion succeeds; in a negative assertion, the assertion fails.</p><p>If <code class="regex rouge"><span class="pcre2-semantic">(*ACCEPT)</span></code> is inside capturing parentheses, the data so far is captured. For | |
| example:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">A((?:A|B(*ACCEPT)|C)D)</span></code></pre></div> | |
| <p>This matches <code class="subject rouge"><span class="pcre2-semantic">AB</span></code>, <code class="subject rouge"><span class="pcre2-semantic">AAD</span></code>, or <code class="subject rouge"><span class="pcre2-semantic">ACD</span></code>; when it matches <code class="subject rouge"><span class="pcre2-semantic">AB</span></code>, <code class="subject rouge"><span class="pcre2-semantic">B</span></code> is captured by | |
| the outer parentheses.</p> | |
| <p><code class="regex rouge"><span class="pcre2-semantic">(*ACCEPT)</span></code> is the only backtracking verb that is allowed to be quantified | |
| because an ungreedy quantification with a minimum of zero acts only when a | |
| backtrack happens. Consider, for example,</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(A(*ACCEPT)??B)C</span></code></pre></div> | |
| <p>where A, B, and C may be complex expressions. After matching <code class="subject rouge"><span class="pcre2-semantic">A</span></code>, the matcher | |
| processes <code class="subject rouge"><span class="pcre2-semantic">BC</span></code>; if that fails, causing a backtrack, <code class="regex rouge"><span class="pcre2-semantic">(*ACCEPT)</span></code> is triggered and | |
| the match succeeds. In both cases, all but C is captured. Whereas <code class="regex rouge"><span class="pcre2-semantic">(*COMMIT)</span></code> | |
| (see below) means "fail on backtrack", a repeated <code class="regex rouge"><span class="pcre2-semantic">(*ACCEPT)</span></code> of this type means | |
| "succeed on backtrack".</p> | |
| <p>Warning: <code class="regex rouge"><span class="pcre2-semantic">(*ACCEPT)</span></code> should not be used within a script run group, because | |
| it causes an immediate exit from the group, bypassing the script run checking.</p></dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">(*FAIL)</span></code> or <code class="regex rouge"><span class="pcre2-semantic">(*FAIL:<em>NAME</em>)</span></code></span></dt><dd><p>This verb causes a matching failure, forcing backtracking to occur. It may be | |
| abbreviated to <code class="regex rouge"><span class="pcre2-semantic">(*F)</span></code>. It is equivalent to <code class="regex rouge"><span class="pcre2-semantic">(?!)</span></code> but easier to read. The Perl | |
| documentation notes that it is probably useful only when combined with <code class="regex rouge"><span class="pcre2-semantic">(?{})</span></code> or | |
| <code class="regex rouge"><span class="pcre2-semantic">(??{})</span></code>. Those are, of course, Perl features that are not present in PCRE2. The | |
| nearest equivalent is the callout feature, as for example in this pattern:</p><div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">a+(?C)(*FAIL)</span></code></pre></div> | |
| <p>A match with the string <code class="subject rouge"><span class="pcre2-semantic">aaaa</span></code> always fails, but the callout is taken before | |
| each backtrack happens (in this example, 10 times).</p></dd></div></dl> | |
| <p><code class="regex rouge"><span class="pcre2-semantic">(*ACCEPT:<em>NAME</em>)</span></code> and <code class="regex rouge"><span class="pcre2-semantic">(*FAIL:<em>NAME</em>)</span></code> behave the same as <code class="regex rouge"><span class="pcre2-semantic">(*MARK:<em>NAME</em>)(*ACCEPT)</span></code> and | |
| <code class="regex rouge"><span class="pcre2-semantic">(*MARK:<em>NAME</em>)(*FAIL)</span></code>, respectively, that is, a <code class="regex rouge"><span class="pcre2-semantic">(*MARK)</span></code> is recorded just before | |
| the verb acts.</p></section> | |
| <section class="doc-section level-2"><h3 id="_recording_which_path_was_taken">Recording which path was taken</h3><p>There is one verb whose main purpose is to track how a match was arrived at, | |
| though it also has a secondary use in conjunction with advancing the match | |
| starting point (see <code class="regex rouge"><span class="pcre2-semantic">(*SKIP)</span></code> below).</p> | |
| <dl class="spaced" style="--tab-width: 14"><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">(*MARK:<em>NAME</em>)</span></code> or <code class="regex rouge"><span class="pcre2-semantic">(*:<em>NAME</em>)</span></code></span></dt><dd><p>A name is always required with this verb. For all the other backtracking | |
| control verbs, a <em>NAME</em> argument is optional.</p><p>When a match succeeds, the name of the last-encountered mark name on the | |
| matching path is passed back to the caller as described in the section | |
| <a href="./pcre2api.html#other-match-information">Other information about a match</a> | |
| in | |
| <a href="./pcre2api.html"><code>pcre2api</code></a> | |
| documentation. This applies to all instances of <code class="regex rouge"><span class="pcre2-semantic">(*MARK)</span></code> and other verbs, | |
| including those inside assertions and atomic groups. However, there are | |
| differences in those cases when <code class="regex rouge"><span class="pcre2-semantic">(*MARK)</span></code> is used in conjunction with <code class="regex rouge"><span class="pcre2-semantic">(*SKIP)</span></code> as | |
| described below.</p> | |
| <p>The mark name that was last encountered on the matching path is passed back. A | |
| verb without a <em>NAME</em> argument is ignored for this purpose. Here is an example of | |
| <code>pcre2test</code> output, where the "mark" modifier requests the retrieval and | |
| outputting of <code class="regex rouge"><span class="pcre2-semantic">(*MARK)</span></code> data:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="text"> re> /X(*MARK:A)Y|X(*MARK:B)Z/mark | |
| data> XY | |
| 0: XY | |
| MK: A | |
| XZ | |
| 0: XZ | |
| MK: B</code></pre></div> | |
| <p>The <code class="regex rouge"><span class="pcre2-semantic">(*MARK)</span></code> name is tagged with "MK:" in this output, and in this example it | |
| indicates which of the two alternatives matched. This is a more efficient way | |
| of obtaining this information than putting each alternative in its own | |
| capturing parentheses.</p> | |
| <p>If a verb with a name is encountered in a positive assertion that is true, the | |
| name is recorded and passed back if it is the last-encountered. This does not | |
| happen for negative assertions or failing positive assertions.</p> | |
| <p>After a partial match or a failed match, the last encountered name in the | |
| entire match process is returned. For example:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="text"> re> /X(*MARK:A)Y|X(*MARK:B)Z/mark | |
| data> XP | |
| No match, mark = B</code></pre></div> | |
| <p>Note that in this unanchored example the mark is retained from the match | |
| attempt that started at the letter "X" in the subject. Subsequent match | |
| attempts starting at "P" and then with an empty string do not get as far as the | |
| <code class="regex rouge"><span class="pcre2-semantic">(*MARK)</span></code> item, but nevertheless do not reset it.</p> | |
| <p>If you are interested in <code class="regex rouge"><span class="pcre2-semantic">(*MARK)</span></code> values after failed matches, you should | |
| probably either set the <code class="constant pcre2-api rouge"><span class="no">PCRE2_NO_START_OPTIMIZE</span></code> option or call | |
| <code class="function pcre2-api rouge"><span class="nf">pcre2_set_optimize()</span></code> with a <code class="constant pcre2-api rouge"><span class="no">PCRE2_START_OPTIMIZE_OFF</span></code> directive | |
| (see above) | |
| to ensure that the match is always attempted.</p></dd></div></dl></section> | |
| <section class="doc-section level-2"><h3 id="_verbs_that_act_after_backtracking">Verbs that act after backtracking</h3><p>The following verbs do nothing when they are encountered. Matching continues | |
| with what follows, but if there is a subsequent match failure, causing a | |
| backtrack to the verb, a failure is forced. That is, backtracking cannot pass | |
| to the left of the verb. However, when one of these verbs appears inside an | |
| atomic group or in an atomic lookaround assertion that is true, its effect is | |
| confined to that group, because once the group has been matched, there is never | |
| any backtracking into it. Backtracking from beyond an atomic assertion or group | |
| ignores the entire group, and seeks a preceding backtracking point.</p> | |
| <p>These verbs differ in exactly what kind of failure occurs when backtracking | |
| reaches them. The behaviour described below is what happens when the verb is | |
| not in a subroutine or an assertion. Subsequent sections cover these special | |
| cases.</p> | |
| <dl class="spaced" style="--tab-width: 14"><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">(*COMMIT)</span></code> or <code class="regex rouge"><span class="pcre2-semantic">(*COMMIT:<em>NAME</em>)</span></code></span></dt><dd><p>This verb causes the whole match to fail outright if there is a later matching | |
| failure that causes backtracking to reach it. Even if the pattern is | |
| unanchored, no further attempts to find a match by advancing the starting point | |
| take place. If <code class="regex rouge"><span class="pcre2-semantic">(*COMMIT)</span></code> is the only backtracking verb that is encountered, | |
| once it has been passed <code class="function pcre2-api rouge"><span class="nf">pcre2_match()</span></code> is committed to finding a match at | |
| the current starting point, or not at all. For example:</p><div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">a+(*COMMIT)b</span></code></pre></div> | |
| <p>This matches <code class="subject rouge"><span class="pcre2-semantic">xxaab</span></code> but not <code class="subject rouge"><span class="pcre2-semantic">aacaab</span></code>. It can be thought of as a kind of | |
| dynamic anchor, or "I’ve started, so I must finish."</p> | |
| <p>The behaviour of <code class="regex rouge"><span class="pcre2-semantic">(*COMMIT:<em>NAME</em>)</span></code> is not the same as <code class="regex rouge"><span class="pcre2-semantic">(*MARK:<em>NAME</em>)(*COMMIT)</span></code>. It is | |
| like <code class="regex rouge"><span class="pcre2-semantic">(*MARK:<em>NAME</em>)</span></code> in that the name is remembered for passing back to the | |
| caller. However, <code class="regex rouge"><span class="pcre2-semantic">(*SKIP:<em>NAME</em>)</span></code> searches only for names that are set with | |
| <code class="regex rouge"><span class="pcre2-semantic">(*MARK)</span></code>, ignoring those set by any of the other backtracking verbs.</p> | |
| <p>If there is more than one backtracking verb in a pattern, a different one that | |
| follows <code class="regex rouge"><span class="pcre2-semantic">(*COMMIT)</span></code> may be triggered first, so merely passing <code class="regex rouge"><span class="pcre2-semantic">(*COMMIT)</span></code> during a | |
| match does not always guarantee that a match must be at this starting point.</p> | |
| <p>Note that <code class="regex rouge"><span class="pcre2-semantic">(*COMMIT)</span></code> at the start of a pattern is not the same as an anchor, | |
| unless PCRE2’s start-of-match optimizations are turned off, as shown in this | |
| output from <code>pcre2test</code>:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="text"> re> /(*COMMIT)abc/ | |
| data> xyzabc | |
| 0: abc | |
| data> | |
| re> /(*COMMIT)abc/no_start_optimize | |
| data> xyzabc | |
| No match</code></pre></div> | |
| <p>For the first pattern, PCRE2 knows that any match must start with <code class="subject rouge"><span class="pcre2-semantic">a</span></code>, so the | |
| optimization skips along the subject to <code class="subject rouge"><span class="pcre2-semantic">a</span></code> before applying the pattern to the | |
| first set of data. The match attempt then succeeds. The second pattern disables | |
| the optimization that skips along to the first character. The pattern is now | |
| applied starting at <code class="subject rouge"><span class="pcre2-semantic">x</span></code>, and so the <code class="regex rouge"><span class="pcre2-semantic">(*COMMIT)</span></code> causes the match to fail without | |
| trying any other starting points.</p></dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">(*PRUNE)</span></code> or <code class="regex rouge"><span class="pcre2-semantic">(*PRUNE:<em>NAME</em>)</span></code></span></dt><dd><p>This verb causes the match to fail at the current starting position in the | |
| subject if there is a later matching failure that causes backtracking to reach | |
| it. If the pattern is unanchored, the normal "bumpalong" advance to the next | |
| starting character then happens. Backtracking can occur as usual to the left of | |
| <code class="regex rouge"><span class="pcre2-semantic">(*PRUNE)</span></code>, before it is reached, or when matching to the right of <code class="regex rouge"><span class="pcre2-semantic">(*PRUNE)</span></code>, but | |
| if there is no match to the right, backtracking cannot cross <code class="regex rouge"><span class="pcre2-semantic">(*PRUNE)</span></code>. In | |
| simple cases, the use of <code class="regex rouge"><span class="pcre2-semantic">(*PRUNE)</span></code> is just an alternative to an atomic group or | |
| possessive quantifier, but there are some uses of <code class="regex rouge"><span class="pcre2-semantic">(*PRUNE)</span></code> that cannot be | |
| expressed in any other way. In an anchored pattern <code class="regex rouge"><span class="pcre2-semantic">(*PRUNE)</span></code> has the same effect | |
| as <code class="regex rouge"><span class="pcre2-semantic">(*COMMIT)</span></code>.</p><p>The behaviour of <code class="regex rouge"><span class="pcre2-semantic">(*PRUNE:<em>NAME</em>)</span></code> is not the same as <code class="regex rouge"><span class="pcre2-semantic">(*MARK:<em>NAME</em>)(*PRUNE)</span></code>. It is | |
| like <code class="regex rouge"><span class="pcre2-semantic">(*MARK:<em>NAME</em>)</span></code> in that the name is remembered for passing back to the | |
| caller. However, <code class="regex rouge"><span class="pcre2-semantic">(*SKIP:<em>NAME</em>)</span></code> searches only for names set with <code class="regex rouge"><span class="pcre2-semantic">(*MARK)</span></code>, | |
| ignoring those set by other backtracking verbs.</p></dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">(*SKIP)</span></code></span></dt><dd><p>This verb, when given without a name, is like <code class="regex rouge"><span class="pcre2-semantic">(*PRUNE)</span></code>, except that if the | |
| pattern is unanchored, the "bumpalong" advance is not to the next character, | |
| but to the position in the subject where <code class="regex rouge"><span class="pcre2-semantic">(*SKIP)</span></code> was encountered. <code class="regex rouge"><span class="pcre2-semantic">(*SKIP)</span></code> | |
| signifies that whatever text was matched leading up to it cannot be part of a | |
| successful match if there is a later mismatch. Consider:</p><div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">a+(*SKIP)b</span></code></pre></div> | |
| <p>If the subject is <code class="subject rouge"><span class="pcre2-semantic">aaaac…</span></code>, after the first match attempt fails (starting at | |
| the first character in the string), the starting point skips on to start the | |
| next attempt at <code class="subject rouge"><span class="pcre2-semantic">c</span></code>. Note that a possessive quantifier does not have the same | |
| effect as this example; although it would suppress backtracking during the | |
| first match attempt, the second attempt would start at the second character | |
| instead of skipping on to "c".</p> | |
| <p>If <code class="regex rouge"><span class="pcre2-semantic">(*SKIP)</span></code> is used to specify a new starting position that is the same as the | |
| starting position of the current match, or (by being inside a lookbehind) | |
| earlier, the position specified by <code class="regex rouge"><span class="pcre2-semantic">(*SKIP)</span></code> is ignored, and instead the normal | |
| "bumpalong" occurs.</p></dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">(*SKIP:<em>NAME</em>)</span></code></span></dt><dd><p>When <code class="regex rouge"><span class="pcre2-semantic">(*SKIP)</span></code> has an associated name, its behaviour is modified. When such a | |
| <code class="regex rouge"><span class="pcre2-semantic">(*SKIP)</span></code> is triggered, the previous path through the pattern is searched for the | |
| most recent <code class="regex rouge"><span class="pcre2-semantic">(*MARK)</span></code> that has the same name. If one is found, the "bumpalong" | |
| advance is to the subject position that corresponds to that <code class="regex rouge"><span class="pcre2-semantic">(*MARK)</span></code> instead of | |
| to where <code class="regex rouge"><span class="pcre2-semantic">(*SKIP)</span></code> was encountered. If no <code class="regex rouge"><span class="pcre2-semantic">(*MARK)</span></code> with a matching name is found, | |
| the <code class="regex rouge"><span class="pcre2-semantic">(*SKIP)</span></code> is ignored.</p><p>The search for a <code class="regex rouge"><span class="pcre2-semantic">(*MARK)</span></code> name uses the normal backtracking mechanism, which | |
| means that it does not see <code class="regex rouge"><span class="pcre2-semantic">(*MARK)</span></code> settings that are inside atomic groups or | |
| assertions, because they are never re-entered by backtracking. Compare the | |
| following <code>pcre2test</code> examples:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="text"> re> /a(?>(*MARK:X))(*SKIP:X)(*F)|(.)/ | |
| data: abc | |
| 0: a | |
| 1: a | |
| data: | |
| re> /a(?:(*MARK:X))(*SKIP:X)(*F)|(.)/ | |
| data: abc | |
| 0: b | |
| 1: b</code></pre></div> | |
| <p>In the first example, the <code class="regex rouge"><span class="pcre2-semantic">(*MARK)</span></code> setting is in an atomic group, so it is not | |
| seen when <code class="regex rouge"><span class="pcre2-semantic">(*SKIP:X)</span></code> triggers, causing the <code class="regex rouge"><span class="pcre2-semantic">(*SKIP)</span></code> to be ignored. This allows | |
| the second branch of the pattern to be tried at the first character position. | |
| In the second example, the <code class="regex rouge"><span class="pcre2-semantic">(*MARK)</span></code> setting is not in an atomic group. This | |
| allows <code class="regex rouge"><span class="pcre2-semantic">(*SKIP:X)</span></code> to find the <code class="regex rouge"><span class="pcre2-semantic">(*MARK)</span></code> when it backtracks, and this causes a new | |
| matching attempt to start at the second character. This time, the <code class="regex rouge"><span class="pcre2-semantic">(*MARK)</span></code> is | |
| never seen because <code class="subject rouge"><span class="pcre2-semantic">a</span></code> does not match <code class="subject rouge"><span class="pcre2-semantic">b</span></code>, so the matcher immediately jumps to | |
| the second branch of the pattern.</p> | |
| <p>Note that <code class="regex rouge"><span class="pcre2-semantic">(*SKIP:<em>NAME</em>)</span></code> searches only for names set by <code class="regex rouge"><span class="pcre2-semantic">(*MARK:<em>NAME</em>)</span></code>. It ignores | |
| names that are set by other backtracking verbs.</p></dd></div><div class="dlist-item"><dt><span><code class="regex rouge"><span class="pcre2-semantic">(*THEN)</span></code> or <code class="regex rouge"><span class="pcre2-semantic">(*THEN:<em>NAME</em>)</span></code></span></dt><dd><p>This verb causes a skip to the next innermost alternative when backtracking | |
| reaches it. That is, it cancels any further backtracking within the current | |
| alternative. Its name comes from the observation that it can be used for a | |
| pattern-based if-then-else block:</p><div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">( COND1 (*THEN) FOO | | |
| COND2 (*THEN) BAR | | |
| COND3 (*THEN) BAZ ) ...</span></code></pre></div> | |
| <p>If the COND1 pattern matches, FOO is tried (and possibly further items after | |
| the end of the group if FOO succeeds); on failure, the matcher skips to the | |
| second alternative and tries COND2, without backtracking into COND1. If that | |
| succeeds and BAR fails, COND3 is tried. If subsequently BAZ fails, there are no | |
| more alternatives, so there is a backtrack to whatever came before the entire | |
| group. If <code class="regex rouge"><span class="pcre2-semantic">(*THEN)</span></code> is not inside an alternation, it acts like <code class="regex rouge"><span class="pcre2-semantic">(*PRUNE)</span></code>.</p> | |
| <p>The behaviour of <code class="regex rouge"><span class="pcre2-semantic">(*THEN:<em>NAME</em>)</span></code> is not the same as <code class="regex rouge"><span class="pcre2-semantic">(*MARK:<em>NAME</em>)(*THEN)</span></code>. It is | |
| like <code class="regex rouge"><span class="pcre2-semantic">(*MARK:<em>NAME</em>)</span></code> in that the name is remembered for passing back to the | |
| caller. However, <code class="regex rouge"><span class="pcre2-semantic">(*SKIP:<em>NAME</em>)</span></code> searches only for names set with <code class="regex rouge"><span class="pcre2-semantic">(*MARK)</span></code>, | |
| ignoring those set by other backtracking verbs.</p> | |
| <p>A group that does not contain a | character is just a part of the enclosing | |
| alternative; it is not a nested alternation with only one alternative. The | |
| effect of <code class="regex rouge"><span class="pcre2-semantic">(*THEN)</span></code> extends beyond such a group to the enclosing alternative. | |
| Consider this pattern, where A, B, etc. are complex pattern fragments that do | |
| not contain any | characters at this level:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">A (B(*THEN)C) | D</span></code></pre></div> | |
| <p>If A and B are matched, but there is a failure in C, matching does not | |
| backtrack into A; instead it moves to the next alternative, that is, D. | |
| However, if the group containing <code class="regex rouge"><span class="pcre2-semantic">(*THEN)</span></code> is given an alternative, it | |
| behaves differently:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">A (B(*THEN)C | (*FAIL)) | D</span></code></pre></div> | |
| <p>The effect of <code class="regex rouge"><span class="pcre2-semantic">(*THEN)</span></code> is now confined to the inner group. After a failure in C, | |
| matching moves to <code class="regex rouge"><span class="pcre2-semantic">(*FAIL)</span></code>, which causes the whole group to fail because there | |
| are no more alternatives to try. In this case, matching does backtrack into A.</p> | |
| <p>Note that a conditional group is not considered as having two alternatives, | |
| because only one is ever used. In other words, the | character in a conditional | |
| group has a different meaning. Ignoring white space, consider:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">^.*? (?(?=a) a | b(*THEN)c )</span></code></pre></div> | |
| <p>If the subject is <code class="subject rouge"><span class="pcre2-semantic">ba</span></code>, this pattern does not match. Because <code class="regex rouge"><span class="pcre2-semantic">.*?</span></code> is ungreedy, | |
| it initially matches zero characters. The condition <code class="regex rouge"><span class="pcre2-semantic">(?=a)</span></code> then fails, the | |
| character <code class="subject rouge"><span class="pcre2-semantic">b</span></code> is matched, but <code class="subject rouge"><span class="pcre2-semantic">c</span></code> is not. At this point, matching does not | |
| backtrack to <code class="regex rouge"><span class="pcre2-semantic">.*?</span></code> as might perhaps be expected from the presence of the | | |
| character. The conditional group is part of the single alternative that | |
| comprises the whole pattern, and so the match fails. (If there was a backtrack | |
| into <code class="regex rouge"><span class="pcre2-semantic">.*?</span></code>, allowing it to match <code class="subject rouge"><span class="pcre2-semantic">b</span></code>, the match would succeed.)</p></dd></div></dl> | |
| <p>The verbs just described provide four different "strengths" of control when | |
| subsequent matching fails. <code class="regex rouge"><span class="pcre2-semantic">(*THEN)</span></code> is the weakest, carrying on the match at the | |
| next alternative. <code class="regex rouge"><span class="pcre2-semantic">(*PRUNE)</span></code> comes next, failing the match at the current | |
| starting position, but allowing an advance to the next character (for an | |
| unanchored pattern). <code class="regex rouge"><span class="pcre2-semantic">(*SKIP)</span></code> is similar, except that the advance may be more | |
| than one character. <code class="regex rouge"><span class="pcre2-semantic">(*COMMIT)</span></code> is the strongest, causing the entire match to | |
| fail.</p></section> | |
| <section class="doc-section level-2"><h3 id="_more_than_one_backtracking_verb">More than one backtracking verb</h3><p>If more than one backtracking verb is present in a pattern, the one that is | |
| backtracked onto first acts. For example, consider this pattern, where A, B, | |
| etc. are complex pattern fragments:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(A(*COMMIT)B(*THEN)C|ABD)</span></code></pre></div> | |
| <p>If A matches but B fails, the backtrack to <code class="regex rouge"><span class="pcre2-semantic">(*COMMIT)</span></code> causes the entire match to | |
| fail. However, if A and B match, but C fails, the backtrack to <code class="regex rouge"><span class="pcre2-semantic">(*THEN)</span></code> causes | |
| the next alternative (ABD) to be tried. This behaviour is consistent, but is | |
| not always the same as Perl’s. It means that if two or more backtracking verbs | |
| appear in succession, all but the last of them has no effect. Consider this | |
| example:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">...(*COMMIT)(*PRUNE)...</span></code></pre></div> | |
| <p>If there is a matching failure to the right, backtracking onto <code class="regex rouge"><span class="pcre2-semantic">(*PRUNE)</span></code> causes | |
| it to be triggered, and its action is taken. There can never be a backtrack | |
| onto <code class="regex rouge"><span class="pcre2-semantic">(*COMMIT)</span></code>.</p></section> | |
| <section class="doc-section level-2"><h3 id="_backtracking_verbs_in_repeated_groups">Backtracking verbs in repeated groups</h3><p>PCRE2 sometimes differs from Perl in its handling of backtracking verbs in | |
| repeated groups. For example, consider:</p> | |
| <div class="listing-block"><pre class="rouge highlight"><code data-lang="regex"><span class="pcre2-semantic">(a(*COMMIT)b)+ac</span></code></pre></div> | |
| <p>If the subject is <code class="subject rouge"><span class="pcre2-semantic">abac</span></code>, Perl matches unless its optimizations are disabled, | |
| but PCRE2 always fails because the <code class="regex rouge"><span class="pcre2-semantic">(*COMMIT)</span></code> in the second repeat of the group | |
| acts.</p></section> | |
| <section class="doc-section level-2"><h3 id="_backtracking_verbs_in_assertions">Backtracking verbs in assertions</h3><p><code class="regex rouge"><span class="pcre2-semantic">(*FAIL)</span></code> in any assertion has its normal effect: it forces an immediate | |
| backtrack. The behaviour of the other backtracking verbs depends on whether or | |
| not the assertion is standalone or acting as the condition in a conditional | |
| group.</p> | |
| <p><code class="regex rouge"><span class="pcre2-semantic">(*ACCEPT)</span></code> in a standalone positive assertion causes the assertion to succeed | |
| without any further processing; captured strings and a mark name (if set) are | |
| retained. In a standalone negative assertion, <code class="regex rouge"><span class="pcre2-semantic">(*ACCEPT)</span></code> causes the assertion to | |
| fail without any further processing; captured substrings and any mark name are | |
| discarded.</p> | |
| <p>If the assertion is a condition, <code class="regex rouge"><span class="pcre2-semantic">(*ACCEPT)</span></code> causes the condition to be true for | |
| a positive assertion and false for a negative one; captured substrings are | |
| retained in both cases.</p> | |
| <p>The remaining verbs act only when a later failure causes a backtrack to | |
| reach them. This means that, for the Perl-compatible assertions, their effect | |
| is confined to the assertion, because Perl lookaround assertions are atomic. A | |
| backtrack that occurs after such an assertion is complete does not jump back | |
| into the assertion. Note in particular that a <code class="regex rouge"><span class="pcre2-semantic">(*MARK)</span></code> name that is set in an | |
| assertion is not "seen" by an instance of <code class="regex rouge"><span class="pcre2-semantic">(*SKIP:<em>NAME</em>)</span></code> later in the pattern.</p> | |
| <p>PCRE2 now supports non-atomic positive assertions and also "scan substring" | |
| assertions, as described in the sections <a href="#non-atomic-assertions">Non-atomic assertions</a> | |
| and | |
| <a href="#scan-substring-assertions">Scan substring assertions</a> | |
| above. These assertions must be standalone (not used as conditions). They are | |
| not Perl-compatible. For these assertions, a later backtrack does jump back | |
| into the assertion, and therefore verbs such as <code class="regex rouge"><span class="pcre2-semantic">(*COMMIT)</span></code> can be triggered by | |
| backtracks from later in the pattern.</p> | |
| <p>The effect of <code class="regex rouge"><span class="pcre2-semantic">(*THEN)</span></code> is not allowed to escape beyond an assertion. If there | |
| are no more branches to try, <code class="regex rouge"><span class="pcre2-semantic">(*THEN)</span></code> causes a positive assertion to be false, | |
| and a negative assertion to be true. This behaviour differs from Perl when the | |
| assertion has only one branch.</p> | |
| <p>The other backtracking verbs are not treated specially if they appear in a | |
| standalone positive assertion. In a conditional positive assertion, | |
| backtracking (from within the assertion) into <code class="regex rouge"><span class="pcre2-semantic">(*COMMIT)</span></code>, <code class="regex rouge"><span class="pcre2-semantic">(*SKIP)</span></code>, or <code class="regex rouge"><span class="pcre2-semantic">(*PRUNE)</span></code> | |
| causes the condition to be false. However, for both standalone and conditional | |
| negative assertions, backtracking into <code class="regex rouge"><span class="pcre2-semantic">(*COMMIT)</span></code>, <code class="regex rouge"><span class="pcre2-semantic">(*SKIP)</span></code>, or <code class="regex rouge"><span class="pcre2-semantic">(*PRUNE)</span></code> causes | |
| the assertion to be true, without considering any further alternative branches.</p></section> | |
| <section class="doc-section level-2"><h3 id="backtracking-verbs-in-subroutines">Backtracking verbs in subroutines</h3><p>These behaviours occur whether or not the group is called recursively.</p> | |
| <p><code class="regex rouge"><span class="pcre2-semantic">(*ACCEPT)</span></code> in a group called as a subroutine causes the subroutine match to | |
| succeed without any further processing. Matching then continues after the | |
| subroutine call. Perl documents this behaviour. Perl’s treatment of the other | |
| verbs in subroutines is different in some cases.</p> | |
| <p><code class="regex rouge"><span class="pcre2-semantic">(*FAIL)</span></code> in a group called as a subroutine has its normal effect: it forces | |
| an immediate backtrack.</p> | |
| <p><code class="regex rouge"><span class="pcre2-semantic">(*COMMIT)</span></code>, <code class="regex rouge"><span class="pcre2-semantic">(*SKIP)</span></code>, and <code class="regex rouge"><span class="pcre2-semantic">(*PRUNE)</span></code> cause the subroutine match to fail when | |
| triggered by being backtracked to in a group called as a subroutine. There is | |
| then a backtrack at the outer level.</p> | |
| <p><code class="regex rouge"><span class="pcre2-semantic">(*THEN)</span></code>, when triggered, skips to the next alternative in the innermost | |
| enclosing group that has alternatives (its normal behaviour). However, if there | |
| is no such group within the subroutine’s group, the subroutine match fails and | |
| there is a backtrack at the outer level.</p></section></section> | |
| <section class="doc-section level-1"><h2 id="ebcdic-environments">EBCDIC environments</h2><p>Differences in the way PCRE behaves when it is running in an EBCDIC environment | |
| are covered in this section.</p> | |
| <section class="doc-section level-2"><h3 id="_escape_sequences">Escape sequences</h3><p>When PCRE2 is compiled in EBCDIC mode, <code class="regex rouge"><span class="pcre2-semantic">\N{U+<em>hhh...</em>}</span></code> is not supported. <code class="regex rouge"><span class="pcre2-semantic">\a</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\e</span></code>, | |
| <code class="regex rouge"><span class="pcre2-semantic">\f</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\n</span></code>, <code class="regex rouge"><span class="pcre2-semantic">\r</span></code>, and <code class="regex rouge"><span class="pcre2-semantic">\t</span></code> generate the appropriate EBCDIC code values. The <code class="regex rouge"><span class="pcre2-semantic">\c</span></code> | |
| escape is processed as specified for Perl in the <code>perlebcdic</code> document. The | |
| only characters that are allowed after <code class="regex rouge"><span class="pcre2-semantic">\c</span></code> are A–Z, a–z, or one of @, [, \, ], | |
| ^, _, or ?. Any other character provokes a compile-time error. The sequence | |
| <code class="regex rouge"><span class="pcre2-semantic">\c@</span></code> encodes character code 0; after <code class="regex rouge"><span class="pcre2-semantic">\c</span></code> the letters (in either case) encode | |
| characters 1–26 (<span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-74"><code class="character pcre2-api rouge"><span class="sc">0x01</span></code><span class="character-card" id="pcre2-character-74" role="tooltip" aria-label="START OF HEADING (U+0001)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="START OF HEADING"></span><span class="character-codepoint" data-codepoint="U+0001"></span></span></span> to <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-75"><code class="character pcre2-api rouge"><span class="sc">0x1A</span></code><span class="character-card" id="pcre2-character-75" 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>); [, \, ], ^, and _ encode characters 27–31 | |
| (<span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-76"><code class="character pcre2-api rouge"><span class="sc">0x1B</span></code><span class="character-card" id="pcre2-character-76" role="tooltip" aria-label="ESCAPE (U+001B)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="ESCAPE"></span><span class="character-codepoint" data-codepoint="U+001B"></span></span></span> to <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-77"><code class="character pcre2-api rouge"><span class="sc">0x1F</span></code><span class="character-card" id="pcre2-character-77" role="tooltip" aria-label="INFORMATION SEPARATOR ONE (U+001F)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="INFORMATION SEPARATOR ONE"></span><span class="character-codepoint" data-codepoint="U+001F"></span></span></span>), and <code class="regex rouge"><span class="pcre2-semantic">\c?</span></code> becomes either 255 (<span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-78"><code class="character pcre2-api rouge"><span class="sc">0xFF</span></code><span class="character-card" id="pcre2-character-78" 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>) or 95 (<span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-79"><code class="character pcre2-api rouge"><span class="sc">0x5F</span></code><span class="character-card" id="pcre2-character-79" role="tooltip" aria-label="LOW LINE (U+005F)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character="_"></span><span class="character-name" data-character-name="LOW LINE"></span><span class="character-codepoint" data-codepoint="U+005F"></span></span></span>).</p> | |
| <p>Thus, apart from <code class="regex rouge"><span class="pcre2-semantic">\c?</span></code>, these escapes generate the same character code values as | |
| they do in an ASCII or Unicode environment, though the meanings of the values | |
| mostly differ. For example, <code class="regex rouge"><span class="pcre2-semantic">\cG</span></code> always generates code value 7, which is BEL in | |
| ASCII but DEL in EBCDIC.</p> | |
| <p>The sequence <code class="regex rouge"><span class="pcre2-semantic">\c?</span></code> generates DEL (127, <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-80"><code class="character pcre2-api rouge"><span class="sc">0x7F</span></code><span class="character-card" id="pcre2-character-80" role="tooltip" aria-label="DELETE (U+007F)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="DELETE"></span><span class="character-codepoint" data-codepoint="U+007F"></span></span></span>) in an ASCII environment, but | |
| because 127 is not a control character in EBCDIC, Perl makes it generate the | |
| APC character. Unfortunately, there are several variants of EBCDIC. In most of | |
| them the APC character has the value 255 (<span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-81"><code class="character pcre2-api rouge"><span class="sc">0xFF</span></code><span class="character-card" id="pcre2-character-81" 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>), but in the one Perl calls | |
| POSIX-BC its value is 95 (<span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-82"><code class="character pcre2-api rouge"><span class="sc">0x5F</span></code><span class="character-card" id="pcre2-character-82" role="tooltip" aria-label="LOW LINE (U+005F)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character="_"></span><span class="character-name" data-character-name="LOW LINE"></span><span class="character-codepoint" data-codepoint="U+005F"></span></span></span>). If certain other characters have POSIX-BC | |
| values, PCRE2 makes <code class="regex rouge"><span class="pcre2-semantic">\c?</span></code> generate 95; otherwise it generates 255.</p></section> | |
| <section class="doc-section level-2"><h3 id="_character_classes">Character classes</h3><p>In character classes there is a special case in EBCDIC environments for ranges | |
| whose end points are both specified as literal letters in the same case. For | |
| compatibility with Perl, EBCDIC code points within the range that are not | |
| letters are omitted. For example, <code class="regex rouge"><span class="pcre2-semantic">[h-k]</span></code> matches only four characters, even | |
| though the EBCDIC codes for h and k are <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-83"><code class="character pcre2-api rouge"><span class="sc">0x88</span></code><span class="character-card" id="pcre2-character-83" role="tooltip" aria-label="CHARACTER TABULATION SET (U+0088)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="CHARACTER TABULATION SET"></span><span class="character-codepoint" data-codepoint="U+0088"></span></span></span> and <span class="character-info" title="" tabindex="0" aria-describedby="pcre2-character-84"><code class="character pcre2-api rouge"><span class="sc">0x92</span></code><span class="character-card" id="pcre2-character-84" role="tooltip" aria-label="PRIVATE USE TWO (U+0092)" aria-hidden="true" data-pagefind-ignore=""><span class="character-glyph" data-character=""></span><span class="character-name" data-character-name="PRIVATE USE TWO"></span><span class="character-codepoint" data-codepoint="U+0092"></span></span></span>, a range of 11 code | |
| points. However, if the range is specified numerically, for example, | |
| <code class="regex rouge"><span class="pcre2-semantic">[\x88-\x92]</span></code> or <code class="regex rouge"><span class="pcre2-semantic">[h-\x92]</span></code>, all code points are included.</p></section></section> | |
| <section class="doc-section level-1"><h2 id="_see_also">See also</h2><p><a href="./pcre2api.html"><code>pcre2api</code></a>, <a href="./pcre2callout.html"><code>pcre2callout</code></a>, <a href="./pcre2matching.html"><code>pcre2matching</code></a>, | |
| <a href="./pcre2syntax.html"><code>pcre2syntax</code></a>, <a href="./pcre2.html"><code>pcre2</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: 25 October 2025<br> | |
| Copyright © 1997-2024 University of Cambridge.</p></section></article></div></main><footer class="offline-footer"></footer></body></html> |