From 6520f78d4b878ff66adcf8d25de331d8ad06dd1d Mon Sep 17 00:00:00 2001 From: Rickard Green Date: Fri, 7 Apr 2017 16:49:56 +0200 Subject: Update documentation --- lib/stdlib/doc/src/re.xml | 310 ++++++++++++++++++++++++++++++++-------------- 1 file changed, 217 insertions(+), 93 deletions(-) (limited to 'lib/stdlib/doc') diff --git a/lib/stdlib/doc/src/re.xml b/lib/stdlib/doc/src/re.xml index 7f4f0aa18c..aadb5beaba 100644 --- a/lib/stdlib/doc/src/re.xml +++ b/lib/stdlib/doc/src/re.xml @@ -45,9 +45,10 @@

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.

+ some parts of the library go beyond what PCRE offers. Currently + PCRE version 8.40 (release date 2017-01-11) is used. 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 @@ extended -

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 # outside a character class and the next newline, - inclusive, are also ignored. This is equivalent to Perl option - /x and can be changed within a pattern by a (?x) - option setting.

+

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 (?> that introduce various + parenthesized subpatterns, nor within a numerical quantifier + such as {1,3}. However, ignorable white space is permitted + between an item and a following quantifier and between a + quantifier and a following + that indicates possessiveness. +

+

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 /x option, and it + can be changed within a pattern by a (?x) option setting. +

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 LIMIT_MATCH and LIMIT_RECURSION can only reduce + the value of the limits set by the caller, not increase them.

@@ -1444,12 +1459,17 @@ Pattern PCRE matches Perl matches \nLine feed (hex 0A) \rCarriage return (hex 0D) \tTab (hex 09) + \0ddCharacter with octal code 0dd \dddCharacter with octal code ddd, or back reference + \o{ddd..}character with octal code ddd.. \xhhCharacter with hex code hh \x{hhh..}Character with hex code hhh.. +

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:

- - - 8-bit non-Unicode mode - < 0x100 - 8-bit UTF-8 mode - < 0x10ffff and a valid code point - - -

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.

+ two digits, just those that are present are used. Thus the sequence + \0\x\015 specifies two binary zeros followed by a CR character (code value + 13). Make sure you 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:

\040 @@ -1526,12 +1534,38 @@ Pattern PCRE matches Perl matches \377 Can be a back reference, otherwise value 255 (decimal) \81 - Either a back reference, or a binary zero followed by the two - characters "8" and "1" + Either a back reference, or the two characters "8" and "1" + + +

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:

+ + 8-bit non-UTF mode +

< 0x100

 + 8-bit UTF-8 mode +

< 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 \dAny character that \p{Nd} matches (decimal digit) - \sAny character that \p{Z} matches, plus HT, LF, FF, CR + \sAny character that \p{Z} or \h or \v - \wAny character that \p{L} or \p{N} matches, plus + \wAny character that matches \p{L} or \p{N} matches, plus underscore @@ -1769,6 +1806,7 @@ Pattern PCRE matches Perl matches Avestan Balinese Bamum + Bassa_Vah Batak Bengali Bopomofo @@ -1777,6 +1815,7 @@ Pattern PCRE matches Perl matches Buhid Canadian_Aboriginal Carian + Caucasian_Albanian Chakma Cham Cherokee @@ -1787,11 +1826,14 @@ Pattern PCRE matches Perl matches Cyrillic Deseret Devanagari + Duployan Egyptian_Hieroglyphs + Elbasan Ethiopic Georgian Glagolitic Gothic + Grantha Greek Gujarati Gurmukhi @@ -1811,40 +1853,56 @@ Pattern PCRE matches Perl matches Kayah_Li Kharoshthi Khmer + Khojki + Khudawadi Lao Latin Lepcha Limbu + Linear_A Linear_B Lisu Lycian Lydian + Mahajani Malayalam Mandaic + Manichaean Meetei_Mayek + Mende_Kikakui Meroitic_Cursive Meroitic_Hieroglyphs Miao + Modi Mongolian + Mro Myanmar + Nabataean New_Tai_Lue Nko Ogham + Ol_Chiki Old_Italic + Old_North_Arabian + Old_Permic Old_Persian Oriya Old_South_Arabian Old_Turkic - Ol_Chiki Osmanya + Pahawh_Hmong + Palmyrene + Pau_Cin_Hau Phags_Pa Phoenician + Psalter_Pahlavi Rejang Runic Samaritan Saurashtra Sharada Shavian + Siddham Sinhala Sora_Sompeng Sundanese @@ -1862,8 +1920,10 @@ Pattern PCRE matches Perl matches Thai Tibetan Tifinagh + Tirhuta Ugaritic Vai + Warang_Citi Yi @@ -2001,10 +2061,10 @@ 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 PCRE_UCP is set. However, they can also be used explicitly. - The properties are as follows:

+ when the ucp option is passed. However, they can also be used + explicitly. The properties are as follows:

Xan @@ -2030,6 +2090,16 @@ Pattern PCRE matches Perl matches +

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) Circumflex (only at the start) Opening square bracket (only when it can be interpreted as - introducing a Posix class name; see the next section) + introducing a Posix class name, or for a special compatibility + feature; see the next two sections) Terminating closing square bracket @@ -2385,16 +2464,18 @@ foo\Kbar printPrinting characters, including space punctPrinting characters, excluding letters, digits, and space - spaceWhitespace (not quite the same as \s) + spaceWhitespace (the same as \s from PCRE 8.34) upperUppercase letters word"Word" characters (same as \w) xdigitHexadecimal digits -

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 PCRE_UCP is passed to pcre_compile(), some of the classes are changed so that - Unicode character properties are used. This is achieved by replacing the - Posix classes by other sequences, as follows:

+ Unicode character properties are used. This is achieved by replacing + certain Posix classes by other sequences, as follows:

[:alnum:]Becomes \p{Xan} @@ -2425,9 +2506,49 @@ foo\Kbar [:word:]Becomes \p{Xwd} -

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:

+ + [:graph:] +

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:

+ + U+061C

Arabic Letter Mark

 + U+180E

Mongolian Vowel Separator

 + U+2066 - U+2069

Various "isolate"s

 + + + [:print:] +

This matches the same characters as [:graph:] plus space + characters that are not controls, that is, characters with the Zs + property.

 + [:punct:]

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.

+
@@ -2476,8 +2597,7 @@ gilbert|sullivan

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 Subpatterns) affects only that part of the subpattern that follows it. So, the following matches abc and aBc and @@ -2645,9 +2765,9 @@ the ((?:red|white) (king|queen)) parentheses from other parts of the pattern, such as back references, recursion, and conditions, can be made by name and by number.

-

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 capture specification to run/3 can use named values if they are present in the regular expression.

@@ -3118,7 +3238,14 @@ aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa purposes of numbering the capturing subpatterns in the whole pattern. However, substring capturing is done only for positive assertions. (Perl sometimes, but not always, performs capturing in negative assertions.)

- + +

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 - no_start_optimize, the match starts at "x" and so the (*COMMIT) - causes it to fail without trying any other starting points.

+

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 + no_start_optimize disables the optimization that skips along to the + first character. The pattern is now applied starting at "x", and so the + (*COMMIT) causes the match to fail without trying any other starting + points.

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