stop gensyming when vivifying IO handles

[perl5.git] / pod / perlref.pod

diff --git a/pod/perlref.pod b/pod/perlref.pod
index 5804c17..fa9e033 100644 (file)
--- a/pod/perlref.pod
+++ b/pod/perlref.pod
@@ -51,13 +51,6 @@ When a scalar is holding a reference, it always behaves as a simple scalar.
 It doesn't magically start being an array or hash or subroutine; you have to
 tell it explicitly to do so, by dereferencing it.
 
-That said, be aware that Perl version 5.14 introduces an exception
-to the rule, for syntactic convenience.  Experimental array and hash container
-function behavior allows array and hash references to be handled by Perl as
-if they had been explicitly syntactically dereferenced.  See
-L<perl5140delta/"Syntactical Enhancements">
-and L<perlfunc> for details.
-
 =head2 Making References
 X<reference, creation> X<referencing>
 
@@ -272,8 +265,9 @@ the IO handle, used for file handles (L<perlfunc/open>), sockets
 (L<perlfunc/socket> and L<perlfunc/socketpair>), and directory
 handles (L<perlfunc/opendir>).  For compatibility with previous
 versions of Perl, C<*foo{FILEHANDLE}> is a synonym for C<*foo{IO}>, though it
-is deprecated as of 5.8.0.  If deprecation warnings are in effect, it will warn
-of its use.
+is discouraged, to encourage a consistent use of one name: IO.  On perls
+between v5.8 and v5.22, it will issue a deprecation warning, but this
+deprecation has since been rescinded.
 
 C<*foo{THING}> returns undef if that particular THING hasn't been used yet,
 except in the case of scalars.  C<*foo{SCALAR}> returns a reference to an
@@ -724,7 +718,7 @@ outer() at the time outer is invoked.
 This has the interesting effect of creating a function local to another
 function, something not normally supported in Perl.
 
-=head1 WARNING
+=head1 WARNING: Don't use references as hash keys
 X<reference, string context> X<reference, use as hash key>
 
 You may not (usefully) use a reference as the key to a hash.  It will be
@@ -744,7 +738,7 @@ real refs, instead of the keys(), which won't.
 
 The standard Tie::RefHash module provides a convenient workaround to this.
 
-=head1 Postfix Dereference Syntax
+=head2 Postfix Dereference Syntax
 
 Beginning in v5.20.0, a postfix syntax for using references is
 available.  It behaves as described in L</Using References>, but instead
@@ -804,7 +798,7 @@ As with postfix array, postfix value slice dereferencing I<can> be used
 in interpolating strings (double quotes or the C<qq> operator), but only
 if the C<postderef_qq> L<feature> is enabled.
 
-=head1 Assigning to References
+=head2 Assigning to References
 
 Beginning in v5.22.0, the referencing operator can be assigned to.  It
 performs an aliasing operation, so that the variable name referenced on the
@@ -915,6 +909,29 @@ will only be visible within that inner sub, and will not affect the outer
 subroutine where the variables are declared.  This bizarre behavior is
 subject to change.
 
+=head1 Declaring a Reference to a Variable
+
+Beginning in v5.26.0, the referencing operator can come after C<my>,
+C<state>, C<our>, or C<local>.  This syntax must be enabled with C<use
+feature 'declared_refs'>.  It is experimental, and will warn by default
+unless C<no warnings 'experimental::refaliasing'> is in effect.
+
+This feature makes these:
+
+    my \$x;
+    our \$y;
+
+equivalent to:
+
+    \my $x;
+    \our $x;
+
+It is intended mainly for use in assignments to references (see
+L</Assigning to References>, above).  It also allows the backslash to be
+used on just some items in a list of declared variables:
+
+    my ($foo, \@bar, \%baz); # equivalent to:  my $foo, \my(@bar, %baz);
+
 =head1 SEE ALSO
 
 Besides the obvious documents, source code can be instructive.