Document HyperWhatever

Closes #433

Author: zoffixznet

doc/Type/HyperWhatever.pod6

@@ -0,0 +1,51 @@
+=begin pod
+
+=TITLE class HyperWhatever
+
+=SUBTITLE Placeholder for multiple unspecified values/arguments
+
+    class HyperWhatever { }
+
+C<HyperWhatever> is very similar in functionality to L<Whatever>. The
+difference lies in C<HyperWhatever> standing in for I<multiple> values, rather
+than a single one.
+
+=head1 STANDALONE TERM
+
+Just like with L<Whatever>, if a L<HyperWhatever> is used as a term on its own,
+no currying is done and the L<HyperWhatever> object will be used as-is:
+
+    sub foo ($arg) { say $arg.^name }
+    foo **; # OUTPUT: «HyperWhatever␤»
+
+You can choose to interpret such a value as standing for multiple values in
+your own routines. In core, a L<HyperWhatever> can be used with this meaning
+when smartmatching with L<Lists|/type/List>:
+
+    say (1, 8)                ~~ (1, **, 8); # OUTPUT: «True␤»
+    say (1, 2, 4, 5, 6, 7, 8) ~~ (1, **, 8); # OUTPUT: «True␤»
+    say (1, 2, 8, 9)          ~~ (1, **, 8); # OUTPUT: «False␤»
+
+Wherever a L<HyperWhatever> appears in the list on the right-hand side means
+any number of elements can fill that space in the list being smartmatched.
+
+=head1 CURRYING
+
+When it comes to currying, the L<HyperWhatever> follows the same
+rules as L<Whatever>. The only difference is L<HyperWhatever> produces a
+L<Callable> with a L«C<*@> slurpy|/syntax/*@» as a signature:
+
+    say (**²)(1, 2, 3, 4, 5); # OUTPUT: «(1 4 9 16 25)␤»
+
+A L<HyperWhatever> closure can be imagined as a
+L«C<Whatever> closure|/type/WhateverCode» with another sub wrapped around it
+that simply maps each element in the arguments over:
+
+    my &hyper-whatever = sub (*@args) { map *², @args }
+    say hyper-whatever(1, 2, 3, 4, 5); # OUTPUT: «(1 4 9 16 25)␤»
+
+When currying, mixing L<HyperWhatever> with L<Whatever> is not permitted.
+
+=end pod
+
+# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6