Merge remote-tracking branch 'upstream/master'

doc/Language/control.pod

@@ -284,32 +284,41 @@ There are also C<with> and C<without> statement modifiers:
 
 =head2 X<for|control flow>
 
-The C<for> loop iterates over a list.
+The C<for> loop iterates over a list, running the statements inside a block
+once on each iteration.  If the block takes parameters, the elements of the
+list are provided as arguments.
 
 =begin code
 
-for @foo {.print}
+for @foo { $_.print } # prints each value contained in @foo
+for @foo { .print }   # same thing, because .print implies a $_ argument
+for @foo { 42.print } # prints 42 as many times as @foo has elements
 
 =end code
 
-Use pointy block syntax to get an iteration variable.
+Pointy block syntax or a L<placeholder|language/variables#The C<^> Twigil>
+may be used to name the parameter, of course.
 
 =begin code
 
 for @foo -> $item { print $item }
+for @foo { print $^item }            # same thing
 
 =end code
 
-Multiple parameters can be declared.
+Multiple parameters can be declared, in which case the iterator takes
+as many elements from the list as needed before running the block.
 
 =begin code
 
 for %hash.kv -> $key, $value { print "$key => $value\n" }
+for 1, 1.1, 2, 2.1 { say "$^x < $^y" }  # says "1 < 1.1" then says "2 < 2.1"
 
 =end code
 
-The list in a C<for> loop is evaluated lazily by default, so to read a file
-line by line, you could use
+A C<for> may be used on lazy lists -- it will only take elements from the
+list when they are needed, so to read a file line by line, you could
+use:
 
 =begin code
 
@@ -328,6 +337,18 @@ for @cars <-> $_ {...}
 
 =end code
 
+A for loop can produce a a C<List> of the values produced by each run of the
+attached block.  To capture these values, put the for loop in parenthesis or
+assign them to an array:
+
+=begin code
+
+(for 1,2,3 { $_ * 2 }).say;             # says "(2 4 6)"
+my @a = do for 1,2,3 { $_ * 2 }; @a.say;# says "[2 4 6]"
+my @a = (for 1,2,3 { $_ * 2 }); @a.say; # same thing
+
+=end code
+
 =head2 X<gather/take|control flow,gather take>
 
 C<gather> is a statement or block prefix that returns a L<sequence|/type/Seq>

doc/Language/operators.pod

@@ -117,22 +117,28 @@ different semantics, as explained in detail as follows.
 
 =head2 Assignment Operators
 
-Most operators can be combined with the assignment operator to modify a 
+Infix operators can be combined with the assignment operator to modify a
 value and apply the result to a container in one go. Containers will be
 autovivified if possible.
 
     my $a = 32;
     $a += 10;  # 42
-    
-    my $a = 3; 
+
+    my $a = 3;
     $a min= 5; # still 3
     $a min= 2; # 2
 
 Z<blocked by #63642 my @a = 1,2; @a ,= 3,4;>
 
+This behavior is automatically extended to include custom-defined infix operators.
+
+    sub infix:<space-concat> ($a,$b) { $a ~ " " ~ $b };
+    my $a = 'word1';
+    $a space-concat= 'word2'; # 'word1 word2'
+
 Although not strictly operators, methods can be used in the same fashion.
 
-    my SomeClass $a .= new;
+    my Rat $a .= new;
     my $a = 3.14;
     $a .= Int; # 3
 
@@ -295,7 +301,7 @@ Universal interface for positional access to zero or more elements of a
     say @alphabet[100]:exists;          #-> False
     say @alphabet[15, 4, 17, 11].join;  #-> perl
     say @alphabet[23 .. *].perl;        #-> ("x", "y", "z")
-    
+
     @alphabet[1, 2] = "B", "C";
     say @alphabet[0..3].perl            #-> ("a", "B", "C", "d")
 
@@ -314,7 +320,7 @@ Universal interface for associative access to zero or more elements of a
     say %color{"banana"};               #-> yellow
     say %color{"cherry", "kiwi"}.perl;  #-> ("red", "green")
     say %color{"strawberry"}:exists;    #-> False
-    
+
     %color{"banana", "lime"} = "yellowish", "green";
     %color{"cherry"}:delete;
     say %color;  #-> banana => yellowish, kiwi => green, lime => green