document Whatever

lib/Whatever.pod

@@ -0,0 +1,57 @@
+=begin pod
+
+=TITLE class Whatever
+
+    class Whatever { }
+
+C<Whatever> is a class whose objects don't really do much; it gets
+its semantic from other routines that accept C<Whatever>-objects as markers
+to do something special. The C<*> literal in term position creates a
+C<Whatever> object.
+
+Another source of speciality is that the compiler turns
+combinations of C<*> in term position and many operators into closures.
+This process is called I<Whatever-currying>.
+
+    my $c = * + 2;          # same as   -> $x { $x + 2 };
+    say $c(4);              # 6
+
+Multiple C<*> in one expression generate closures with as many arguments:
+
+    my $c = * + *;          # same as   -> $x, $y { $x + $y }
+
+C<*> in complex expressions also generate closures:
+
+    my $c = 4 * * + 5;      # same as   -> $x { 4 * $x + 5 }
+
+Calling a method on C<*> also create a closure:
+
+    say <a b c>.map: *.uc;  # A B C
+
+Those closure are of type L<WhateverCode>.
+
+Not all operators and syntactic constructs curry Whatever-stars.
+
+=begin table
+
+    Exception           Example     What it does
+    =========           =======     ============
+    comma               1, *, 2     generates a Parcel with a * element
+    range operators     1..*        Range.new(:from(1), :to(*));
+    series operator     1 ... *     infinite list
+    smart-matching      1 ~~ *      returns True
+    assignment          $x = *      assign * to $x
+    binding             $x := *     binds * to $x
+    list repetition     1 xx *      generates infinite list
+
+=end table
+
+=head1 Methods
+
+=head2 ACCEPTS
+
+    multi method ACCEPTS(Whatever:D: Mu $other)
+
+Returns C<True>.
+
+=end pod