Update docs for declared_refs
authorFather Chrysostomos <sprout@cpan.org>
Sun, 29 May 2016 21:29:28 +0000 (14:29 -0700)
committerFather Chrysostomos <sprout@cpan.org>
Sun, 17 Jul 2016 18:27:02 +0000 (11:27 -0700)
lib/feature.pm
pod/perlexperiment.pod
pod/perlref.pod
regen/feature.pl

index ddab733..5524e5b 100644 (file)
@@ -355,6 +355,22 @@ See L<perlop/Bitwise String Operators> for details.
 
 This feature is available from Perl 5.22 onwards.
 
+=head2 The 'declared_refs' feature
+
+B<WARNING>: This feature is still experimental and the implementation may
+change in future versions of Perl.  For this reason, Perl will
+warn when you use the feature, unless you have explicitly disabled the
+warning:
+
+    no warnings "experimental::declared_refs";
+
+This allows a reference to a variable to be declared with C<my>, C<state>,
+our C<our>, or localized with C<local>.  It is intended mainly for use in
+conjunction with the "refaliasing" feature.  See L<perlref/Declaring a
+Reference to a Variable> for examples.
+
+This feature is available from Perl 5.26 onwards.
+
 =head1 FEATURE BUNDLES
 
 It's possible to load multiple features together, using
index 2e33177..5e734b6 100644 (file)
@@ -120,6 +120,18 @@ L<[perl #119453]|https://rt.perl.org/rt3/Ticket/Display.html?id=119453>.
 
 See also L<perlrun>
 
+=item Declaring a reference to a variable
+
+Introduced in Perl 5.26.0
+
+Using this feature triggers warnings in the category
+C<experimental::declared_refs>.
+
+The ticket for this feature is
+L<[perl #128654]|https://rt.perl.org/rt3/Ticket/Display.html?id=128654>.
+
+See also: L<perlref/Declaring a Reference to a Variable>
+
 =item There is an C<installhtml> target in the Makefile.
 
 The ticket for this feature is
index 8959ba5..a071f1f 100644 (file)
@@ -909,6 +909,26 @@ 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.
index 78c7400..92655da 100755 (executable)
@@ -665,6 +665,22 @@ See L<perlop/Bitwise String Operators> for details.
 
 This feature is available from Perl 5.22 onwards.
 
+=head2 The 'declared_refs' feature
+
+B<WARNING>: This feature is still experimental and the implementation may
+change in future versions of Perl.  For this reason, Perl will
+warn when you use the feature, unless you have explicitly disabled the
+warning:
+
+    no warnings "experimental::declared_refs";
+
+This allows a reference to a variable to be declared with C<my>, C<state>,
+our C<our>, or localized with C<local>.  It is intended mainly for use in
+conjunction with the "refaliasing" feature.  See L<perlref/Declaring a
+Reference to a Variable> for examples.
+
+This feature is available from Perl 5.26 onwards.
+
 =head1 FEATURE BUNDLES
 
 It's possible to load multiple features together, using