Document lvalue references

1 files changed, 16 insertions, 1 deletions

diff --git a/pod/perlsyn.pod b/pod/perlsyn.pod
index 2a5ced5303..731b036c2b 100644
--- a/pod/perlsyn.pod
+++ b/pod/perlsyn.pod
@@ -469,7 +469,7 @@ X<readline> X<< <> >>
 =head2 Foreach Loops
 X<for> X<foreach>
 
-The C<foreach> loop iterates over a normal list value and sets the
+The C<foreach> loop iterates over a normal list value and sets the scalar
 variable VAR to be each element of the list in turn.  If the variable
 is preceded with the keyword C<my>, then it is lexically scoped, and
 is therefore visible only within the loop.  Otherwise, the variable is
@@ -499,6 +499,15 @@ X<splice>
 C<foreach> probably won't do what you expect if VAR is a tied or other
 special variable.   Don't do that either.
 
+As of Perl 5.22, there is an experimental variant of this loop that accepts
+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>
+feature via C<use feature>.  (See L<feature>.  See also L<perlref/Assigning
+to References>.)
+
 Examples:
 
     for (@ary) { s/foo/bar/ }
@@ -518,6 +527,12 @@ Examples:
 	print "Item: $item\n";
     }
 
+    use feature "lvalue_refs";
+    no warnings "experimental::lvalue_refs";
+    foreach \my %hash (@array_of_hash_references) {
+	# do something which each %hash
+    }
+
 Here's how a C programmer might code up a particular algorithm in Perl:
 
     for (my $i = 0; $i < @ary1; $i++) {