document Block

Author: moritz

lib/Block.pod

@@ -0,0 +1,47 @@
+=begin pod
+
+=TITLE class Block
+
+    class Block is Code { }
+
+A C<Block> is a code object meant for small-scale code reuse. A block is
+created syntactically by a list of statements enclosed in curly brackets.
+
+Without an explicit signature or placeholder arguments, a block has C<$_>
+as a positional argument
+
+    my $block = { uc $_; };
+    say $block.WHAT;            # Block
+    say $block('hello');        # HELLO
+
+A block can have a signature between C<< -> >> or C<< <-> >> and the block:
+
+    my $add = -> $a, $b { $a + $b };
+    say $add(38, 4);            # 42
+
+If the signature is introduced with C<< <-> >>, then the parameters are marked
+as C<rw> by default:
+
+    my $swap = <-> $a, $b { ($a, $b) = ($b, $a) };
+
+    my ($a, $b) = (2, 4);
+    $swap($a, $b);
+    say $a;                     # 4
+
+Blocks that aren't of type C<Routine> (which is a subclass of C<Block>) are
+transparent to L<return>.
+
+    sub f() {
+        say <a b c>.map: { return 42 };
+                       #   ^^^^^^   exits &f, not just the block
+    }
+
+Bare blocks in sink context are automatically executed:
+
+    say 1;
+    {
+        say 2;                  # executed directly, not a Block object
+    }
+    say 3;
+
+=end pod