Raku highlighting

class Nil is Cool { }

The value Nil may be used to fill a spot where a value would normally go, and in so doing, explicitly indicate that no value is present. It may also be used as a cheaper and less explosive alternative to a Failure. (In fact, class Failure is derived from Nil, so smartmatching Nil will also match Failure.)

The class Nil is the same exact thing as its only possible value, Nil.

Raku highlighting

say Nil === Nil.new;        # OUTPUT: «True␤»

Along with Failure, Nil and its subclasses may always be returned from a routine even when the routine specifies a particular return type. It may also be returned regardless of the definedness of the return type, however, Nil is considered undefined for all other purposes.

Raku highlighting

sub a( --> Int:D ) { return Nil }
a().say;                    # OUTPUT: «Nil␤»

Nil is what is returned from empty routines or closure, or routines that use a bare return statement.

Raku highlighting

sub a { }; a().say;         # OUTPUT: «Nil␤» 
sub b { return }; b().say;  # OUTPUT: «Nil␤» 
say (if 1 { });             # OUTPUT: «Nil␤» 
{ ; }().say;                # OUTPUT: «Nil␤» 
say EVAL "";                # OUTPUT: «Nil␤»

In a list, Nil takes the space of one value. Iterating Nil behaves like iteration of any non-iterable value, producing a sequence of one Nil. (When you need the other meaning, the special value Empty is available to take no spaces when inserted into list, and to return no values when iterated.)

Raku highlighting

(1, Nil, 3).elems.say;      # OUTPUT: «3␤» 
(for Nil { $_ }).raku.say;  # OUTPUT: «(Nil,)␤»

Any method call on Nil of a method that does not exist, and consequently, any subscripting operation, will succeed and return Nil.

Raku highlighting

say Nil.ITotallyJustMadeThisUp;  # OUTPUT: «Nil␤» 
say (Nil)[100];                  # OUTPUT: «Nil␤» 
say (Nil){100};                  # OUTPUT: «Nil␤»

When assigned to a container, the Nil value (but not any subclass of Nil) will attempt to revert the container to its default value; if no such default is declared, Raku assumes Any.

Since a hash assignment expects two elements, use Empty not Nil, e.g.

Raku highlighting

my %h = 'a'..'b' Z=> 1..*;
# stuff happens 
%h = Empty; # %h = Nil will generate an error

However, if the container type is constrained with :D, assigning Nil to it will immediately throw an exception. (In contrast, an instantiated Failure matches :D because it's a definite value, but will fail to match the actual nominal type unless it happens to be a parent class of Failure.) Native types can not have default values nor hold a type object. Assigning Nil to a native type container will fail with a runtime error.

Raku highlighting

my Int $x = 42;
$x = Nil;
$x.say;                     # OUTPUT: «(Int)␤» 
 
sub f( --> Int:D ){ Nil };  # this definedness constraint is ignored 
my Int:D $i = f;            # this definedness constraint is not ignored, so throws 
CATCH { default { put .^name, ': ', .Str } };
# OUTPUT: «X::TypeCheck::Assignment: Type check failed in assignment to $y; expected Int but got Any (Any)» 
 
sub g( --> Int:D ){ fail "oops" }; # this definedness constraint is ignored 
my Any:D $h = g;                   # failure object matches Any:D, so is assigned

but

Raku highlighting

my Int:D $j = g;
# It will throw both exceptions: 
# Earlier failure: 
#  oops 
#   in sub g at <unknown file> line 1 
#   in block <unit> at <unknown file> line 1 
# 
# Final error: 
#  Type check failed in assignment to $j; expected Int:D but got Failure (Failure.new(exception...) 
#   in block <unit> at <unknown file> line 1

Because an untyped variable is type Any, assigning a Nil to one will result in an (Any) type object.

Raku highlighting

my $x = Nil;
$x.say;          # OUTPUT: «(Any)␤» 
my Int $y = $x;  # will throw an exception 
CATCH { default { put .^name, ': ', .Str } };
# OUTPUT: «X::TypeCheck::Assignment: Type check failed in assignment to $y; expected Int but got Any (Any)␤»

If you are looking for a variable which transforms objects into type objects when said variable appears on the right-hand side, you can type the container as Nil.

Raku highlighting

my Nil $x;
my Str $s = $x;
$s.say;          # OUTPUT: «(Str)␤»

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

Raku highlighting

my Int $x is default(42) = -1;
my $y = 1;
for $x, $y -> $val is rw { $val = Nil unless $val > 0 }
$x.say;          # OUTPUT: «42␤»

Methods such as BIND-POS, ASSIGN-KEY, ASSIGN-POS will die; BIND-KEY will produce a failure with an X::Bind exception in it, and STORE will produce an X::Assignment::RO exception.