Rename lvalue references

Also correct the description of lvref magic.  When it was first added,
it was for list assignments only, but that soon changed.

20 files changed, 67 insertions, 67 deletions

diff --git a/MANIFEST b/MANIFEST
index c620292753..e6ad9f571d 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -5138,7 +5138,7 @@ t/op/local.t			See if local works
 t/op/lock.t			Tests for lock args & retval (no threads)
 t/op/loopctl.t			See if next/last/redo work
 t/op/lop.t			See if logical operators work
-t/op/lvref.t			See if lvalue references work
+t/op/lvref.t			See if aliasing via references works
 t/op/magic-27839.t		Test for #27839, skipped for minitest
 t/op/magic.t			See if magic variables work
 t/op/method.t			See if method calls work
diff --git a/cpan/experimental/t/basic.t b/cpan/experimental/t/basic.t
index 5dc2eafab9..df3ce2ce7f 100644
--- a/cpan/experimental/t/basic.t
+++ b/cpan/experimental/t/basic.t
@@ -52,7 +52,7 @@ END
 
 if ($] >= 5.021005) {
 	is (eval <<'END', 1, 'lvalue ref compiles') or diag $@;
-	use experimental 'lvalue_refs';
+	use experimental 'refaliasing';
 	\@a = \@b;
 	is(\@a, \@b, '@a and @b are the same after \@a=\@b');
 	1;
diff --git a/feature.h b/feature.h
index c6c71e331e..370896e01e 100644
--- a/feature.h
+++ b/feature.h
@@ -93,10 +93,10 @@
 	 FEATURE_IS_ENABLED("__SUB__")) \
     )
 
-#define FEATURE_LVREF_IS_ENABLED \
+#define FEATURE_REFALIASING_IS_ENABLED \
     ( \
 	CURRENT_FEATURE_BUNDLE == FEATURE_BUNDLE_CUSTOM && \
-	 FEATURE_IS_ENABLED("lvref") \
+	 FEATURE_IS_ENABLED("refaliasing") \
     )
 
 #define FEATURE_LEXSUBS_IS_ENABLED \
diff --git a/lib/B/Deparse.t b/lib/B/Deparse.t
index 7a0c4d9973..75d05e4b73 100644
--- a/lib/B/Deparse.t
+++ b/lib/B/Deparse.t
@@ -1621,7 +1621,7 @@ use feature 'state';
 main::state();
 ####
 # lvalue references
-# CONTEXT use feature "state", 'lvalue_refs', 'lexical_subs'; no warnings 'experimental';
+# CONTEXT use feature "state", 'refaliasing', 'lexical_subs'; no warnings 'experimental';
 our $x;
 \$x = \$x;
 my $m;
diff --git a/lib/feature.pm b/lib/feature.pm
index fe78881717..b902d51fee 100644
--- a/lib/feature.pm
+++ b/lib/feature.pm
@@ -17,7 +17,7 @@ our %feature = (
     array_base      => 'feature_arybase',
     signatures      => 'feature_signatures',
     current_sub     => 'feature___SUB__',
-    lvalue_refs     => 'feature_lvref',
+    refaliasing     => 'feature_refaliasing',
     lexical_subs    => 'feature_lexsubs',
     postderef_qq    => 'feature_postderef_qq',
     unicode_eval    => 'feature_unieval',
@@ -28,7 +28,7 @@ our %feature_bundle = (
     "5.10"    => [qw(array_base say state switch)],
     "5.11"    => [qw(array_base say state switch unicode_strings)],
     "5.15"    => [qw(current_sub evalbytes fc say state switch unicode_eval unicode_strings)],
-    "all"     => [qw(array_base current_sub evalbytes fc lexical_subs lvalue_refs postderef postderef_qq say signatures state switch unicode_eval unicode_strings)],
+    "all"     => [qw(array_base current_sub evalbytes fc lexical_subs postderef postderef_qq refaliasing say signatures state switch unicode_eval unicode_strings)],
     "default" => [qw(array_base)],
 );
 
@@ -275,14 +275,14 @@ See L<perlsub/Signatures> for details.
 
 This feature is available from Perl 5.20 onwards.
 
-=head2 The 'lvalue_refs' feature
+=head2 The 'refaliasing' 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::lvalue_refs";
+    no warnings "experimental::refaliasing";
 
 This enables aliasing via assignment to references:
 
diff --git a/lib/warnings.pm b/lib/warnings.pm
index b2062915ff..05a1198d79 100644
--- a/lib/warnings.pm
+++ b/lib/warnings.pm
@@ -93,7 +93,7 @@ our %Offsets = (
 
     # Warnings Categories added in Perl 5.021
 
-    'experimental::lvalue_refs'=> 120,
+    'experimental::refaliasing'=> 120,
     'experimental::win32_perlio'=> 122,
     'missing'		=> 124,
     'redundant'		=> 126,
@@ -114,8 +114,8 @@ our %Bits = (
     'experimental::autoderef'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00", # [56]
     'experimental::lexical_subs'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00", # [52]
     'experimental::lexical_topic'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00", # [53]
-    'experimental::lvalue_refs'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01", # [60]
     'experimental::postderef'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00", # [57]
+    'experimental::refaliasing'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01", # [60]
     'experimental::regex_sets'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x10\x00\x00", # [54]
     'experimental::signatures'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x10\x00", # [58]
     'experimental::smartmatch'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x40\x00\x00", # [55]
@@ -181,8 +181,8 @@ our %DeadBits = (
     'experimental::autoderef'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00", # [56]
     'experimental::lexical_subs'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x00", # [52]
     'experimental::lexical_topic'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x08\x00\x00", # [53]
-    'experimental::lvalue_refs'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02", # [60]
     'experimental::postderef'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x08\x00", # [57]
+    'experimental::refaliasing'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02", # [60]
     'experimental::regex_sets'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x20\x00\x00", # [54]
     'experimental::signatures'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x20\x00", # [58]
     'experimental::smartmatch'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80\x00\x00", # [55]
@@ -234,7 +234,7 @@ our %DeadBits = (
   );
 
 $NONE     = "\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0";
-$DEFAULT  = "\x10\x01\x00\x00\x00\x50\x04\x00\x00\x00\x00\x00\x00\x55\x15\x05", # [2,56,52,53,60,57,54,58,55,61,4,22,23,25]
+$DEFAULT  = "\x10\x01\x00\x00\x00\x50\x04\x00\x00\x00\x00\x00\x00\x55\x15\x05", # [2,56,52,53,57,60,54,58,55,61,4,22,23,25]
 $LAST_BIT = 128 ;
 $BYTES    = 16 ;
 
@@ -726,10 +726,10 @@ The current hierarchy is:
          |                 |
          |                 +- experimental::lexical_topic
          |                 |
-         |                 +- experimental::lvalue_refs
-         |                 |
          |                 +- experimental::postderef
          |                 |
+         |                 +- experimental::refaliasing
+         |                 |
          |                 +- experimental::regex_sets
          |                 |
          |                 +- experimental::signatures
diff --git a/mg_raw.h b/mg_raw.h
index 4b3d35d428..3095d584fe 100644
--- a/mg_raw.h
+++ b/mg_raw.h
@@ -83,7 +83,7 @@
     { 'y', "want_vtbl_defelem | PERL_MAGIC_VALUE_MAGIC",
       "/* defelem 'y' Shadow \"foreach\" iterator variable / smart parameter vivification */" },
     { '\\', "want_vtbl_lvref",
-      "/* lvref '\\' Lvalue reference in list assignment */" },
+      "/* lvref '\\' Lvalue reference constructor */" },
     { ']', "want_vtbl_checkcall | PERL_MAGIC_VALUE_MAGIC",
       "/* checkcall ']' Inlining/mutation of call to this CV */" },
     { '~', "magic_vtable_max",
diff --git a/mg_vtable.h b/mg_vtable.h
index 2ee636106e..c0bb820551 100644
--- a/mg_vtable.h
+++ b/mg_vtable.h
@@ -55,7 +55,7 @@
 #define PERL_MAGIC_substr         'x' /* substr() lvalue */
 #define PERL_MAGIC_defelem        'y' /* Shadow "foreach" iterator variable /
                                          smart parameter vivification */
-#define PERL_MAGIC_lvref          '\\' /* Lvalue reference in list assignment */
+#define PERL_MAGIC_lvref          '\\' /* Lvalue reference constructor */
 #define PERL_MAGIC_checkcall      ']' /* Inlining/mutation of call to this CV */
 #define PERL_MAGIC_ext            '~' /* Available for use by extensions */
 
diff --git a/op.c b/op.c
index 7c5964881d..a2d402717c 100644
--- a/op.c
+++ b/op.c
@@ -2772,12 +2772,12 @@ Perl_op_lvalue_flags(pTHX_ OP *o, I32 type, U32 flags)
 	    const U8 ec = PL_parser ? PL_parser->error_count : 0;
 	    S_lvref(aTHX_ kid, type);
 	    if (!PL_parser || PL_parser->error_count == ec) {
-		if (!FEATURE_LVREF_IS_ENABLED)
+		if (!FEATURE_REFALIASING_IS_ENABLED)
 		    Perl_croak(aTHX_
-			     "Experimental lvalue references not enabled");
+		       "Experimental aliasing via reference not enabled");
 		Perl_ck_warner_d(aTHX_
-				 packWARN(WARN_EXPERIMENTAL__LVALUE_REFS),
-			      "Lvalue references are experimental");
+				 packWARN(WARN_EXPERIMENTAL__REFALIASING),
+				"Aliasing via reference is experimental");
 	    }
 	}
 	if (o->op_type == OP_REFGEN)
@@ -10174,12 +10174,12 @@ Perl_ck_refassign(pTHX_ OP *o)
 				 OP_DESC(varop)));
 	return o;
     }
-    if (!FEATURE_LVREF_IS_ENABLED)
+    if (!FEATURE_REFALIASING_IS_ENABLED)
 	Perl_croak(aTHX_
-		  "Experimental lvalue references not enabled");
+		  "Experimental aliasing via reference not enabled");
     Perl_ck_warner_d(aTHX_
-		     packWARN(WARN_EXPERIMENTAL__LVALUE_REFS),
-		    "Lvalue references are experimental");
+		     packWARN(WARN_EXPERIMENTAL__REFALIASING),
+		    "Aliasing via reference is experimental");
     o->op_private |= varop->op_private & (OPpLVAL_INTRO|OPpPAD_STATE);
     if (stacked) o->op_flags |= OPf_STACKED;
     else {
diff --git a/pod/perldiag.pod b/pod/perldiag.pod
index a163937c5a..46052b8ee3 100644
--- a/pod/perldiag.pod
+++ b/pod/perldiag.pod
@@ -50,6 +50,19 @@ letter.
 to check the return value of your socket() call?  See
 L<perlfunc/accept>.
 
+=item Aliasing via reference is experimental
+
+(S experimental::refaliasing) This warning is emitted if you use
+a reference constructor on the left-hand side of an assignment to
+alias one variable to another.  Simply suppress the warning if you
+want to use the feature, but know that in doing so you are taking
+the risk of using an experimental feature which may change or be
+removed in a future Perl version:
+
+    no warnings "experimental::refaliasing";
+    use feature "refaliasing";
+    \$x = \$y;
+
 =item Allocation too large: %x
 
 (X) You can't allocate more than 64K on an MS-DOS machine.
@@ -209,9 +222,9 @@ C<\$x = \$y>.
 
 =item Assigned value is not %s reference
 
-(F) You tried to assign a reference to an lvalue reference, but the two
-references were not of the same type.  You cannot alias a scalar to an
-array, or an array to a hash; the two types must match.
+(F) You tried to assign a reference to a reference constructor, but the
+two references were not of the same type.  You cannot alias a scalar to
+an array, or an array to a hash; the two types must match.
 
     \$x = \@y;  # error
     \@x = \%y;  # error
@@ -1961,12 +1974,12 @@ interpolated.  If you see this error message, then you probably
 have some other C<(?...)> construct inside your character class.  See
 L<perlrecharclass/Extended Bracketed Character Classes>.
 
-=item Experimental lvalue references not enabled
+=item Experimental aliasing via reference not enabled
 
-(F) To use lvalue references, you must first enable them:
+(F) To do aliasing via references, you must first enable the feature:
 
-    no warnings "experimental::lvalue_refs";
-    use feature "lvalue_refs";
+    no warnings "experimental::refaliasing";
+    use feature "refaliasing";
     \$x = \$y;
 
 =item Experimental subroutine signatures not enabled
@@ -2926,19 +2939,6 @@ foo :lvalue;> declaration before the definition.
 
 See also L<attributes.pm|attributes>.
 
-=item Lvalue references are experimental
-
-(S experimental::lvalue_refs) This warning is emitted if you use
-a reference constructor on the left-hand side of an assignment to
-alias one variable to another.  Simply suppress the warning if you
-want to use the feature, but know that in doing so you are taking
-the risk of using an experimental feature which may change or be
-removed in a future Perl version:
-
-    no warnings "experimental::lvalue_refs";
-    use feature "lvalue_refs";
-    \$x = \$y;
-
 =item Magical list constants are not supported
 
 (F) You assigned a magical array to a stash element, and then tried
diff --git a/pod/perlexperiment.pod b/pod/perlexperiment.pod
index 093e887f6b..ee48e23a4d 100644
--- a/pod/perlexperiment.pod
+++ b/pod/perlexperiment.pod
@@ -111,12 +111,12 @@ C<experimental::postderef>.
 The ticket for this feature is
 L<[perl #120162]|https://rt.perl.org:443/rt3/Ticket/Display.html?id=120162>.
 
-=item Lvalue references
+=item Aliasing via reference
 
 Introduced in Perl 5.22.0
 
 Using this feature triggers warnings in the category
-C<experimental::lvalue_refs>.
+C<experimental::refaliasing>.
 
 The ticket for this feature is
 L<[perl #122947]|https://rt.perl.org/rt3/Ticket/Display.html?id=122947>.
diff --git a/pod/perlguts.pod b/pod/perlguts.pod
index e9aba641ad..60f74c1194 100644
--- a/pod/perlguts.pod
+++ b/pod/perlguts.pod
@@ -1218,8 +1218,8 @@ will be lost.
  y  PERL_MAGIC_defelem        vtbl_defelem   Shadow "foreach" iterator
                                              variable / smart parameter
                                              vivification
- \  PERL_MAGIC_lvref          vtbl_lvref     Lvalue reference in list
-                                             assignment
+ \  PERL_MAGIC_lvref          vtbl_lvref     Lvalue reference
+                                             constructor
  ]  PERL_MAGIC_checkcall      vtbl_checkcall Inlining/mutation of call
                                              to this CV
  ~  PERL_MAGIC_ext            (none)         Available for use by
diff --git a/pod/perlref.pod b/pod/perlref.pod
index 5df9a70660..d3c12f17fe 100644
--- a/pod/perlref.pod
+++ b/pod/perlref.pod
@@ -814,9 +814,9 @@ side:
     \$a = \$b; # $a and $b now point to the same scalar
     \&foo = \&bar; # foo() now means bar()
 
-This syntax must be enabled with C<use feature 'lvalue_refs'>.  It is
+This syntax must be enabled with C<use feature 'refaliasing'>.  It is
 experimental, and will warn by default unless C<no warnings
-'experimental::lvalue_refs'> is in effect.
+'experimental::refaliasing'> is in effect.
 
 These forms may be assigned to, and cause the right-hand side to be
 evaluated in scalar context:
diff --git a/pod/perlsyn.pod b/pod/perlsyn.pod
index 731b036c2b..0792e9943a 100644
--- a/pod/perlsyn.pod
+++ b/pod/perlsyn.pod
@@ -504,7 +504,7 @@ a variable preceded by a backslash for VAR, in which case the items in the
 LIST must be references.  The backslashed variable will become an alias
 to each referenced item in the LIST, which must be of the correct type.
 The variable needn't be a scalar in this case, and the backslash may be
-followed by C<my>.  To use this form, you must enable the C<lvalue_refs>
+followed by C<my>.  To use this form, you must enable the C<refaliasing>
 feature via C<use feature>.  (See L<feature>.  See also L<perlref/Assigning
 to References>.)
 
@@ -527,8 +527,8 @@ Examples:
 	print "Item: $item\n";
     }
 
-    use feature "lvalue_refs";
-    no warnings "experimental::lvalue_refs";
+    use feature "refaliasing";
+    no warnings "experimental::refaliasing";
     foreach \my %hash (@array_of_hash_references) {
 	# do something which each %hash
     }
diff --git a/regen/feature.pl b/regen/feature.pl
index b58381c5d2..ed7c4907f3 100755
--- a/regen/feature.pl
+++ b/regen/feature.pl
@@ -29,7 +29,7 @@ my %feature = (
     postderef       => 'postderef',
     array_base      => 'arybase',
     current_sub     => '__SUB__',
-    lvalue_refs     => 'lvref',
+    refaliasing     => 'refaliasing',
     lexical_subs    => 'lexsubs',
     postderef_qq    => 'postderef_qq',
     unicode_eval    => 'unieval',
@@ -590,14 +590,14 @@ See L<perlsub/Signatures> for details.
 
 This feature is available from Perl 5.20 onwards.
 
-=head2 The 'lvalue_refs' feature
+=head2 The 'refaliasing' 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::lvalue_refs";
+    no warnings "experimental::refaliasing";
 
 This enables aliasing via assignment to references:
 
diff --git a/regen/mg_vtable.pl b/regen/mg_vtable.pl
index cb61908780..247423c305 100644
--- a/regen/mg_vtable.pl
+++ b/regen/mg_vtable.pl
@@ -111,7 +111,7 @@ my %mg =
      debugvar => { char => '*', desc => '$DB::single, signal, trace vars',
 		   vtable => 'debugvar' },
      lvref => { char => '\\', vtable => 'lvref',
-		  desc => "Lvalue reference in list assignment" },
+		  desc => "Lvalue reference constructor" },
 );
 
 # These have a subtly different "namespace" from the magic types.
diff --git a/regen/warnings.pl b/regen/warnings.pl
index 6c27a16278..4e3a6245a4 100644
--- a/regen/warnings.pl
+++ b/regen/warnings.pl
@@ -102,7 +102,7 @@ my $tree = {
                                     [ 5.019, DEFAULT_ON ],
                                 'experimental::win32_perlio' =>
                                     [ 5.021, DEFAULT_ON ],
-                                'experimental::lvalue_refs' =>
+                                'experimental::refaliasing' =>
                                     [ 5.021, DEFAULT_ON ],
                         }],
 
diff --git a/t/op/lvref.t b/t/op/lvref.t
index d55ccd2a7f..2bdc26d8f4 100644
--- a/t/op/lvref.t
+++ b/t/op/lvref.t
@@ -7,29 +7,29 @@ BEGIN {
 plan 153;
 
 eval '\$x = \$y';
-like $@, qr/^Experimental lvalue references not enabled/,
+like $@, qr/^Experimental aliasing via reference not enabled/,
     'error when feature is disabled';
 eval '\($x) = \$y';
-like $@, qr/^Experimental lvalue references not enabled/,
+like $@, qr/^Experimental aliasing via reference not enabled/,
     'error when feature is disabled (aassign)';
 
-use feature 'lvalue_refs', 'state';
+use feature 'refaliasing', 'state';
 
 {
     my($w,$c);
     local $SIG{__WARN__} = sub { $c++; $w = shift };
     eval '\$x = \$y';
     is $c, 1, 'one warning from lv ref assignment';
-    like $w, qr/^Lvalue references are experimental/,
+    like $w, qr/^Aliasing via reference is experimental/,
         'experimental warning';
     undef $c;
     eval '\($x) = \$y';
     is $c, 1, 'one warning from lv ref list assignment';
-    like $w, qr/^Lvalue references are experimental/,
+    like $w, qr/^Aliasing via reference is experimental/,
         'experimental warning';
 }
 
-no warnings 'experimental::lvalue_refs';
+no warnings 'experimental::refaliasing';
 
 # Scalars
 
diff --git a/t/op/ref.t b/t/op/ref.t
index dbd532271c..6ce0480c25 100644
--- a/t/op/ref.t
+++ b/t/op/ref.t
@@ -322,7 +322,7 @@ is (scalar (@bzz), 3);
 # (That’s what *you* think!  --sprout)
 eval '\\($x, $y) = (1, 2);';
 like ($@, qr/Can\'t modify.*ref.*in.*assignment(?x:
-           )|Experimental lvalue references not enabled/);
+           )|Experimental aliasing via reference not enabled/);
 
 # test for proper destruction of lexical objects
 $test = curr_test();
diff --git a/warnings.h b/warnings.h
index e2ee66a566..b288bd50d4 100644
--- a/warnings.h
+++ b/warnings.h
@@ -104,7 +104,7 @@
 
 /* Warnings Categories added in Perl 5.021 */
 
-#define WARN_EXPERIMENTAL__LVALUE_REFS 60
+#define WARN_EXPERIMENTAL__REFALIASING 60
 #define WARN_EXPERIMENTAL__WIN32_PERLIO 61
 #define WARN_MISSING		 62
 #define WARN_REDUNDANT		 63