This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perlop tweak
[perl5.git] / pod / perlop.pod
index 1e6f94e..c36d8ce 100644 (file)
@@ -5,6 +5,22 @@ perlop - Perl operators and precedence
 
 =head1 DESCRIPTION
 
+In Perl, the operator determines what operation is performed,
+independent of the type of the operands. For example C<$a + $b>
+is always a numeric addition, and if C<$a> or C<$b> do not contain
+numbers, an attempt is made to convert them to numbers first.
+
+This is in contrast to many other dynamic languages, where the
+operation is determined by the type of the first argument. It also
+means that Perl has two versions of some operators, one for numeric
+and one for string comparison. For example C<$a == $b> compares
+two numbers for equality, and C<$a eq $b> compares two strings.
+
+There are a few exceptions though: C<x> can be either string
+repetition or list repetition, depending on the type of the left
+operand, and C<&>, C<|> and C<^> can be either string or numeric bit
+operations.
+
 =head2 Operator Precedence and Associativity
 X<operator, precedence> X<precedence> X<associativity>
 
@@ -48,7 +64,7 @@ values only, not array values.
     left       || //
     nonassoc   ..  ...
     right      ?:
-    right      = += -= *= etc.
+    right      = += -= *= etc. goto last next redo dump
     left       , =>
     nonassoc   list operators (rightward)
     right      not
@@ -137,6 +153,10 @@ variable containing either the method name or a subroutine reference,
 and the left side must be either an object (a blessed reference)
 or a class name (that is, a package name).  See L<perlobj>.
 
+The dereferencing cases (as opposed to method-calling cases) are
+somewhat extended by the experimental C<postderef> feature.  For the
+details of that feature, consult L<perlref/Postfix Dereference Syntax>.
+
 =head2 Auto-increment and Auto-decrement
 X<increment> X<auto-increment> X<++> X<decrement> X<auto-decrement> X<-->
 
@@ -302,7 +322,8 @@ operand is not enclosed in parentheses, it returns a string consisting
 of the left operand repeated the number of times specified by the right
 operand.  In list context, if the left operand is enclosed in
 parentheses or is a list formed by C<qw/STRING/>, it repeats the list.
-If the right operand is zero or negative, it returns an empty string
+If the right operand is zero or negative (raising a warning on
+negative), it returns an empty string
 or an empty list, depending on the context.
 X<x>
 
@@ -497,7 +518,9 @@ First available in Perl 5.10.1 (the 5.10.0 version behaved differently),
 binary C<~~> does a "smartmatch" between its arguments.  This is mostly
 used implicitly in the C<when> construct described in L<perlsyn>, although
 not all C<when> clauses call the smartmatch operator.  Unique among all of
-Perl's operators, the smartmatch operator can recurse.
+Perl's operators, the smartmatch operator can recurse.  The smartmatch
+operator is L<experimental|perlpolicy/experimental> and its behavior is
+subject to change.
 
 It is also unique in that all other Perl operators impose a context
 (usually string or numeric context) on their operands, autoconverting
@@ -561,7 +584,7 @@ the table is sorted on the right operand instead of on the left.
                 like: exists HASH->{Any}
 
  Right operand is CODE:
-   
+
  Left      Right      Description and pseudocode                               
  ===============================================================
  ARRAY     CODE       sub returns true on all ARRAY elements[1]
@@ -784,8 +807,10 @@ C<"IO::Handle=GLOB(0x8039e0)">, then pattern matches against that.
 =head2 Bitwise And
 X<operator, bitwise, and> X<bitwise and> X<&>
 
-Binary "&" returns its operands ANDed together bit by bit.
-(See also L<Integer Arithmetic> and L<Bitwise String Operators>.)
+Binary "&" returns its operands ANDed together bit by bit.  Although no
+warning is currently raised, the result is not well defined when this operation
+is performed on operands that aren't either numbers (see
+L<Integer Arithmetic>) or bitstrings (see L<Bitwise String Operators>).
 
 Note that "&" has lower priority than relational operators, so for example
 the parentheses are essential in a test like
@@ -797,10 +822,13 @@ X<operator, bitwise, or> X<bitwise or> X<|> X<operator, bitwise, xor>
 X<bitwise xor> X<^>
 
 Binary "|" returns its operands ORed together bit by bit.
-(See also L<Integer Arithmetic> and L<Bitwise String Operators>.)
 
 Binary "^" returns its operands XORed together bit by bit.
-(See also L<Integer Arithmetic> and L<Bitwise String Operators>.)
+
+Although no warning is currently raised, the results are not well
+defined when these operations are performed on operands that aren't either
+numbers (see L<Integer Arithmetic>) or bitstrings (see L<Bitwise String
+Operators>).
 
 Note that "|" and "^" have lower priority than relational operators, so
 for example the brackets are essential in a test like
@@ -1026,7 +1054,9 @@ you could use this instead:
 
 However, because there are I<many> other lowercase Greek characters than
 just those, to match lowercase Greek characters in a regular expression,
-you would use the pattern C</(?:(?=\p{Greek})\p{Lower})+/>.
+you could use the pattern C</(?:(?=\p{Greek})\p{Lower})+/> (or the
+L<experimental feature|perlrecharclass/Extended Bracketed Character
+Classes> C<S</(?[ \p{Greek} & \p{Lower} ])+/>>).
 
 Because each operand is evaluated in integer form, C<2.18 .. 3.14> will
 return two elements in list context.
@@ -1405,10 +1435,12 @@ table:
    \c[      chr(27)
    \c]      chr(29)
    \c^      chr(30)
-   \c?      chr(127)
+   \c_      chr(31)
+   \c?      chr(127) # (on ASCII platforms)
 
 In other words, it's the character whose code point has had 64 xor'd with
-its uppercase.  C<\c?> is DELETE because C<ord("@") ^ 64> is 127, and
+its uppercase.  C<\c?> is DELETE on ASCII platforms because
+S<C<ord("?") ^ 64>> is 127, and
 C<\c@> is NULL because the ord of "@" is 64, so xor'ing 64 itself produces 0.
 
 Also, C<\c\I<X>> yields C< chr(28) . "I<X>"> for any I<X>, but cannot come at the
@@ -1417,14 +1449,15 @@ quote.
 
 On ASCII platforms, the resulting characters from the list above are the
 complete set of ASCII controls.  This isn't the case on EBCDIC platforms; see
-L<perlebcdic/OPERATOR DIFFERENCES> for the complete list of what these
-sequences mean on both ASCII and EBCDIC platforms.
+L<perlebcdic/OPERATOR DIFFERENCES> for a full discussion of the
+differences between these for ASCII versus EBCDIC platforms.
 
-Use of any other character following the "c" besides those listed above is
-discouraged, and some are deprecated with the intention of removing
-those in a later Perl version.  What happens for any of these
-other characters currently though, is that the value is derived by xor'ing
-with the seventh bit, which is 64.
+Use of any other character following the C<"c"> besides those listed above is
+discouraged, and as of Perl v5.20, the only characters actually allowed
+are the printable ASCII ones, minus the left brace C<"{">.  What happens
+for any of the allowed other characters is that the value is derived by
+xor'ing with the seventh bit, which is 64, and a warning raised if
+enabled.  Using the non-allowed characters generates a fatal error.
 
 To get platform independent controls, you can use C<\N{...}>.
 
@@ -1454,12 +1487,6 @@ the left with zeros to make three digits.  For larger ordinals, either use
 C<\o{}>, or convert to something else, such as to hex and use C<\x{}>
 instead.
 
-Having fewer than 3 digits may lead to a misleading warning message that says
-that what follows is ignored.  For example, C<"\128"> in the ASCII character set
-is equivalent to the two characters C<"\n8">, but the warning C<Illegal octal
-digit '8' ignored> will be thrown.  If C<"\n8"> is what you want, you can
-avoid this warning by padding your octal number with C<0>'s: C<"\0128">.
-
 =item [8]
 
 Several constructs above specify a character by a number.  That number
@@ -1489,7 +1516,9 @@ otherwise to Unicode.
 =back
 
 B<NOTE>: Unlike C and other languages, Perl has no C<\v> escape sequence for
-the vertical tab (VT - ASCII 11), but you may use C<\ck> or C<\x0b>.  (C<\v>
+the vertical tab (VT, which is 11 in both ASCII and EBCDIC), but you may
+use C<\ck> or
+C<\x0b>.  (C<\v>
 does have meaning in regular expression patterns in Perl, see L<perlre>.)
 
 The following escape sequences are available in constructs that interpolate,
@@ -1501,10 +1530,14 @@ X<\l> X<\u> X<\L> X<\U> X<\E> X<\Q> X<\F>
     \L         lowercase all characters till \E or end of string
     \U         uppercase all characters till \E or end of string
     \F         foldcase all characters till \E or end of string
-    \Q         quote non-word characters till \E or end of string
+    \Q          quote (disable) pattern metacharacters till \E or
+                end of string
     \E         end either case modification or quoted section
                (whichever was last seen)
 
+See L<perlfunc/quotemeta> for the exact definition of characters that
+are quoted by C<\Q>.
+
 C<\L>, C<\U>, C<\F>, and C<\Q> can stack, in which case you need one
 C<\E> for each.  For example:
 
@@ -1518,7 +1551,9 @@ If Unicode (for example, C<\N{}> or code points of 0x100 or
 beyond) is being used, the case map used by C<\l>, C<\L>, C<\u>, and
 C<\U> is as defined by Unicode.  That means that case-mapping
 a single character can sometimes produce several characters.
-Under C<use locale>, C<\F> produces the same results as C<\L>.
+Under C<use locale>, C<\F> produces the same results as C<\L>
+for all locales but a UTF-8 one, where it instead uses the Unicode
+definition.
 
 All systems use the virtual C<"\n"> to represent a line terminator,
 called a "newline".  There is no such thing as an unvarying, physical
@@ -1614,7 +1649,8 @@ is equivalent to
 The result may be used as a subpattern in a match:
 
     $re = qr/$pattern/;
-    $string =~ /foo${re}bar/;  # can be interpolated in other patterns
+    $string =~ /foo${re}bar/;  # can be interpolated in other
+                                # patterns
     $string =~ $re;            # or used standalone
     $string =~ /$re/;          # or this way
 
@@ -1647,14 +1683,15 @@ Options (specified by the following modifiers) are:
     i  Do case-insensitive pattern matching.
     x  Use extended regular expressions.
     p  When matching preserve a copy of the matched string so
-        that ${^PREMATCH}, ${^MATCH}, ${^POSTMATCH} will be defined.
+        that ${^PREMATCH}, ${^MATCH}, ${^POSTMATCH} will be
+        defined.
     o  Compile pattern only once.
-    a   ASCII-restrict: Use ASCII for \d, \s, \w; specifying two a's
-        further restricts /i matching so that no ASCII character will
-        match a non-ASCII one
-    l   Use the locale
-    u   Use Unicode rules
-    d   Use Unicode or native charset, as in 5.12 and earlier
+    a   ASCII-restrict: Use ASCII for \d, \s, \w; specifying two
+        a's further restricts /i matching so that no ASCII
+        character will match a non-ASCII one.
+    l   Use the locale.
+    u   Use Unicode rules.
+    d   Use Unicode or native charset, as in 5.12 and earlier.
 
 If a precompiled pattern is embedded in a larger pattern then the effect
 of "msixpluad" will be propagated appropriately.  The effect the "o"
@@ -1662,7 +1699,7 @@ modifier has is not propagated, being restricted to those patterns
 explicitly using it.
 
 The last four modifiers listed above, added in Perl 5.14,
-control the character set semantics, but C</a> is the only one you are likely
+control the character set rules, but C</a> is the only one you are likely
 to want to specify explicitly; the other three are selected
 automatically by various pragmas.
 
@@ -1689,15 +1726,16 @@ Options are as described in C<qr//> above; in addition, the following match
 process modifiers are available:
 
  g  Match globally, i.e., find all occurrences.
- c  Do not reset search position on a failed match when /g is in effect.
+ c  Do not reset search position on a failed match when /g is
+    in effect.
 
 If "/" is the delimiter then the initial C<m> is optional.  With the C<m>
 you can use any pair of non-whitespace (ASCII) characters
 as delimiters.  This is particularly useful for matching path names
 that contain "/", to avoid LTS (leaning toothpick syndrome).  If "?" is
 the delimiter, then a match-only-once rule applies,
-described in C<m?PATTERN?> below.
-If "'" is the delimiter, no interpolation is performed on the PATTERN.
+described in C<m?PATTERN?> below. If "'" (single quote) is the delimiter,
+no interpolation is performed on the PATTERN.
 When using a character valid in an identifier, whitespace is required
 after the C<m>.
 
@@ -1711,7 +1749,7 @@ test and never recompile by adding a C</o> (which stands for "once")
 after the trailing delimiter.
 Once upon a time, Perl would recompile regular expressions
 unnecessarily, and this modifier was useful to tell it not to do so, in the
-interests of speed.  But now, the only reasons to use C</o> are either:
+interests of speed.  But now, the only reasons to use C</o> are one of:
 
 =over
 
@@ -1730,6 +1768,18 @@ you want the pattern to use the initial values of the variables
 regardless of whether they change or not.  (But there are saner ways
 of accomplishing this than using C</o>.)
 
+=item 3
+
+If the pattern contains embedded code, such as
+
+    use re 'eval';
+    $code = 'foo(?{ $x })';
+    /$code/
+
+then perl will recompile each time, even though the pattern string hasn't
+changed, to ensure that the current value of C<$x> is seen each time.
+Use C</o> if you want to avoid this.
+
 =back
 
 The bottom line is that using C</o> is almost never a good idea.
@@ -1756,30 +1806,29 @@ regex with an C<m> (so C<//> becomes C<m//>).
 
 If the C</g> option is not used, C<m//> in list context returns a
 list consisting of the subexpressions matched by the parentheses in the
-pattern, that is, (C<$1>, C<$2>, C<$3>...).  (Note that here C<$1> etc. are
-also set, and that this differs from Perl 4's behavior.)  When there are
-no parentheses in the pattern, the return value is the list C<(1)> for
-success.  With or without parentheses, an empty list is returned upon
-failure.
+pattern, that is, (C<$1>, C<$2>, C<$3>...)  (Note that here C<$1> etc. are
+also set).  When there are no parentheses in the pattern, the return
+value is the list C<(1)> for success.  
+With or without parentheses, an empty list is returned upon failure.
 
 Examples:
 
   open(TTY, "+>/dev/tty")
-       || die "can't access /dev/tty: $!";
open(TTY, "+</dev/tty")
+    || die "can't access /dev/tty: $!";
 
   <TTY> =~ /^y/i && foo();   # do foo if desired
<TTY> =~ /^y/i && foo();      # do foo if desired
 
   if (/Version: *([0-9.]*)/) { $version = $1; }
+ if (/Version: *([0-9.]*)/) { $version = $1; }
 
   next if m#^/usr/spool/uucp#;
+ next if m#^/usr/spool/uucp#;
 
   # poor man's grep
   $arg = shift;
   while (<>) {
-       print if /$arg/o;       # compile only once (no longer needed!)
   }
+ # poor man's grep
+ $arg = shift;
+ while (<>) {
+    print if /$arg/o; # compile only once (no longer needed!)
+ }
 
   if (($F1, $F2, $Etc) = ($foo =~ /^(\S+)\s+(\S+)\s*(.*)/))
+ if (($F1, $F2, $Etc) = ($foo =~ /^(\S+)\s+(\S+)\s*(.*)/))
 
 This last example splits $foo into the first two words and the
 remainder of the line, and assigns those three fields to $F1, $F2, and
@@ -1831,26 +1880,30 @@ Examples:
 
 Here's another way to check for sentences in a paragraph:
 
-    my $sentence_rx = qr{
-       (?: (?<= ^ ) | (?<= \s ) )  # after start-of-string or whitespace
-       \p{Lu}                      # capital letter
-       .*?                         # a bunch of anything
-       (?<= \S )                   # that ends in non-whitespace
-       (?<! \b [DMS]r  )           # but isn't a common abbreviation
-       (?<! \b Mrs )
-       (?<! \b Sra )
-       (?<! \b St  )
-       [.?!]                       # followed by a sentence ender
-       (?= $ | \s )                # in front of end-of-string or whitespace
-    }sx;
-    local $/ = "";
-    while (my $paragraph = <>) {
-       say "NEW PARAGRAPH";
-       my $count = 0;
-       while ($paragraph =~ /($sentence_rx)/g) {
-           printf "\tgot sentence %d: <%s>\n", ++$count, $1;
-       }
+ my $sentence_rx = qr{
+    (?: (?<= ^ ) | (?<= \s ) )  # after start-of-string or
+                                # whitespace
+    \p{Lu}                      # capital letter
+    .*?                         # a bunch of anything
+    (?<= \S )                   # that ends in non-
+                                # whitespace
+    (?<! \b [DMS]r  )           # but isn't a common abbr.
+    (?<! \b Mrs )
+    (?<! \b Sra )
+    (?<! \b St  )
+    [.?!]                       # followed by a sentence
+                                # ender
+    (?= $ | \s )                # in front of end-of-string
+                                # or whitespace
+ }sx;
+ local $/ = "";
+ while (my $paragraph = <>) {
+    say "NEW PARAGRAPH";
+    my $count = 0;
+    while ($paragraph =~ /($sentence_rx)/g) {
+        printf "\tgot sentence %d: <%s>\n", ++$count, $1;
     }
+ }
 
 Here's how to use C<m//gc> with C<\G>:
 
@@ -1887,26 +1940,31 @@ doing different actions depending on which regexp matched.  Each
 regexp tries to match where the previous one leaves off.
 
  $_ = <<'EOL';
-    $url = URI::URL->new( "http://example.com/" ); die if $url eq "xXx";
+    $url = URI::URL->new( "http://example.com/" );
+    die if $url eq "xXx";
  EOL
 
  LOOP: {
      print(" digits"),       redo LOOP if /\G\d+\b[,.;]?\s*/gc;
-     print(" lowercase"),    redo LOOP if /\G\p{Ll}+\b[,.;]?\s*/gc;
-     print(" UPPERCASE"),    redo LOOP if /\G\p{Lu}+\b[,.;]?\s*/gc;
-     print(" Capitalized"),  redo LOOP if /\G\p{Lu}\p{Ll}+\b[,.;]?\s*/gc;
+     print(" lowercase"),    redo LOOP
+                                    if /\G\p{Ll}+\b[,.;]?\s*/gc;
+     print(" UPPERCASE"),    redo LOOP
+                                    if /\G\p{Lu}+\b[,.;]?\s*/gc;
+     print(" Capitalized"),  redo LOOP
+                              if /\G\p{Lu}\p{Ll}+\b[,.;]?\s*/gc;
      print(" MiXeD"),        redo LOOP if /\G\pL+\b[,.;]?\s*/gc;
-     print(" alphanumeric"), redo LOOP if /\G[\p{Alpha}\pN]+\b[,.;]?\s*/gc;
+     print(" alphanumeric"), redo LOOP
+                            if /\G[\p{Alpha}\pN]+\b[,.;]?\s*/gc;
      print(" line-noise"),   redo LOOP if /\G\W+/gc;
      print ". That's all!\n";
  }
 
 Here is the output (split into several lines):
 
   line-noise lowercase line-noise UPPERCASE line-noise UPPERCASE
   line-noise lowercase line-noise lowercase line-noise lowercase
   lowercase line-noise lowercase lowercase line-noise lowercase
   lowercase line-noise MiXeD line-noise. That's all!
+ line-noise lowercase line-noise UPPERCASE line-noise UPPERCASE
+ line-noise lowercase line-noise lowercase line-noise lowercase
+ lowercase line-noise lowercase lowercase line-noise lowercase
+ lowercase line-noise MiXeD line-noise. That's all!
 
 =item m?PATTERN?msixpodualgc
 X<?> X<operator, match-once>
@@ -1974,13 +2032,15 @@ Options are as with m// with the addition of the following replacement
 specific options:
 
     e  Evaluate the right side as an expression.
-    ee  Evaluate the right side as a string then eval the result.
-    r   Return substitution and leave the original string untouched.
+    ee  Evaluate the right side as a string then eval the
+        result.
+    r   Return substitution and leave the original string
+        untouched.
 
 Any non-whitespace delimiter may replace the slashes.  Add space after
 the C<s> when using a character allowed in identifiers.  If single quotes
 are used, no interpretation is done on the replacement string (the C</e>
-modifier overrides this, however).  Unlike Perl 4, Perl 5 treats backticks
+modifier overrides this, however).  Note that Perl treats backticks
 as normal delimiters; the replacement text is not evaluated as a command.
 If the PATTERN is delimited by bracketing quotes, the REPLACEMENT has
 its own pair of quotes, which may or may not be bracketing quotes, for example,
@@ -1992,20 +2052,24 @@ to be C<eval>ed before being run as a Perl expression.
 
 Examples:
 
-    s/\bgreen\b/mauve/g;               # don't change wintergreen
+    s/\bgreen\b/mauve/g;             # don't change wintergreen
 
     $path =~ s|/usr/bin|/usr/local/bin|;
 
     s/Login: $foo/Login: $bar/; # run-time pattern
 
-    ($foo = $bar) =~ s/this/that/;     # copy first, then change
-    ($foo = "$bar") =~ s/this/that/;   # convert to string, copy, then change
+    ($foo = $bar) =~ s/this/that/;     # copy first, then
+                                        # change
+    ($foo = "$bar") =~ s/this/that/;   # convert to string,
+                                        # copy, then change
     $foo = $bar =~ s/this/that/r;      # Same as above using /r
     $foo = $bar =~ s/this/that/r
-                =~ s/that/the other/r; # Chained substitutes using /r
-    @foo = map { s/this/that/r } @bar  # /r is very useful in maps
+                =~ s/that/the other/r; # Chained substitutes
+                                        # using /r
+    @foo = map { s/this/that/r } @bar  # /r is very useful in
+                                        # maps
 
-    $count = ($paragraph =~ s/Mister\b/Mr./g);  # get change-count
+    $count = ($paragraph =~ s/Mister\b/Mr./g);  # get change-cnt
 
     $_ = 'abc123xyz';
     s/\d+/$&*2/e;              # yields 'abc246xyz'
@@ -2042,9 +2106,11 @@ Examples:
        \*/     # Match the closing delimiter.
     } []gsx;
 
-    s/^\s*(.*?)\s*$/$1/;       # trim whitespace in $_, expensively
+    s/^\s*(.*?)\s*$/$1/;       # trim whitespace in $_,
+                                # expensively
 
-    for ($variable) {          # trim whitespace in $variable, cheap
+    for ($variable) {          # trim whitespace in $variable,
+                                # cheap
        s/^\s+//;
        s/\s+$//;
     }
@@ -2064,14 +2130,6 @@ to occur that you might want.  Here are two common cases:
     # expand tabs to 8-column spacing
     1 while s/\t+/' ' x (length($&)*8 - length($`)%8)/e;
 
-C<s///le> is treated as a substitution followed by the C<le> operator, not
-the C</le> flags.  This may change in a future version of Perl.  It
-produces a warning if warnings are enabled.  To disambiguate, use a space
-or change the order of the flags:
-
-    s/foo/bar/ le 5;  # "le" infix operator
-    s/foo/bar/el;     # "e" and "l" flags
-
 =back
 
 =head2 Quote-Like Operators
@@ -2110,7 +2168,7 @@ X<qx> X<`> X<``> X<backtick>
 =item `STRING`
 
 A string which is (possibly) interpolated and then executed as a
-system command with C</bin/sh> or its equivalent.  Shell wildcards,
+system command with F</bin/sh> or its equivalent.  Shell wildcards,
 pipes, and redirections will be honored.  The collected standard
 output of the command is returned; standard error is unaffected.  In
 scalar context, it comes back as a single (potentially multi-line)
@@ -2173,7 +2231,7 @@ multiple commands in a single line by separating them with the command
 separator character, if your shell supports that (for example, C<;> on 
 many Unix shells and C<&> on the Windows NT C<cmd> shell).
 
-Beginning with v5.6.0, Perl will attempt to flush all files opened for
+Perl will attempt to flush all files opened for
 output before starting the child process, but this may not be supported
 on some platforms (see L<perlport>).  To be safe, you may need to set
 C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method of
@@ -2445,24 +2503,24 @@ you'll need to remove leading whitespace from each line manually:
     FINIS
 
 If you use a here-doc within a delimited construct, such as in C<s///eg>,
-the quoted material must come on the lines following the final delimiter.
-So instead of
+the quoted material must still come on the line following the
+C<<< <<FOO >>> marker, which means it may be inside the delimited
+construct:
 
     s/this/<<E . 'that'
     the other
     E
      . 'more '/eg;
 
-you have to write
+It works this way as of Perl 5.18.  Historically, it was inconsistent, and
+you would have to write
 
     s/this/<<E . 'that'
      . 'more '/eg;
     the other
     E
 
-If the terminating identifier is on the last line of the program, you
-must be sure there is a newline after it; otherwise, Perl will give the
-warning B<Can't find string terminator "END" anywhere before EOF...>.
+outside of string evals.
 
 Additionally, quoting rules for the end-of-string identifier are
 unrelated to Perl's quoting rules. C<q()>, C<qq()>, and the like are not
@@ -2530,7 +2588,7 @@ corresponding closing punctuation (that is C<)>, C<]>, C<}>, or C<< > >>).
 If the starting delimiter is an unpaired character like C</> or a closing
 punctuation, the ending delimiter is same as the starting delimiter.
 Therefore a C</> terminates a C<qq//> construct, while a C<]> terminates
-C<qq[]> and C<qq]]> constructs.
+both C<qq[]> and C<qq]]> constructs.
 
 When searching for single-character delimiters, escaped delimiters
 and C<\\> are skipped.  For example, while searching for terminating C</>,
@@ -2540,18 +2598,20 @@ for closing C<]> paired with the opening C<[>, combinations of C<\\>, C<\]>,
 and C<\[> are all skipped, and nested C<[> and C<]> are skipped as well.
 However, when backslashes are used as the delimiters (like C<qq\\> and
 C<tr\\\>), nothing is skipped.
-During the search for the end, backslashes that escape delimiters
-are removed (exactly speaking, they are not copied to the safe location).
+During the search for the end, backslashes that escape delimiters or
+other backslashes are removed (exactly speaking, they are not copied to the
+safe location).
 
 For constructs with three-part delimiters (C<s///>, C<y///>, and
 C<tr///>), the search is repeated once more.
-If the first delimiter is not an opening punctuation, three delimiters must
-be same such as C<s!!!> and C<tr)))>, in which case the second delimiter
+If the first delimiter is not an opening punctuation, the three delimiters must
+be the same, such as C<s!!!> and C<tr)))>,
+in which case the second delimiter
 terminates the left part and starts the right part at once.
 If the left part is delimited by bracketing punctuation (that is C<()>,
 C<[]>, C<{}>, or C<< <> >>), the right part needs another pair of
 delimiters such as C<s(){}> and C<tr[]//>.  In these cases, whitespace
-and comments are allowed between both parts, though the comment must follow
+and comments are allowed between the two parts, though the comment must follow
 at least one whitespace character; otherwise a character expected as the 
 start of the comment may be regarded as the starting delimiter of the right part.
 
@@ -2624,7 +2684,7 @@ expansions.
 
 Let it be stressed that I<whatever falls between C<\Q> and C<\E>>
 is interpolated in the usual way.  Something like C<"\Q\\E"> has
-no C<\E> inside.  instead, it has C<\Q>, C<\\>, and C<E>, so the
+no C<\E> inside.  Instead, it has C<\Q>, C<\\>, and C<E>, so the
 result is the same as for C<"\\\\E">.  As a general rule, backslashes
 between C<\Q> and C<\E> may lead to counterintuitive results.  So,
 C<"\Q\t\E"> is converted to C<quotemeta("\t")>, which is the same
@@ -2692,6 +2752,10 @@ As C<\c> is skipped at this step, C<@> of C<\c@> in RE is possibly
 treated as an array symbol (for example C<@foo>),
 even though the same text in C<qq//> gives interpolation of C<\c@>.
 
+Code blocks such as C<(?{BLOCK})> are handled by temporarily passing control
+back to the perl parser, in a similar way that an interpolated array
+subscript expression such as C<"foo$array[1+f("[xyz")]bar"> would be.
+
 Moreover, inside C<(?{BLOCK})>, C<(?# comment )>, and
 a C<#>-comment in a C<//x>-regular expression, no processing is
 performed whatsoever.  This is the first step at which the presence
@@ -2760,9 +2824,11 @@ rather different than the rule used for the rest of the pattern.
 The terminator of this construct is found using the same rules as
 for finding the terminator of a C<{}>-delimited construct, the only
 exception being that C<]> immediately following C<[> is treated as
-though preceded by a backslash.  Similarly, the terminator of
-C<(?{...})> is found using the same rules as for finding the
-terminator of a C<{}>-delimited construct.
+though preceded by a backslash.
+
+The terminator of runtime C<(?{...})> is found by temporarily switching
+control to the perl parser, which should stop at the point where the
+logically balancing terminating C<}> is found.
 
 It is possible to inspect both the string given to RE engine and the
 resulting finite automaton.  See the arguments C<debug>/C<debugcolor>
@@ -3164,7 +3230,7 @@ need yourself.
 X<number, arbitrary precision>
 
 The standard C<Math::BigInt>, C<Math::BigRat>, and C<Math::BigFloat> modules,
-along with the C<bigint>, C<bigrat>, and C<bitfloat> pragmas, provide
+along with the C<bignum>, C<bigint>, and C<bigrat> pragmas, provide
 variable-precision arithmetic and overloaded operators, although
 they're currently pretty slow. At the cost of some space and
 considerable speed, they avoid the normal pitfalls associated with
@@ -3193,17 +3259,19 @@ provide faster implementations via external C libraries.
 
 Here is a short, but incomplete summary:
 
-  Math::Fraction         big, unlimited fractions like 9973 / 12967
   Math::String           treat string sequences like numbers
   Math::FixedPrecision   calculate with a fixed precision
   Math::Currency         for currency calculations
   Bit::Vector            manipulate bit vectors fast (uses C)
   Math::BigIntFast       Bit::Vector wrapper for big numbers
   Math::Pari             provides access to the Pari C library
-  Math::BigInteger       uses an external C library
-  Math::Cephes           uses external Cephes C library (no big numbers)
+  Math::Cephes           uses the external Cephes C library (no
+                         big numbers)
   Math::Cephes::Fraction fractions via the Cephes library
   Math::GMP              another one using an external C library
+  Math::GMPz             an alternative interface to libgmp's big ints
+  Math::GMPq             an interface to libgmp's fraction numbers
+  Math::GMPf             an interface to libgmp's floating point numbers
 
 Choose wisely.