=begin pod

=TITLE class Nil

=SUBTITLE Absence of a value

=comment TODO: This page seems to documents a previous design iteration of Nil,
               not the current one. Needs re-checking and rewriting. I only
               updated the subtitle for now.

    class Nil is Iterator { }

Represents an empty list in list context, and an undefined value in item
context.

C<Nil>, when assigned, evaporates into the type object of the type of the
container you assigned it into.

    my Int $x = 42;
    $x = Nil;
    $x.say;          #-> (Int)

It is for this reason that assigning an untyped container as C<Nil> will result
in an L<(Any)> object.

    my $x = Nil;
    $x.say;          #-> (Any)
    my Int $y = $x;  # error:  Type check failed in assignment to '$y'; expected 'Int' but got 'Any'

This is because an untyped container is C<Any> until proven otherwise, and
the C<Nil> evaporates.

If you are looking for a variable which transforms objects into type objects
when said variable appears on the RHS, you can type the container as C<Nil>.

    my Nil $x;
    my Str $s = $x;
    $s.say;          #-> (Str)

There is an important exception to this transforms-into-type-object rule:
assigning C<Nil> to a variable which has a default will restore that default.

    my Int $x is default(42) = -1;
    my $y = 1;
    for $x,$y -> $val is rw { $val = $reset unless $val > 0 }
    $x.say;          #-> 42

=head1 Methods

=head2 method gist

    method gist() returns Str:D

Returns C<"Nil">.

=head2 method Str

    method Str() returns Str:D

Returns the empty string.

=end pod

# vim: expandtab shiftwidth=4 ft=perl6
