=begin pod :kind("Type") :subkind("class") :category("basic")

=TITLE class Whatever

=SUBTITLE Placeholder for the value of an unspecified argument

    class Whatever { }

X<|* literal> X<|Whatever literal>
C<Whatever> is a class whose objects don't have any explicit meaning; it
gets its semantics from other routines that accept C<Whatever>-objects
as markers to do something special. Using the C<*> literal as an operand
creates a C<Whatever> object.

X<|Whatever-currying>
Much of C<*>'s charm comes from I<Whatever-currying>. When C<*> is used
in term position, that is, as an operand, in combination with most
operators, the compiler will transform the expression into a closure of
type L<WhateverCode|/type/WhateverCode>, which is actually a
L<C<Block>|/type/Block> that can be used wherever C<Callables> are
accepted.

    my $c = * + 2;          # same as   -> $x { $x + 2 };
    say $c(4);              # OUTPUT: «6␤»

Multiple C<*> in one expression generate closures with as many
arguments:

    my $c = * + *;          # same as   -> $x, $y { $x + $y }

Using C<*> in complex expressions will also generate closures:

    my $c = 4 * * + 5;      # same as   -> $x { 4 * $x + 5 }

Calling a method on C<*> also creates a closure:

=for code
<a b c>.map: *.uc;      # same as    <a b c>.map: -> $char { $char.uc }

As mentioned before, not all operators and syntactic constructs curry
C<*> (or C<Whatever>-stars) to C<WhateverCode>. In the following cases,
C<*> will remain a C<Whatever> object.

=begin table

    Exception           Example     What it does
    =========           =======     ============
    comma               1, *, 2     generates a List with a * element
    range operators     1 .. *      Range.new(:from(1), :to(*));
    series operator     1 ... *     infinite list
    assignment          $x = *      assign * to $x
    binding             $x := *     bind * to $x
    list repetition     1 xx *      generates an infinite list

=end table

The range operators are handled specially. They do not curry with
C<Whatever>-stars, but they do curry with C<WhateverCode>

    say (1..*).^name;       # OUTPUT: «Range␤»
    say ((1..*-1)).^name;   # OUTPUT: «WhateverCode␤»

This allows all these constructs to work:

=for code
.say for 1..*;          # infinite loop

and

    my @a = 1..4;
    say @a[0..*];           # OUTPUT: «(1 2 3 4)␤»
    say @a[0..*-2];         # OUTPUT: «(1 2 3)␤»

Because I<Whatever-currying> is a purely syntactic compiler transform,
you will get no runtime currying of stored C<Whatever>-stars into
C<WhateverCode>s.

=for code
my $x = *;
$x + 2;   # Not a closure, dies because it can't coerce $x to Numeric
CATCH { default { put .^name, ': ', .Str } };
# OUTPUT: «X::Multi::NoMatch: Cannot resolve caller Numeric(Whatever: );
# none of these signatures match:␤
# (Mu:U \v: *%_)»

The use cases for stored C<Whatever>-stars involve those curry-exception
cases mentioned above. For example, if you want an infinite series by
default.

=for code :preamble<sub potential-upper-limit {}; sub known-lower-limit {};>
my $max    = potential-upper-limit() // *;
my $series = known-lower-limit() ... $max;

A stored C<*> will also result in the generation of a C<WhateverCode> in
the specific case of smartmatch. Note that this is not actually the
stored C<*> which is being curried, but rather the C<*> on the left-hand
side.

=for code :preamble<sub find-constraint {};>
my $constraint           = find-constraint() // *;
my $maybe-always-matcher = * ~~ $constraint;

If this hypothetical C<find-constraint> were to have found no
constraint, C<$maybe-always-matcher> would evaluate to C<True> for
anything.

=for code :preamble<my $maybe-always-matcher>
$maybe-always-matcher(555);      # True
$maybe-always-matcher(Any);      # True

L<C<HyperWhatever>|/type/HyperWhatever>'s functionality is similar to
C<Whatever>, except it refers to multiple values, instead of a single
one.

=head1 Methods

=head2 method ACCEPTS

    multi method ACCEPTS(Whatever:D: Mu $other)
    multi method ACCEPTS(Whatever:U: Mu $other)

If the invocant is L«an instance|/language/classtut#index-entry-.DEFINITE»,
always returns C<True>. If the invocant is a type object, performs a typecheck.

    say 42 ~~ (*);       # OUTPUT: «True␤»
    say 42 ~~ Whatever;  # OUTPUT: «False␤»

=head2 method Capture

Defined as:

    method Capture()

Throws C<X::Cannot::Capture>.

=end pod

# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6
