Merge remote-tracking branch 'upstream/master'

Author: gfldex

doc/Language/control.pod

@@ -568,6 +568,21 @@ is equivalent to the C-ish idiom:
 
     loop (;;) {...}
 
+The C<loop> statement may be used to produce values from the result of each
+run of the attached block if it appears in lists:
+
+    (loop ( my $i = 0; $i++ < 3;) { $i * 2 }).say;               #-> "(2 4 6)"
+    my @a = (loop ( my $i = 0; $i++ < 3;) { $i * 2 }); @a.say;   #-> "[2 4 6]"
+    my @a = do loop ( my $i = 0; $i++ < 3;) { $i * 2 }); @a.say; # same thing
+
+Unlike a C<for> loop, one should not rely on whether returned values are produced
+lazily, for now.  It would probably be best to use C<eager> to guarantee that a
+loop whose return value may be used actually runs:
+
+    sub heads-in-a-row {
+        (eager loop (; 2.rand < 1;) { "heads".say })
+    }
+
 =head2 X<while, until|control flow,while until>
 
 The C<while> statement executes the block as long as its condition is
@@ -626,6 +641,8 @@ $x++ while $x < 12
 
 Also see C<repeat/while> and C<repeat/until> below.
 
+All these forms may produce a return value the same way C<loop> does.
+
 =head2 X<repeat/while, repeat/until|control flow,repeat>
 
 Perl 5 allows one to apply a statement modifier to a C<do> block such that
@@ -650,6 +667,8 @@ This can also be written quite naturally with C<until>:
         ...
     } until $x >= 10;
 
+All these forms may produce a return value the same way C<loop> does.
+
 =head2 X<return|control flow>
 
 =comment TODO