[perl #82708] Fix unescaped chars in L<>.

[perl5.git] / pod / perlre.pod

diff --git a/pod/perlre.pod b/pod/perlre.pod
index 5ea15a0..1d70b88 100644 (file)
--- a/pod/perlre.pod
+++ b/pod/perlre.pod
@@ -79,7 +79,12 @@ of the g and c modifiers.
 These are usually written as "the C</x> modifier", even though the delimiter
 in question might not really be a slash.  Any of these
 modifiers may also be embedded within the regular expression itself using
 These are usually written as "the C</x> modifier", even though the delimiter
 in question might not really be a slash.  Any of these
 modifiers may also be embedded within the regular expression itself using

-the C<(?...)> construct.  See below.
+the C<(?...)> construct.  Also are new (in 5.14) character set semantics
+modifiers B<C<<"a">>, B<C<"d">>, B<C<"l">> and B<C<"u">>, which, in 5.14
+only, must be used embedded in the regular expression, and not after the
+trailing delimiter.  All this is discussed below in
+L</Extended Patterns>.
+X</a> X</d> X</l> X</u>

 
 The C</x> modifier itself needs a little more explanation.  It tells
 the regular expression parser to ignore most whitespace that is neither
 
 The C</x> modifier itself needs a little more explanation.  It tells
 the regular expression parser to ignore most whitespace that is neither


@@ -229,11 +234,11 @@ also work:
  \f          form feed             (FF)
  \a          alarm (bell)          (BEL)
  \e          escape (think troff)  (ESC)
  \f          form feed             (FF)
  \a          alarm (bell)          (BEL)
  \e          escape (think troff)  (ESC)

- \033        octal char            (example: ESC)

  \cK         control char          (example: VT)
  \x{}, \x00  character whose ordinal is the given hexadecimal number
  \cK         control char          (example: VT)
  \x{}, \x00  character whose ordinal is the given hexadecimal number

- \N{name}    named Unicode character
+ \N{name}    named Unicode character or character sequence

  \N{U+263D}  Unicode character     (example: FIRST QUARTER MOON)
  \N{U+263D}  Unicode character     (example: FIRST QUARTER MOON)

+ \o{}, \000  character whose ordinal is the given octal number

  \l          lowercase next char (think vi)
  \u          uppercase next char (think vi)
  \L          lowercase till \E (think vi)
  \l          lowercase next char (think vi)
  \u          uppercase next char (think vi)
  \L          lowercase till \E (think vi)


@@ -256,7 +261,9 @@ X<\g> X<\k> X<\K> X<backreference>
                    character class "..." within the outer bracketed
                    character class.  Example: [[:upper:]] matches any
                    uppercase character.
                    character class "..." within the outer bracketed
                    character class.  Example: [[:upper:]] matches any
                    uppercase character.

-  \w        [3]  Match a "word" character (alphanumeric plus "_")
+  \w        [3]  Match a "word" character (alphanumeric plus "_", plus
+                   other connector punctuation chars plus Unicode
+                   marks

   \W        [3]  Match a non-"word" character
   \s        [3]  Match a whitespace character
   \S        [3]  Match a non-whitespace character
   \W        [3]  Match a non-"word" character
   \s        [3]  Match a whitespace character
   \S        [3]  Match a non-whitespace character


@@ -316,9 +323,9 @@ See L</Extended Patterns> below for details.
 =item [7]
 
 Note that C<\N> has two meanings.  When of the form C<\N{NAME}>, it matches the
 =item [7]
 
 Note that C<\N> has two meanings.  When of the form C<\N{NAME}>, it matches the

-character whose name is C<NAME>; and similarly when of the form
-C<\N{U+I<wide hex char>}>, it matches the character whose Unicode ordinal is
-I<wide hex char>.  Otherwise it matches any character but C<\n>.
+character or character sequence whose name is C<NAME>; and similarly
+when of the form C<\N{U+I<hex>}>, it matches the character whose Unicode
+code point is I<hex>.  Otherwise it matches any character but C<\n>.

 
 =back
 
 
 =back
 


@@ -363,11 +370,11 @@ not counted when determining the length of the match. Thus the following
 will not match forever:
 X<\G>
 
 will not match forever:
 X<\G>
 

-    $str = 'ABC';
-    pos($str) = 1;
-    while (/.\G/g) {
-        print $&;
-    }
+     my $string = 'ABC';
+     pos($string) = 1;
+     while ($string =~ /(.\G)/g) {
+         print $1;
+     }

 
 It will print 'A' and then terminate, as it considers the match to
 be zero-width, and thus will not match at the same position twice in a
 
 It will print 'A' and then terminate, as it considers the match to
 be zero-width, and thus will not match at the same position twice in a


@@ -450,11 +457,12 @@ capture group, or the character whose ordinal in octal is 010 (a backspace in
 ASCII).  Perl resolves this ambiguity by interpreting C<\10> as a backreference
 only if at least 10 left parentheses have opened before it.  Likewise C<\11> is
 a backreference only if at least 11 left parentheses have opened before it.
 ASCII).  Perl resolves this ambiguity by interpreting C<\10> as a backreference
 only if at least 10 left parentheses have opened before it.  Likewise C<\11> is
 a backreference only if at least 11 left parentheses have opened before it.

-And so on.  C<\1> through C<\9> are always interpreted as backreferences.  You
-can minimize the ambiguity by always using C<\g> if you mean capturing groups;
-and always using 3 digits for octal constants, with the first always "0" (which
-works if there are 63 (= \077) or fewer capture groups).  There are several
-examples below that illustrate these perils.
+And so on.  C<\1> through C<\9> are always interpreted as backreferences.
+There are several examples below that illustrate these perils.  You can avoid
+the ambiguity by always using C<\g{}> or C<\g> if you mean capturing groups;
+and for octal constants always using C<\o{}>, or for C<\077> and below, using 3
+digits padded with leading zeros, since a leading zero implies an octal
+constant.

 
 The C<\I<digit>> notation also works in certain circumstances outside
 the pattern.  See L</Warning on \1 Instead of $1> below for details.)
 
 The C<\I<digit>> notation also works in certain circumstances outside
 the pattern.  See L</Warning on \1 Instead of $1> below for details.)


@@ -593,13 +601,16 @@ whitespace formatting, a simple C<#> will suffice.  Note that Perl closes
 the comment as soon as it sees a C<)>, so there is no way to put a literal
 C<)> in the comment.
 
 the comment as soon as it sees a C<)>, so there is no way to put a literal
 C<)> in the comment.
 

-=item C<(?pimsx-imsx)>
-X<(?)>
+=item C<(?adlupimsx-imsx)>
+
+=item C<(?^alupimsx)>
+X<(?)> X<(?^)>

 
 One or more embedded pattern-match modifiers, to be turned on (or
 turned off, if preceded by C<->) for the remainder of the pattern or
 
 One or more embedded pattern-match modifiers, to be turned on (or
 turned off, if preceded by C<->) for the remainder of the pattern or

-the remainder of the enclosing pattern group (if any). This is
-particularly useful for dynamic patterns, such as those read in from a
+the remainder of the enclosing pattern group (if any).
+
+This is particularly useful for dynamic patterns, such as those read in from a

 configuration file, taken from an argument, or specified in a table
 somewhere.  Consider the case where some patterns want to be case
 sensitive and some do not:  The case insensitive ones merely need to
 configuration file, taken from an argument, or specified in a table
 somewhere.  Consider the case where some patterns want to be case
 sensitive and some do not:  The case insensitive ones merely need to


@@ -625,15 +636,94 @@ These modifiers do not carry over into named subpatterns called in the
 enclosing group. In other words, a pattern such as C<((?i)(&NAME))> does not
 change the case-sensitivity of the "NAME" pattern.
 
 enclosing group. In other words, a pattern such as C<((?i)(&NAME))> does not
 change the case-sensitivity of the "NAME" pattern.
 

-Note that the C<p> modifier is special in that it can only be enabled,
-not disabled, and that its presence anywhere in a pattern has a global
-effect. Thus C<(?-p)> and C<(?-p:...)> are meaningless and will warn
-when executed under C<use warnings>.
+Any of these modifiers can be set to apply globally to all regular
+expressions compiled within the scope of a C<use re>.  See
+L<re/"'/flags' mode">.
+
+Starting in Perl 5.14, a C<"^"> (caret or circumflex accent) immediately
+after the C<"?"> is a shorthand equivalent to C<d-imsx>.  Flags (except
+C<"d">) may follow the caret to override it.
+But a minus sign is not legal with it.
+
+Also, starting in Perl 5.14, are modifiers C<"a">, C<"d">, C<"l">, and
+C<"u">, which for 5.14 may not be used as suffix modifiers.
+
+C<"l"> means to use a locale (see L<perllocale>) when pattern matching.
+The locale used will be the one in effect at the time of execution of
+the pattern match.  This may not be the same as the compilation-time
+locale, and can differ from one match to another if there is an
+intervening call of the
+L<setlocale() function|perllocale/The setlocale function>.
+This modifier is automatically set if the regular expression is compiled
+within the scope of a C<"use locale"> pragma.  Results are not
+well-defined when using this and matching against a utf8-encoded string.
+
+C<"u"> means to use Unicode semantics when pattern matching.  It is
+automatically set if the regular expression is encoded in utf8, or is
+compiled within the scope of a
+L<C<"use feature 'unicode_strings">|feature> pragma (and isn't also in
+the scope of L<C<"use locale">|locale> nor L<C<"use bytes">|bytes>
+pragmas.  On ASCII platforms, the code points between 128 and 255 take on their
+Latin-1 (ISO-8859-1) meanings (which are the same as Unicode's), whereas
+in strict ASCII their meanings are undefined.  Thus the platform
+effectively becomes a Unicode platform.  The ASCII characters remain as
+ASCII characters (since ASCII is a subset of Latin-1 and Unicode).  For
+example, when this option is not on, on a non-utf8 string, C<"\w">
+matches precisely C<[A-Za-z0-9_]>.  When the option is on, it matches
+not just those, but all the Latin-1 word characters (such as an "n" with
+a tilde).  On EBCDIC platforms, which already are equivalent to Latin-1,
+this modifier changes behavior only when the C<"/i"> modifier is also
+specified, and affects only two characters, giving them full Unicode
+semantics: the C<MICRO SIGN> will match the Greek capital and
+small letters C<MU>; otherwise not; and the C<LATIN CAPITAL LETTER SHARP
+S> will match any of C<SS>, C<Ss>, C<sS>, and C<ss>, otherwise not.
+(This last case is buggy, however.)
+
+C<"a"> is the same as C<"u">, except that C<\d>, C<\s>, C<\w>, and the
+Posix character classes are restricted to matching in the ASCII range
+only.  That is, with this modifier, C<\d> always means precisely the
+digits C<"0"> to C<"9">; C<\s> means the five characters C<[ \f\n\r\t]>;
+C<\w> means the 63 characters C<[A-Za-z0-9_]>; and likewise, all the
+Posix classes such as C<[[:print:]]> match only the appropriate
+ASCII-range characters.  As you would expect, this modifier causes, for
+example, C<\D> to mean the same thing as C<[^0-9]>; in fact, all
+non-ASCII characters match C<\D>, C<\S>, and C<\W>.  C<\b> still means
+to match at the boundary between C<\w> and C<\W>, using the C<"a">
+definitions of them (similarly for C<\B>).  Otherwise, C<"a"> behaves
+like the C<"u"> modifier, in that case-insensitive matching uses Unicode
+semantics; for example, "k" will match the Unicode C<\N{KELVIN SIGN}>
+under C</i> matching, and code points in the Latin1 range, above ASCII
+will have Unicode semantics when it comes to case-insensitive matching.
+
+C<"d"> means to use the traditional Perl pattern matching behavior.
+This is dualistic (hence the name C<"d">, which also could stand for
+"depends").  When this is in effect, Perl matches utf8-encoded strings
+using Unicode rules, and matches non-utf8-encoded strings using the
+platform's native character set rules.  (If the regular expression
+itself is encoded in utf8, Unicode rules are used regardless of the
+target string's encoding.)
+See L<perlunicode/The "Unicode Bug">.  It is automatically selected by
+default if the regular expression is compiled neither within the scope
+of a C<"use locale"> pragma nor a <C<"use feature 'unicode_strings">
+pragma.
+
+Note that the C<a>, C<d>, C<l>, C<p>, and C<u> modifiers are special in
+that they can only be enabled, not disabled, and the C<d>, C<l>, and
+C<u> modifiers are mutually exclusive: specifying one de-specifies the
+others, and a maximum of one may appear in the construct.  Thus, for
+example, C<(?-p)>, C<(?-d:...)>, and C<(?dl:...)> will warn when
+compiled under C<use warnings>.
+
+Note also that the C<p> modifier is special in that its presence
+anywhere in a pattern has a global effect.

 
 =item C<(?:pattern)>
 X<(?:)>
 
 
 =item C<(?:pattern)>
 X<(?:)>
 

-=item C<(?imsx-imsx:pattern)>
+=item C<(?adluimsx-imsx:pattern)>
+
+=item C<(?^aluimsx:pattern)>
+X<(?^:)>

 
 This is for clustering, not capturing; it groups subexpressions like
 "()", but doesn't make backreferences as "()" does.  So
 
 This is for clustering, not capturing; it groups subexpressions like
 "()", but doesn't make backreferences as "()" does.  So


@@ -648,7 +738,7 @@ but doesn't spit out extra fields.  It's also cheaper not to capture
 characters if you don't need to.
 
 Any letters between C<?> and C<:> act as flags modifiers as with
 characters if you don't need to.
 
 Any letters between C<?> and C<:> act as flags modifiers as with

-C<(?imsx-imsx)>.  For example,
+C<(?adluimsx-imsx)>.  For example,

 
     /(?s-i:more.*than).*million/i
 
 
     /(?s-i:more.*than).*million/i
 


@@ -656,6 +746,37 @@ is equivalent to the more verbose
 
     /(?:(?s-i)more.*than).*million/i
 
 
     /(?:(?s-i)more.*than).*million/i
 

+Starting in Perl 5.14, a C<"^"> (caret or circumflex accent) immediately
+after the C<"?"> is a shorthand equivalent to C<d-imsx>.  Any positive
+flags (except C<"d">) may follow the caret, so
+
+    (?^x:foo)
+
+is equivalent to
+
+    (?x-ims:foo)
+
+The caret tells Perl that this cluster doesn't inherit the flags of any
+surrounding pattern, but to go back to the system defaults (C<d-imsx>),
+modified by any flags specified.
+
+The caret allows for simpler stringification of compiled regular
+expressions.  These look like
+
+    (?^:pattern)
+
+with any non-default flags appearing between the caret and the colon.
+A test that looks at such stringification thus doesn't need to have the
+system default flags hard-coded in it, just the caret.  If new flags are
+added to Perl, the meaning of the caret's expansion will change to include
+the default for those flags, so the test will still work, unchanged.
+
+Specifying a negative flag after the caret is an error, as the flag is
+redundant.
+
+Mnemonic for C<(?^...)>:  A fresh beginning since the usual use of a caret is
+to match at the beginning.
+

 =item C<(?|pattern)>
 X<(?|)> X<Branch reset>
 
 =item C<(?|pattern)>
 X<(?|)> X<Branch reset>
 


@@ -905,10 +1026,11 @@ B<WARNING>: Use of lexical (C<my>) variables in these blocks is
 broken. The result is unpredictable and will make perl unstable. The
 workaround is to use global (C<our>) variables.
 
 broken. The result is unpredictable and will make perl unstable. The
 workaround is to use global (C<our>) variables.
 

-B<WARNING>: Because Perl's regex engine is currently not re-entrant,
-interpolated code may not invoke the regex engine either directly with
+B<WARNING>: In perl 5.12.x and earlier, the regex engine
+was not re-entrant, so interpolated code could not
+safely invoke the regex engine either directly with

 C<m//> or C<s///>), or indirectly with functions such as
 C<m//> or C<s///>), or indirectly with functions such as

-C<split>. Invoking the regex engine in these blocks will make perl
+C<split>. Invoking the regex engine in these blocks would make perl

 unstable.
 
 =item C<(??{ code })>
 unstable.
 
 =item C<(??{ code })>


@@ -957,9 +1079,9 @@ perilous C<use re 'eval'> pragma has been used (see L<re>), or the
 variables contain results of C<qr//> operator (see
 L<perlop/"qrE<sol>STRINGE<sol>msixpo">).
 
 variables contain results of C<qr//> operator (see
 L<perlop/"qrE<sol>STRINGE<sol>msixpo">).
 

-Because perl's regex engine is not currently re-entrant, delayed
-code may not invoke the regex engine either directly with C<m//> or C<s///>),
-or indirectly with functions such as C<split>.
+In perl 5.12.x and earlier, because the regex engine was not re-entrant,
+delayed code could not safely invoke the regex engine either directly with
+C<m//> or C<s///>), or indirectly with functions such as C<split>.

 
 Recursing deeper than 50 times without consuming any input string will
 result in a fatal error.  The maximum depth is compiled into perl, so
 
 Recursing deeper than 50 times without consuming any input string will
 result in a fatal error.  The maximum depth is compiled into perl, so