PerlIO::Via: check arg is non-NULL before using it.

[perl5.git] / pod / perlvar.pod

diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index 4b6bb74..6c54f76 100644 (file)
--- a/pod/perlvar.pod
+++ b/pod/perlvar.pod
@@ -12,30 +12,30 @@ arbitrarily long (up to an internal limit of 251 characters) and
 may contain letters, digits, underscores, or the special sequence
 C<::> or C<'>.  In this case, the part before the last C<::> or
 C<'> is taken to be a I<package qualifier>; see L<perlmod>.
 may contain letters, digits, underscores, or the special sequence
 C<::> or C<'>.  In this case, the part before the last C<::> or
 C<'> is taken to be a I<package qualifier>; see L<perlmod>.

-
-Perl variable names may also be a sequence of digits or a single
-punctuation or control character.  These names are all reserved for
+A Unicode letter that is not ASCII is not considered to be a letter
+unless S<C<"use utf8">> is in effect, and somewhat more complicated
+rules apply; see L<perldata/Identifier parsing> for details.
+
+Perl variable names may also be a sequence of digits, a single
+punctuation character, or the two-character sequence: C<^> (caret or
+CIRCUMFLEX ACCENT) followed by any one of the characters C<[][A-Z^_?\]>.
+These names are all reserved for

 special uses by Perl; for example, the all-digits names are used
 to hold data captured by backreferences after a regular expression
 special uses by Perl; for example, the all-digits names are used
 to hold data captured by backreferences after a regular expression

-match.  Perl has a special syntax for the single-control-character
-names: It understands C<^X> (caret C<X>) to mean the control-C<X>
-character.  For example, the notation C<$^W> (dollar-sign caret
-C<W>) is the scalar variable whose name is the single character
-control-C<W>.  This is better than typing a literal control-C<W>
-into your program.
-
-Since Perl v5.6.0, Perl variable names may be alphanumeric
-strings that begin with control characters (or better yet, a caret).
-These variables must be written in the form C<${^Foo}>; the braces
-are not optional.  C<${^Foo}> denotes the scalar variable whose
-name is a control-C<F> followed by two C<o>'s.  These variables are
+match.
+
+Since Perl v5.6.0, Perl variable names may also be alphanumeric strings
+preceded by a caret.  These must all be written in the form C<${^Foo}>;
+the braces are not optional.  C<${^Foo}> denotes the scalar variable
+whose name is considered to be a control-C<F> followed by two C<o>'s.
+These variables are

 reserved for future special uses by Perl, except for the ones that
 reserved for future special uses by Perl, except for the ones that

-begin with C<^_> (control-underscore or caret-underscore).  No
-control-character name that begins with C<^_> will acquire a special
+begin with C<^_> (caret-underscore).  No
+name that begins with C<^_> will acquire a special

 meaning in any future version of Perl; such names may therefore be
 used safely in programs.  C<$^_> itself, however, I<is> reserved.
 
 meaning in any future version of Perl; such names may therefore be
 used safely in programs.  C<$^_> itself, however, I<is> reserved.
 

-Perl identifiers that begin with digits, control characters, or
+Perl identifiers that begin with digits or

 punctuation characters are exempt from the effects of the C<package>
 declaration and are always forced to be in package C<main>; they are
 also exempt from C<strict 'vars'> errors.  A few other names are also
 punctuation characters are exempt from the effects of the C<package>
 declaration and are always forced to be in package C<main>; they are
 also exempt from C<strict 'vars'> errors.  A few other names are also


@@ -142,19 +142,12 @@ test.  Outside a C<while> test, this will not happen.
 
 =back
 
 
 =back
 

-C<$_> is by default a global variable.  However, as
-of perl v5.10.0, you can use a lexical version of
-C<$_> by declaring it in a file or in a block with C<my>.  Moreover,
-declaring C<our $_> restores the global C<$_> in the current scope.  Though
-this seemed like a good idea at the time it was introduced, lexical C<$_>
-actually causes more problems than it solves.  If you call a function that
-expects to be passed information via C<$_>, it may or may not work,
-depending on how the function is written, there not being any easy way to
-solve this.  Just avoid lexical C<$_>, unless you are feeling particularly
-masochistic.  For this reason lexical C<$_> is still experimental and will
-produce a warning unless warnings have been disabled.  As with other
-experimental features, the behavior of lexical C<$_> is subject to change
-without notice, including change into a fatal error.
+C<$_> is a global variable.
+
+However, between perl v5.10.0 and v5.24.0, it could be used lexically by
+writing C<my $_>.  Making C<$_> refer to the global C<$_> in the same scope
+was then possible with C<our $_>.  This experimental feature was removed and is
+now a fatal error, but you may encounter it in older code.

 
 Mnemonic: underline is understood in certain operations.
 
 
 Mnemonic: underline is understood in certain operations.
 


@@ -165,7 +158,7 @@ X<@_> X<@ARG>
 
 Within a subroutine the array C<@_> contains the parameters passed to
 that subroutine.  Inside a subroutine, C<@_> is the default array for
 
 Within a subroutine the array C<@_> contains the parameters passed to
 that subroutine.  Inside a subroutine, C<@_> is the default array for

-the array operators C<push>, C<pop>, C<shift>, and C<unshift>.
+the array operators C<pop> and C<shift>.

 
 See L<perlsub>.
 
 
 See L<perlsub>.
 


@@ -370,19 +363,19 @@ X<$;> X<$SUBSEP> X<SUBSCRIPT_SEPARATOR>
 The subscript separator for multidimensional array emulation.  If you
 refer to a hash element as
 
 The subscript separator for multidimensional array emulation.  If you
 refer to a hash element as
 

-    $foo{$a,$b,$c}
+    $foo{$x,$y,$z}

 
 it really means
 
 
 it really means
 

-    $foo{join($;, $a, $b, $c)}
+    $foo{join($;, $x, $y, $z)}

 
 But don't put
 
 
 But don't put
 

-    @foo{$a,$b,$c}     # a slice--note the @
+    @foo{$x,$y,$z}     # a slice--note the @

 
 which means
 
 
 which means
 

-    ($foo{$a},$foo{$b},$foo{$c})
+    ($foo{$x},$foo{$y},$foo{$z})

 
 Default is "\034", the same as SUBSEP in B<awk>.  If your keys contain
 binary data there might not be any safe value for C<$;>.
 
 Default is "\034", the same as SUBSEP in B<awk>.  If your keys contain
 binary data there might not be any safe value for C<$;>.


@@ -432,6 +425,45 @@ Previously, only child processes received stringified values:
 This happens because you can't really share arbitrary data structures with
 foreign processes.
 
 This happens because you can't really share arbitrary data structures with
 foreign processes.
 

+=item $OLD_PERL_VERSION
+
+=item $]
+X<$]> X<$OLD_PERL_VERSION>
+
+The revision, version, and subversion of the Perl interpreter, represented
+as a decimal of the form 5.XXXYYY, where XXX is the version / 1e3 and YYY
+is the subversion / 1e6.  For example, Perl v5.10.1 would be "5.010001".
+
+This variable can be used to determine whether the Perl interpreter
+executing a script is in the right range of versions:
+
+    warn "No PerlIO!\n" if $] lt '5.008';
+
+When comparing C<$]>, string comparison operators are B<highly
+recommended>.  The inherent limitations of binary floating point
+representation can sometimes lead to incorrect comparisons for some
+numbers on some architectures.
+
+See also the documentation of C<use VERSION> and C<require VERSION>
+for a convenient way to fail if the running Perl interpreter is too old.
+
+See L</$^V> for a representation of the Perl version as a L<version>
+object, which allows more flexible string comparisons.
+
+The main advantage of C<$]> over C<$^V> is that it works the same on any
+version of Perl.  The disadvantages are that it can't easily be compared
+to versions in other formats (e.g. literal v-strings, "v1.2.3" or
+version objects) and numeric comparisons can occasionally fail; it's good
+for string literal version checks and bad for comparing to a variable
+that hasn't been sanity-checked.
+
+The C<$OLD_PERL_VERSION> form was added in Perl v5.20.0 for historical
+reasons but its use is discouraged. (If your reason to use C<$]> is to
+run code on old perls then referring to it as C<$OLD_PERL_VERSION> would
+be self-defeating.)
+
+Mnemonic: Is this version of perl in the right bracket?
+

 =item $SYSTEM_FD_MAX
 
 =item $^F
 =item $SYSTEM_FD_MAX
 
 =item $^F


@@ -462,11 +494,13 @@ The array C<@INC> contains the list of places that the C<do EXPR>,
 C<require>, or C<use> constructs look for their library files.  It
 initially consists of the arguments to any B<-I> command-line
 switches, followed by the default Perl library, probably
 C<require>, or C<use> constructs look for their library files.  It
 initially consists of the arguments to any B<-I> command-line
 switches, followed by the default Perl library, probably

-F</usr/local/lib/perl>, followed by ".", to represent the current
-directory.  ("." will not be appended if taint checks are enabled,
-either by C<-T> or by C<-t>.)  If you need to modify this at runtime,
-you should use the C<use lib> pragma to get the machine-dependent
-library properly loaded also:
+F</usr/local/lib/perl>.
+Prior to Perl 5.26, C<.> -which represents the current directory, was included
+in C<@INC>; it has been removed. This change in behavior is documented
+in L<C<PERL_USE_UNSAFE_INC>|perlrun/PERL_USE_UNSAFE_INC> and it is
+not recommended that C<.> be re-added to C<@INC>.
+If you need to modify C<@INC> at runtime, you should use the C<use lib> pragma
+to get the machine-dependent library properly loaded as well:

 
     use lib '/mypath/libdir/';
     use SomeMod;
 
     use lib '/mypath/libdir/';
     use SomeMod;


@@ -501,6 +535,19 @@ inplace editing.
 
 Mnemonic: value of B<-i> switch.
 
 
 Mnemonic: value of B<-i> switch.
 

+=item @ISA
+X<@ISA>
+
+Each package contains a special array called C<@ISA> which contains a list
+of that class's parent classes, if any. This array is simply a list of
+scalars, each of which is a string that corresponds to a package name. The
+array is examined when Perl does method resolution, which is covered in
+L<perlobj>.
+
+To load packages while adding them to C<@ISA>, see the L<parent> pragma. The
+discouraged L<base> pragma does this as well, but should not be used except
+when compatibility with the discouraged L<fields> pragma is required.
+

 =item $^M
 X<$^M>
 
 =item $^M
 X<$^M>
 


@@ -607,13 +654,12 @@ or a C<die()>.  The C<__DIE__> handler is explicitly disabled during
 the call, so that you can die from a C<__DIE__> handler.  Similarly
 for C<__WARN__>.
 
 the call, so that you can die from a C<__DIE__> handler.  Similarly
 for C<__WARN__>.
 

-Due to an implementation glitch, the C<$SIG{__DIE__}> hook is called
-even inside an C<eval()>.  Do not use this to rewrite a pending
-exception in C<$@>, or as a bizarre substitute for overriding
-C<CORE::GLOBAL::die()>.  This strange action at a distance may be fixed
-in a future release so that C<$SIG{__DIE__}> is only called if your
-program is about to exit, as was the original intent.  Any other use is
-deprecated.
+The C<$SIG{__DIE__}> hook is called even inside an C<eval()>. It was
+never intended to happen this way, but an implementation glitch made
+this possible. This used to be deprecated, as it allowed strange action
+at a distance like rewriting a pending exception in C<$@>. Plans to
+rectify this have been scrapped, as users found that rewriting a 
+pending exception is actually a useful feature, and not a bug.

 
 C<__DIE__>/C<__WARN__> handlers are very special in one respect: they
 may be called to report (probable) errors found by the parser.  In such
 
 C<__DIE__>/C<__WARN__> handlers are very special in one respect: they
 may be called to report (probable) errors found by the parser.  In such


@@ -656,30 +702,36 @@ and B<-C> filetests are based on this value.
 X<$^V> X<$PERL_VERSION>
 
 The revision, version, and subversion of the Perl interpreter,
 X<$^V> X<$PERL_VERSION>
 
 The revision, version, and subversion of the Perl interpreter,

-represented as a C<version> object.
+represented as a L<version> object.

 
 This variable first appeared in perl v5.6.0; earlier versions of perl
 will see an undefined value.  Before perl v5.10.0 C<$^V> was represented
 
 This variable first appeared in perl v5.6.0; earlier versions of perl
 will see an undefined value.  Before perl v5.10.0 C<$^V> was represented

-as a v-string.
+as a v-string rather than a L<version> object.

 
 C<$^V> can be used to determine whether the Perl interpreter executing
 a script is in the right range of versions.  For example:
 
     warn "Hashes not randomized!\n" if !$^V or $^V lt v5.8.1
 
 
 C<$^V> can be used to determine whether the Perl interpreter executing
 a script is in the right range of versions.  For example:
 
     warn "Hashes not randomized!\n" if !$^V or $^V lt v5.8.1
 

-To convert C<$^V> into its string representation use C<sprintf()>'s
-C<"%vd"> conversion:
+While version objects overload stringification, to portably convert
+C<$^V> into its string representation, use C<sprintf()>'s C<"%vd">
+conversion, which works for both v-strings or version objects:

 
     printf "version is v%vd\n", $^V;  # Perl's version
 
 See the documentation of C<use VERSION> and C<require VERSION>
 for a convenient way to fail if the running Perl interpreter is too old.
 
 
     printf "version is v%vd\n", $^V;  # Perl's version
 
 See the documentation of C<use VERSION> and C<require VERSION>
 for a convenient way to fail if the running Perl interpreter is too old.
 

-See also C<$]> for an older representation of the Perl version.
+See also C<L</$]>> for a decimal representation of the Perl version.

 
 

-This variable was added in Perl v5.6.0.
+The main advantage of C<$^V> over C<$]> is that, for Perl v5.10.0 or
+later, it overloads operators, allowing easy comparison against other
+version representations (e.g. decimal, literal v-string, "v1.2.3", or
+objects).  The disadvantage is that prior to v5.10.0, it was only a
+literal v-string, which can't be easily printed or compared, whereas
+the behavior of C<$]> is unchanged on all versions of Perl.

 
 

-Mnemonic: use ^V for Version Control.
+Mnemonic: use ^V for a version object.

 
 =item ${^WIN32_SLOPPY_STAT}
 X<${^WIN32_SLOPPY_STAT}> X<sitecustomize> X<sitecustomize.pl>
 
 =item ${^WIN32_SLOPPY_STAT}
 X<${^WIN32_SLOPPY_STAT}> X<sitecustomize> X<sitecustomize.pl>


@@ -816,9 +868,9 @@ this:
 
     $str =~ /pattern/;
 
 
     $str =~ /pattern/;
 

-    print $`, $&, $'; # bad: perfomance hit
+    print $`, $&, $'; # bad: performance hit

 
 

-    print             # good: no perfomance hit
+    print             # good: no performance hit

        substr($str, 0,     $-[0]),
        substr($str, $-[0], $+[0]-$-[0]),
        substr($str, $+[0]);
        substr($str, 0,     $-[0]),
        substr($str, $-[0], $+[0]-$-[0]),
        substr($str, $+[0]);


@@ -850,16 +902,44 @@ find uses of these problematic match variables in your code.
 =over 8
 
 =item $<I<digits>> ($1, $2, ...)
 =over 8
 
 =item $<I<digits>> ($1, $2, ...)

-X<$1> X<$2> X<$3>
+X<$1> X<$2> X<$3> X<$I<digits>>

 
 Contains the subpattern from the corresponding set of capturing
 parentheses from the last successful pattern match, not counting patterns
 matched in nested blocks that have been exited already.
 
 
 Contains the subpattern from the corresponding set of capturing
 parentheses from the last successful pattern match, not counting patterns
 matched in nested blocks that have been exited already.
 

+Note there is a distinction between a capture buffer which matches
+the empty string a capture buffer which is optional. Eg, C<(x?)> and
+C<(x)?> The latter may be undef, the former not.
+

 These variables are read-only and dynamically-scoped.
 
 Mnemonic: like \digits.
 
 These variables are read-only and dynamically-scoped.
 
 Mnemonic: like \digits.
 

+=item @{^CAPTURE}
+X<@{^CAPTURE}> X<@^CAPTURE>
+
+An array which exposes the contents of the capture buffers, if any, of
+the last successful pattern match, not counting patterns matched
+in nested blocks that have been exited already.
+
+Note that the 0 index of @{^CAPTURE} is equivalent to $1, the 1 index
+is equivalent to $2, etc.
+
+    if ("foal"=~/(.)(.)(.)(.)/) {
+        print join "-", @{^CAPTURE};
+    }
+
+should output "f-o-a-l".
+
+See also L<<< /$<I<digits>> ($1, $2, ...) >>>, L</%{^CAPTURE}> and
+L</%{^CAPTURE_ALL}>.
+
+Note that unlike most other regex magic variables there is no single
+letter equivalent to C<@{^CAPTURE}>.
+
+This variable was added in 5.25.7
+

 =item $MATCH
 
 =item $&
 =item $MATCH
 
 =item $&


@@ -968,7 +1048,10 @@ This variable is read-only and dynamically-scoped.
 =item $+
 X<$+> X<$LAST_PAREN_MATCH>
 
 =item $+
 X<$+> X<$LAST_PAREN_MATCH>
 

-The text matched by the last bracket of the last successful search pattern.
+The text matched by the highest used capture group of the last
+successful search pattern.  It is logically equivalent to the highest
+numbered capture variable (C<$1>, C<$2>, ...) which has a defined value.
+

 This is useful if you don't know which one of a set of alternative patterns
 matched.  For example:
 
 This is useful if you don't know which one of a set of alternative patterns
 matched.  For example:
 


@@ -985,7 +1068,15 @@ X<$^N> X<$LAST_SUBMATCH_RESULT>
 
 The text matched by the used group most-recently closed (i.e. the group
 with the rightmost closing parenthesis) of the last successful search
 
 The text matched by the used group most-recently closed (i.e. the group
 with the rightmost closing parenthesis) of the last successful search

-pattern.
+pattern. This is subtly different from C<$+>. For example in
+
+    "ab" =~ /^((.)(.))$/
+
+we have
+
+    $1,$^N   have the value "ab"
+    $2       has  the value "a"
+    $3,$+    have the value "b"

 
 This is primarily used inside C<(?{...})> blocks for examining text
 recently matched.  For example, to effectively capture text to a variable
 
 This is primarily used inside C<(?{...})> blocks for examining text
 recently matched.  For example, to effectively capture text to a variable


@@ -1018,10 +1109,12 @@ examples given for the C<@-> variable.
 
 This variable was added in Perl v5.6.0.
 
 
 This variable was added in Perl v5.6.0.
 

+=item %{^CAPTURE}
+

 =item %LAST_PAREN_MATCH
 
 =item %+
 =item %LAST_PAREN_MATCH
 
 =item %+

-X<%+> X<%LAST_PAREN_MATCH>
+X<%+> X<%LAST_PAREN_MATCH> X<%{^CAPTURE}>

 
 Similar to C<@+>, the C<%+> hash allows access to the named capture
 buffers, should they exist, in the last successful match in the
 
 Similar to C<@+>, the C<%+> hash allows access to the named capture
 buffers, should they exist, in the last successful match in the


@@ -1034,6 +1127,9 @@ For example, C<$+{foo}> is equivalent to C<$1> after the following match:
 The keys of the C<%+> hash list only the names of buffers that have
 captured (and that are thus associated to defined values).
 
 The keys of the C<%+> hash list only the names of buffers that have
 captured (and that are thus associated to defined values).
 

+If multiple distinct capture groups have the same name, then
+C<$+{NAME}> will refer to the leftmost defined group in the match.
+

 The underlying behaviour of C<%+> is provided by the
 L<Tie::Hash::NamedCapture> module.
 
 The underlying behaviour of C<%+> is provided by the
 L<Tie::Hash::NamedCapture> module.
 


@@ -1043,7 +1139,8 @@ iterative access to them via C<each> may have unpredictable results.
 Likewise, if the last successful match changes, then the results may be
 surprising.
 
 Likewise, if the last successful match changes, then the results may be
 surprising.
 

-This variable was added in Perl v5.10.0.
+This variable was added in Perl v5.10.0. The C<%{^CAPTURE}> alias was
+added in 5.25.7.

 
 This variable is read-only and dynamically-scoped.
 
 
 This variable is read-only and dynamically-scoped.
 


@@ -1053,7 +1150,7 @@ This variable is read-only and dynamically-scoped.
 X<@-> X<@LAST_MATCH_START>
 
 C<$-[0]> is the offset of the start of the last successful match.
 X<@-> X<@LAST_MATCH_START>
 
 C<$-[0]> is the offset of the start of the last successful match.

-C<$-[>I<n>C<]> is the offset of the start of the substring matched by
+C<$-[I<n>]> is the offset of the start of the substring matched by

 I<n>-th subpattern, or undef if the subpattern did not match.
 
 Thus, after a match against C<$_>, C<$&> coincides with C<substr $_, $-[0],
 I<n>-th subpattern, or undef if the subpattern did not match.
 
 Thus, after a match against C<$_>, C<$&> coincides with C<substr $_, $-[0],


@@ -1091,10 +1188,11 @@ After a match against some variable C<$var>:
 
 This variable was added in Perl v5.6.0.
 
 
 This variable was added in Perl v5.6.0.
 

-=item %LAST_MATCH_START
+=item %{^CAPTURE_ALL}
+X<%{^CAPTURE_ALL}>

 
 =item %-
 
 =item %-

-X<%-> X<%LAST_MATCH_START>
+X<%->

 
 Similar to C<%+>, this variable allows access to the named capture groups
 in the last successful match in the currently active dynamic scope.  To
 
 Similar to C<%+>, this variable allows access to the named capture groups
 in the last successful match in the currently active dynamic scope.  To


@@ -1137,7 +1235,8 @@ iterative access to them via C<each> may have unpredictable results.
 Likewise, if the last successful match changes, then the results may be
 surprising.
 
 Likewise, if the last successful match changes, then the results may be
 surprising.
 

-This variable was added in Perl v5.10.0.
+This variable was added in Perl v5.10.0. The C<%{^CAPTURE_ALL}> alias was
+added in 5.25.7.

 
 This variable is read-only and dynamically-scoped.
 
 
 This variable is read-only and dynamically-scoped.
 


@@ -1151,6 +1250,17 @@ regular expression assertion (see L<perlre>).  May be written to.
 
 This variable was added in Perl 5.005.
 
 
 This variable was added in Perl 5.005.
 

+=item ${^RE_COMPILE_RECURSION_LIMIT}
+X<${^RE_COMPILE_RECURSION_LIMIT}>
+
+The current value giving the maximum number of open but unclosed
+parenthetical groups there may be at any point during a regular
+expression compilation.  The default is currently 1000 nested groups.
+You may adjust it depending on your needs and the amount of memory
+available.
+
+This variable was added in Perl v5.30.0.
+

 =item ${^RE_DEBUG_FLAGS}
 X<${^RE_DEBUG_FLAGS}>
 
 =item ${^RE_DEBUG_FLAGS}
 X<${^RE_DEBUG_FLAGS}>
 


@@ -1390,6 +1500,44 @@ the next paragraph, even if it's a newline.
 Remember: the value of C<$/> is a string, not a regex.  B<awk> has to
 be better for something. :-)
 
 Remember: the value of C<$/> is a string, not a regex.  B<awk> has to
 be better for something. :-)
 

+Setting C<$/> to an empty string -- the so-called I<paragraph mode> -- merits
+special attention.  When C<$/> is set to C<""> and the entire file is read in
+with that setting, any sequence of consecutive newlines C<"\n\n"> at the
+beginning of the file is discarded.  With the exception of the final record in
+the file, each sequence of characters ending in two or more newlines is
+treated as one record and is read in to end in exactly two newlines.  If the
+last record in the file ends in zero or one consecutive newlines, that record
+is read in with that number of newlines.  If the last record ends in two or
+more consecutive newlines, it is read in with two newlines like all preceding
+records.
+
+Suppose we wrote the following string to a file:
+
+    my $string = "\n\n\n";
+    $string .= "alpha beta\ngamma delta\n\n\n";
+    $string .= "epsilon zeta eta\n\n";
+    $string .= "theta\n";
+
+    my $file = 'simple_file.txt'; 
+    open my $OUT, '>', $file or die;
+    print $OUT $string;
+    close $OUT or die;
+
+Now we read that file in paragraph mode:
+
+    local $/ = ""; # paragraph mode
+    open my $IN, '<', $file or die;
+    my @records = <$IN>;
+    close $IN or die;
+
+C<@records> will consist of these 3 strings:
+
+    (
+      "alpha beta\ngamma delta\n\n",
+      "epsilon zeta eta\n\n",
+      "theta\n",
+    )
+

 Setting C<$/> to a reference to an integer, scalar containing an
 integer, or scalar that's convertible to an integer will attempt to
 read records instead of lines, with the maximum record size being the
 Setting C<$/> to a reference to an integer, scalar containing an
 integer, or scalar that's convertible to an integer will attempt to
 read records instead of lines, with the maximum record size being the


@@ -1625,12 +1773,12 @@ Under a few operating systems, C<$^E> may contain a more verbose error
 indicator, such as in this case, "CDROM tray not closed."  Systems that
 do not support extended error messages leave C<$^E> the same as C<$!>.
 
 indicator, such as in this case, "CDROM tray not closed."  Systems that
 do not support extended error messages leave C<$^E> the same as C<$!>.
 

-Finally, C<$?> may be set to non-0 value if the external program
+Finally, C<$?> may be set to a non-0 value if the external program

 F</cdrom/install> fails.  The upper eight bits reflect specific error
 conditions encountered by the program (the program's C<exit()> value).
 The lower eight bits reflect mode of failure, like signal death and
 core dump information.  See L<wait(2)> for details.  In contrast to
 F</cdrom/install> fails.  The upper eight bits reflect specific error
 conditions encountered by the program (the program's C<exit()> value).
 The lower eight bits reflect mode of failure, like signal death and
 core dump information.  See L<wait(2)> for details.  In contrast to

-C<$!> and C<$^E>, which are set only if error condition is detected,
+C<$!> and C<$^E>, which are set only if an error condition is detected,

 the variable C<$?> is set on each C<wait> or pipe C<close>,
 overwriting the old value.  This is more like C<$@>, which on every
 C<eval()> is always set on failure and cleared on success.
 the variable C<$?> is set on each C<wait> or pipe C<close>,
 overwriting the old value.  This is more like C<$@>, which on every
 C<eval()> is always set on failure and cleared on success.


@@ -1660,7 +1808,7 @@ This variable was added in Perl v5.10.0.
 X<$^E> X<$EXTENDED_OS_ERROR>
 
 Error information specific to the current operating system.  At the
 X<$^E> X<$EXTENDED_OS_ERROR>
 
 Error information specific to the current operating system.  At the

-moment, this differs from C<$!> under only VMS, OS/2, and Win32 (and
+moment, this differs from C<L</$!>> under only VMS, OS/2, and Win32 (and

 for MacPerl).  On all other platforms, C<$^E> is always just the same
 as C<$!>.
 
 for MacPerl).  On all other platforms, C<$^E> is always just the same
 as C<$!>.
 


@@ -1678,7 +1826,7 @@ from within the Win32 API.  Most Win32-specific code will report errors
 via C<$^E>.  ANSI C and Unix-like calls set C<errno> and so most
 portable Perl code will report errors via C<$!>.
 
 via C<$^E>.  ANSI C and Unix-like calls set C<errno> and so most
 portable Perl code will report errors via C<$!>.
 

-Caveats mentioned in the description of C<$!> generally apply to
+Caveats mentioned in the description of C<L</$!>> generally apply to

 C<$^E>, also.
 
 This variable was added in Perl 5.003.
 C<$^E>, also.
 
 This variable was added in Perl 5.003.


@@ -1765,10 +1913,6 @@ It can be used immediately before invoking the C<die()> operator,
 to set the exit value, or to inspect the system error string
 corresponding to error I<n>, or to restore C<$!> to a meaningful state.
 
 to set the exit value, or to inspect the system error string
 corresponding to error I<n>, or to restore C<$!> to a meaningful state.
 

-Note that when stringified, the text is always returned as if both
-S<L<C<"use locale">|perllocale>> and S<L<C<"use bytes">|bytes>> are in
-effect.  This is likely to change in v5.22.
-

 Mnemonic: What just went bang?
 
 =item %OS_ERROR
 Mnemonic: What just went bang?
 
 =item %OS_ERROR


@@ -1782,10 +1926,12 @@ Each element of C<%!> has a true value only if C<$!> is set to that
 value.  For example, C<$!{ENOENT}> is true if and only if the current
 value of C<$!> is C<ENOENT>; that is, if the most recent error was "No
 such file or directory" (or its moral equivalent: not all operating
 value.  For example, C<$!{ENOENT}> is true if and only if the current
 value of C<$!> is C<ENOENT>; that is, if the most recent error was "No
 such file or directory" (or its moral equivalent: not all operating

-systems give that exact error, and certainly not all languages).  To
-check if a particular key is meaningful on your system, use C<exists
-$!{the_key}>; for a list of legal keys, use C<keys %!>.  See L<Errno>
-for more information, and also see L</$!>.
+systems give that exact error, and certainly not all languages).  The
+specific true value is not guaranteed, but in the past has generally
+been the numeric value of C<$!>.  To check if a particular key is
+meaningful on your system, use C<exists $!{the_key}>; for a list of legal
+keys, use C<keys %!>.  See L<Errno> for more information, and also see
+L</$!>.

 
 This variable was added in Perl 5.005.
 
 
 This variable was added in Perl 5.005.
 


@@ -1827,17 +1973,18 @@ Mnemonic: similar to B<sh> and B<ksh>.
 =item $@
 X<$@> X<$EVAL_ERROR>
 
 =item $@
 X<$@> X<$EVAL_ERROR>
 

-The Perl syntax error message from the
-last C<eval()> operator.  If C<$@> is
-the null string, the last C<eval()> parsed and executed correctly
-(although the operations you invoked may have failed in the normal
-fashion).
+The Perl error from the last C<eval> operator, i.e. the last exception that
+was caught.  For C<eval BLOCK>, this is either a runtime error message or the
+string or reference C<die> was called with.  The C<eval STRING> form also
+catches syntax errors and other compile time exceptions.
+
+If no error occurs, C<eval> sets C<$@> to the empty string.

 
 Warning messages are not collected in this variable.  You can, however,
 set up a routine to process warnings by setting C<$SIG{__WARN__}> as
 described in L</%SIG>.
 
 
 Warning messages are not collected in this variable.  You can, however,
 set up a routine to process warnings by setting C<$SIG{__WARN__}> as
 described in L</%SIG>.
 

-Mnemonic: Where was the syntax error "at"?
+Mnemonic: Where was the error "at"?

 
 =back
 
 
 =back
 


@@ -1866,20 +2013,42 @@ This variable was added in Perl v5.6.0.
 X<$^D> X<$DEBUGGING>
 
 The current value of the debugging flags.  May be read or set.  Like its
 X<$^D> X<$DEBUGGING>
 
 The current value of the debugging flags.  May be read or set.  Like its

-command-line equivalent, you can use numeric or symbolic values, eg
-C<$^D = 10> or C<$^D = "st">.
+L<command-line equivalent|perlrun/B<-D>I<letters>>, you can use numeric
+or symbolic values, e.g. C<$^D = 10> or C<$^D = "st">.  See
+L<perlrun/B<-D>I<number>>.  The contents of this variable also affects the
+debugger operation.  See L<perldebguts/Debugger Internals>.

 
 Mnemonic: value of B<-D> switch.
 
 =item ${^ENCODING}
 X<${^ENCODING}>
 
 
 Mnemonic: value of B<-D> switch.
 
 =item ${^ENCODING}
 X<${^ENCODING}>
 

-The I<object reference> to the C<Encode> object that is used to convert
-the source code to Unicode.  Thanks to this variable your Perl script
-does not have to be written in UTF-8.  Default is I<undef>.  The direct
-manipulation of this variable is highly discouraged.
+This variable is no longer supported.
+
+It used to hold the I<object reference> to the C<Encode> object that was
+used to convert the source code to Unicode.
+
+Its purpose was to allow your non-ASCII Perl
+scripts not to have to be written in UTF-8; this was
+useful before editors that worked on UTF-8 encoded text were common, but
+that was long ago.  It caused problems, such as affecting the operation
+of other modules that weren't expecting it, causing general mayhem.
+
+If you need something like this functionality, it is recommended that use
+you a simple source filter, such as L<Filter::Encoding>.
+
+If you are coming here because code of yours is being adversely affected
+by someone's use of this variable, you can usually work around it by
+doing this:

 
 

-This variable was added in Perl 5.8.2.
+ local ${^ENCODING};
+
+near the beginning of the functions that are getting broken.  This
+undefines the variable during the scope of execution of the including
+function.
+
+This variable was added in Perl 5.8.2 and removed in 5.26.0.
+Setting it to anything other than C<undef> was made fatal in Perl 5.28.0.

 
 =item ${^GLOBAL_PHASE}
 X<${^GLOBAL_PHASE}>
 
 =item ${^GLOBAL_PHASE}
 X<${^GLOBAL_PHASE}>


@@ -2042,7 +2211,9 @@ X<%^H>
 
 The C<%^H> hash provides the same scoping semantic as C<$^H>.  This makes
 it useful for implementation of lexically scoped pragmas.  See
 
 The C<%^H> hash provides the same scoping semantic as C<$^H>.  This makes
 it useful for implementation of lexically scoped pragmas.  See

-L<perlpragma>.
+L<perlpragma>.   All the entries are stringified when accessed at
+runtime, so only simple values can be accommodated.  This means no
+pointers to objects, for example.

 
 When putting items into C<%^H>, in order to avoid conflicting with other
 users of the hash there is a convention regarding which keys to use.
 
 When putting items into C<%^H>, in order to avoid conflicting with other
 users of the hash there is a convention regarding which keys to use.


@@ -2143,6 +2314,21 @@ This variable is read-only.
 
 This variable was added in Perl v5.8.0.
 
 
 This variable was added in Perl v5.8.0.
 

+=item ${^SAFE_LOCALES}
+X<${^SAFE_LOCALES}>
+
+Reflects if safe locale operations are available to this perl (when the
+value is 1) or not (the value is 0).  This variable is always 1 if the
+perl has been compiled without threads.  It is also 1 if this perl is
+using thread-safe locale operations.  Note that an individual thread may
+choose to use the global locale (generally unsafe) by calling
+L<perlapi/switch_to_global_locale>.  This variable currently is still
+set to 1 in such threads.
+
+This variable is read-only.
+
+This variable was added in Perl v5.28.0.
+

 =item ${^UNICODE}
 X<${^UNICODE}>
 
 =item ${^UNICODE}
 X<${^UNICODE}>
 


@@ -2236,37 +2422,16 @@ scopes in the same file, unlike other compile-time directives (such as
 L<strict>).  Using local() on it would bind its value strictly to a lexical
 block.  Now it is always lexically scoped.
 
 L<strict>).  Using local() on it would bind its value strictly to a lexical
 block.  Now it is always lexically scoped.
 

-As of Perl v5.16.0, it is implemented by the L<arybase> module.  See
-L<arybase> for more details on its behaviour.
+As of Perl v5.16.0, it is implemented by the L<arybase> module.

 
 

-Under C<use v5.16>, or C<no feature "array_base">, C<$[> no longer has any
-effect, and always contains 0.  Assigning 0 to it is permitted, but any
-other value will produce an error.
+As of Perl v5.30.0, or under C<use v5.16>, or C<no feature "array_base">,
+C<$[> no longer has any effect, and always contains 0.
+Assigning 0 to it is permitted, but any other value will produce an error.

 
 Mnemonic: [ begins subscripts.
 
 Deprecated in Perl v5.12.0.
 
 
 Mnemonic: [ begins subscripts.
 
 Deprecated in Perl v5.12.0.
 

-=item $]
-X<$]>
-
-See L</$^V> for a more modern representation of the Perl version that allows
-accurate string comparisons.
-
-The version + patchlevel / 1000 of the Perl interpreter.  This variable
-can be used to determine whether the Perl interpreter executing a
-script is in the right range of versions:
-
-    warn "No PerlIO!\n" if $] lt '5.008';
-
-The floating point representation can sometimes lead to inaccurate
-numeric comparisons, so string comparisons are recommended.
-
-See also the documentation of C<use VERSION> and C<require VERSION>
-for a convenient way to fail if the running Perl interpreter is too old.
-
-Mnemonic: Is this version of perl in the right bracket?
-

 =back
 
 =cut
 =back
 
 =cut