From 6520f78d4b878ff66adcf8d25de331d8ad06dd1d Mon Sep 17 00:00:00 2001
From: Rickard Green The matching algorithms of the library are based on the
PCRE library, but not all of the PCRE library is interfaced and
- some parts of the library go beyond what PCRE offers. The sections of
- the PCRE documentation that are relevant to this module are included
- here.
The Erlang literal syntax for strings uses the "\"
@@ -149,13 +150,25 @@
Whitespace data characters in the pattern are ignored except
- when escaped or inside a character class. Whitespace does not
- include character 'vt' (ASCII 11). Characters between an
- unescaped If this option is set, most white space characters in the
+ pattern are totally ignored except when escaped or inside a
+ character class. However, white space is not allowed within
+ sequences such as White space did not used to include the VT character (code
+ 11), because Perl did not treat this character as white space.
+ However, Perl changed at release 5.18, so PCRE followed at
+ release 8.34, and VT is now treated as white space.
+ This also causes characters between an unescaped #
+ outside a character class and the next newline, inclusive, to
+ be ignored. This is equivalent to Perl's With this option, comments inside complicated patterns can be
included. However, notice that this applies only to data
characters. Whitespace characters can never appear within special
@@ -1321,6 +1334,8 @@ re:split("Erlang","[lg]",[{return,list},{parts,4}]).
VM. Notice that the recursion limit does not affect the stack depth of the
VM, as PCRE for Erlang is compiled in such a way that the match function
never does recursion on the C stack. Note that Note that \0dd is always an octal code, and that \8 and \9 are
+ the literal characters "8" and "9". The precise effect of \cx on ASCII characters is as follows: if x is a
lowercase letter, it is converted to upper case. Then bit 6 of the
character (hex 40) is inverted. Thus \cA to \cZ become hex 01 to hex 1A
@@ -1461,50 +1481,38 @@ Pattern PCRE matches Perl matches
The \c facility was designed for use with ASCII characters, but with the
extension to Unicode it is even less useful than it once was. By default, after \x, from zero to two hexadecimal digits are read
- (letters can be in upper or lower case). Any number of hexadecimal digits
- can appear between \x{ and }, but the character code is constrained as
- follows: Invalid Unicode code points are the range 0xd800 to 0xdfff (the so-called
- "surrogate" code points), and 0xffef. If characters other than hexadecimal digits appear between \x{ and },
- or if there is no terminating }, this form of escape is not recognized.
- Instead, the initial \x is interpreted as a basic hexadecimal escape,
- with no following digits, giving a character whose value is zero. Characters whose value is < 256 can be defined by either of the two
- syntaxes for \x. There is no difference in the way they are handled. For
- example, \xdc is the same as \x{dc}. After \0 up to two further octal digits are read. If there are fewer than
- two digits, only those that are present are used. Thus the sequence
- \0\x\07 specifies two binary zeros followed by a BEL character (code value
- 7). Ensure to supply two digits after the initial zero if the pattern
- character that follows is itself an octal digit.
The escape \o must be followed by a sequence of octal digits, enclosed + in braces. An error occurs if this is not the case. This escape is a recent + addition to Perl; it provides way of specifying character code points as + octal numbers greater than 0777, and it also allows octal numbers and back + references to be unambiguously specified.
+ +For greater clarity and unambiguity, it is best to avoid following \ by + a digit greater than zero. Instead, use \o{} or \x{} to specify character + numbers, and \g{} to specify back references. The following paragraphs + describe the old, ambiguous syntax.
The handling of a backslash followed by a digit other than 0 is - complicated. Outside a character class, PCRE reads it and any following - digits as a decimal number. If the number is < 10, or if there have + complicated, and Perl has changed in recent releases, causing PCRE also + to change. Outside a character class, PCRE reads the digit and any following + digits as a decimal number. If the number is < 8, or if there have been at least that many previous capturing left parentheses in the expression, the entire sequence is taken as a back reference. A description of how this works is provided later, following the discussion of parenthesized subpatterns.
-Inside a character class, or if the decimal number is > 9 and there - have not been that many capturing subpatterns, PCRE re-reads up to three - octal digits following the backslash, and uses them to generate a data - character. Any subsequent digits stand for themselves. The value of the - character is constrained in the same way as characters specified in - hexadecimal. For example:
+Inside a character class, or if the decimal number following \ is > + 7 and there have not been that many capturing subpatterns, PCRE handles + \8 and \9 as the literal characters "8" and "9", and otherwise re-reads + up to three octal digits following the backslash, and using them to + generate a data character. Any subsequent digits stand for themselves. + For example:
Notice that octal values >= 100 that are specified using this syntax + must not be introduced by a leading zero, as no more than three octal digits + are ever read.
+ +By default, after \x that is not followed by {, from zero to two + hexadecimal digits are read (letters can be in upper or lower case). Any + number of hexadecimal digits may appear between \x{ and }. If a character + other than a hexadecimal digit appears between \x{ and }, or if there is no + terminating }, an error occurs. +
+ +Characters whose value is less than 256 can be defined by either of the + two syntaxes for \x. There is no difference in the way they are handled. For + example, \xdc is exactly the same as \x{dc}.
+ +Constraints on character values
+ +Characters that are specified using octal or hexadecimal numbers are + limited to certain values, as follows:
+< 0x100
< 0x10ffff and a valid codepoint
Invalid Unicode codepoints are the range 0xd800 to 0xdfff (the + so-called "surrogate" codepoints), and 0xffef.
-Notice that octal values >= 100 must not be introduced by a leading - zero, as no more than three octal digits are ever read.
+Escape sequences in character classes
All the sequences that define a single character value can be used both inside and outside character classes. Also, inside a character class, \b @@ -1597,11 +1631,14 @@ Pattern PCRE matches Perl matches appropriate type. If the current matching point is at the end of the subject string, all fail, as there is no character to match.
-For compatibility with Perl, \s does not match the VT character - (code 11). This makes it different from the Posix "space" class. The \s - characters are HT (9), LF (10), FF (12), CR (13), and space (32). If "use - locale;" is included in a Perl script, \s can match the VT character. In - PCRE, it never does.
+For compatibility with Perl, \s did not used to match the VT character (code + 11), which made it different from the the POSIX "space" class. However, Perl + added VT at release 5.18, and PCRE followed suit at release 8.34. The default + \s characters are now 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 (\xA0) is recognized as white space, and in + others the VT character is not.
A "word" character is an underscore or any character that is a letter or
a digit. By default, the definition of letters and digits is controlled by
@@ -1619,9 +1656,9 @@ Pattern PCRE matches Perl matches
In addition to the standard Unicode properties described earlier, PCRE
supports four more that make it possible to convert traditional escape
- sequences, such as \w and \s, and Posix character classes to use Unicode
+ sequences, such as \w and \s to use Unicode
properties. PCRE uses these non-standard, non-Perl properties internally
- when
Perl and POSIX space are now the same. Perl added VT to its space + character set at release 5.18 and PCRE changed at release 8.34.
+ +Xan matches characters that have either the L (letter) or the N (number) + property. Xps matches the characters tab, linefeed, vertical tab, form feed, + or carriage return, and any other character that has the Z (separator) + property. Xsp is the same as Xps; it used to exclude vertical tab, for Perl + compatibility, but Perl changed, and so PCRE followed at release 8.34. Xwd + matches the same characters as Xan, plus underscore. +
There is another non-standard property, Xuc, 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), @@ -2062,7 +2132,9 @@ foo\Kbar
Perl documents that the use of \K within assertions is "not well defined". In PCRE, \K is acted upon when it occurs inside positive - assertions, but is ignored in negative assertions.
+ assertions, but is ignored in negative assertions. Note that when a + pattern such as (?=ab\K) matches, the reported start of the match can + be greater than the end of the match.Simple Assertions
@@ -2301,7 +2373,8 @@ foo\Kbar 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. + character in the class, or immediately after a range. For example, [b-d-z] + matches letters in the range b to d, a hyphen character, or z.The literal character "]" cannot be the end character of a range. A pattern such as [W-]46] is interpreted as a class of two characters ("W" @@ -2311,6 +2384,11 @@ foo\Kbar followed by two other characters. The octal or hexadecimal representation of "]" can also be used to end a range.
+An error is generated if a POSIX character class (see below) or an + escape sequence other than one that defines a single character appears at + a point where a range ending character is expected. For example, [z-\xff] + is valid, but [A-\d] and [A-[:digit:]] are not.
+Ranges operate in the collating sequence of character values. They can
also be used for characters specified numerically, for example,
[\000-\037]. Ranges can include any characters that are valid for the
@@ -2353,7 +2431,8 @@ foo\Kbar
range)
The "space" characters are HT (9), LF (10), VT (11), FF (12), CR (13), - and space (32). Notice that this list includes the VT character (code 11). - This makes "space" different to \s, which does not include VT (for Perl - compatibility).
+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" used to be different to \s, which did not include VT, for + Perl compatibility. However, Perl changed at release 5.18, and PCRE followed + at release 8.34. "Space" and \s now match the same set of characters.
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 ^ @@ -2408,11 +2489,11 @@ foo\Kbar "ch" is a "collating element", but these are not supported, and an error is given if they are encountered.
-By default, in UTF modes, characters with values > 255 do not match +
By default, characters with values > 255 do not match
any of the Posix character classes. However, if option
Negated versions, such as [:^alpha:], use \P instead of \p. The other - Posix classes are unchanged, and match only characters with code points - < 256.
+Negated versions, such as [:^alpha:], use \P instead of \p. Three other + POSIX classes are handled specially in UCP mode:
+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:
+Arabic Letter Mark
Mongolian Vowel Separator
Various "isolate"s
This matches the same characters as [:graph:] plus space + characters that are not controls, that is, characters with the Zs + property.
This matches all characters that have + the Unicode P (punctuation) property, plus those characters whose code + points are less than 128 that have the S (Symbol) property.
The other POSIX classes are unchanged, and match only characters with + code points less than 128. +
+ +Compatibility Feature for Word Boundaries
+ +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". PCRE treats these items as follows:
+is converted to \b(?=\w)
is converted to \b(?<=\w)
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 \b + 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.
+When one of these option changes occurs at top-level (that is, not inside subpattern parentheses), the change applies to the remainder of the - pattern that follows. If the change is placed right at the start of a - pattern, PCRE extracts it into the global options.
+ pattern that follows.An option change within a subpattern (see section
Names consist of up to 32 alphanumeric characters and underscores. Named - capturing parentheses are still allocated numbers as well as names, - exactly as if the names were not present. +
Names consist of up to 32 alphanumeric characters and underscores, but
+ must start with a non-digit. Named capturing parentheses are still allocated
+ numbers as well as names, exactly as if the names were not present.
The
If a positive assertion containing one or more capturing subpatterns + succeeds, but failure to match later in the pattern causes backtracking over + this assertion, the captures within the assertion are reset only if no higher + numbered captures are already set. This is, unfortunately, a fundamental + limitation of the current implementation, and as PCRE1 is now in + maintenance-only status, it is unlikely ever to change.
+For compatibility with Perl, assertion subpatterns can be repeated. However, it makes no sense to assert the same thing many times, the side effect of capturing parentheses can occasionally be useful. In practice, @@ -3371,12 +3498,7 @@ abcd$
Perl uses the syntax (?(<name>)...) or (?('name')...) to test for a used subpattern by name. For compatibility with earlier versions of PCRE, which had this facility before Perl, the syntax (?(name)...) is also - recognized. However, there is a possible ambiguity with this syntax, as - subpattern names can consist entirely of digits. PCRE looks first for a - named subpattern; if it cannot find one and the name consists entirely of - digits, PCRE looks for a subpattern of that number, which must be > 0. - Using subpattern names that consist entirely of digits is not - recommended.
+ recognized.Rewriting the previous example to use a named subpattern gives:
@@ -3958,11 +4080,13 @@ a+(*COMMIT)b 2> re:run("xyzabc","(*COMMIT)abc",[{capture,all,list},no_start_optimize]). nomatch -PCRE knows that any match must start with "a", so the optimization skips
- along the subject to "a" before running the first match attempt, which
- succeeds. When the optimization is disabled by option
-
For this pattern, PCRE knows that any match must start with "a", so the
+ optimization skips along the subject to "a" before applying the pattern to the
+ first set of data. The match attempt then succeeds. In the second call the
+
The following verb causes the match to fail at the current starting position in the subject if there is a later matching failure that causes @@ -4138,7 +4262,7 @@ A (B(*THEN)C | (*FAIL)) | D ...(*COMMIT)(*PRUNE)...
If there is a matching failure to the right, backtracking onto (*PRUNE) - cases it to be triggered, and its action is taken. There can never be a + causes it to be triggered, and its action is taken. There can never be a backtrack onto (*COMMIT).
Backtracking Verbs in Repeated Groups
-- cgit v1.2.3