class X::NYI is Exception { }

Error class for unimplemented features. NYI stands for Not Yet Implemented.

If a Raku compiler is not yet feature complete, it may throw an X::NYI exception when a program uses a feature that it can detect and is somehow specified is not yet implemented.

A full-featured Raku compiler must not throw such exceptions, but still provide the X::NYI class for compatibility reasons.

A typical error message is

HyperWhatever is not yet implemented. Sorry.

Methods §

method new §

method new( :$feature, :$did-you-mean, :$workaround)

This is the default constructor for X:NYI which can take three parameters with obvious meanings.

class Nothing {
    method ventured( $sub, **@args) {
        X::NYI.new( feature => &?ROUTINE.name,
                    did-you-mean => "gained",
                    workaround => "Implement it yourself" ).throw;
    }
}
 
my $nothing = Nothing.new;
$nothing.ventured("Nothing", "Gained");

In this case, we are throwing an exception that indicates that the ventured routine has not been implemented; we use the generic &?ROUTINE.name to not tie the exception to the method name in case it is changed later on. This code effectively throws this exception

# OUTPUT: 
# ventured not yet implemented. Sorry. 
# Did you mean: gained? 
# Workaround: Implement it yourself 
#   in method ventured at NYI.p6 line 6 
#   in block <unit> at NYI.p6 line 14 

Using the exception properties, it composes the message that we see there.

method feature §

Returns a Str describing the missing feature.

method did-you-mean §

Returns a Str indicating the optional feature that is already implemented.

method workaround §

It helpfully shows a possible workaround for the missing feature, if it's been declared.

method message §

Returns the message including the above properties.

Type Graph §

Routines supplied by class Exception §

X::NYI inherits from class Exception, which provides the following routines:

(Exception) method message §

Defined as:

method message(Exception:D: --> Str:D)

This is a stub that must be overwritten by subclasses, and should return the exception message.

Special care should be taken that this method does not produce an exception itself.

try die "Something bad happened";
if ($!) {
    say $!.message; # OUTPUT: «Something bad happened.␤» 
}

(Exception) method backtrace §

Defined as:

method backtrace(Exception:D:)

Returns the backtrace associated with the exception in a Backtrace object or an empty string if there is none. Only makes sense on exceptions that have been thrown at least once.

try die "Something bad happened";
with $! { .backtrace.print ; }

(Exception) method throw §

Defined as:

method throw(Exception:D:)

Throws the exception.

my $exception = X::AdHoc.new;    # Totally fine 
try $exception.throw;            # Throws 
if ($!) { #`( some handling ) }; # Suppress the exception

(Exception) method resume §

Defined as:

method resume(Exception:D:)

Resumes control flow where .throw left it when handled in a CATCH block.

# For example, resume control flow for any exception 
CATCH { default { .resume } }

(Exception) method rethrow §

Defined as:

method rethrow(Exception:D:)

Rethrows an exception that has already been thrown at least once. This is different from throw in that it preserves the original backtrace.

sub f() { die 'Bad' };
sub g() { f; CATCH { default { .rethrow } } };
g;
CATCH { default { say .backtrace.full } };

(Exception) routine fail §

Defined as:

multi sub    fail(Exception $e)
method       fail(Exception:D:)

Exits the calling Routine and returns a Failure object wrapping the exception.

# A custom exception defined 
class ForbiddenWord is Exception {
    has Str $.word;
    method message { "This word is forbidden: «$!word»" }
}
 
sub say-word ( $word ) {
    ForbiddenWord.new(:word($word)).fail if $word eq 'foo';
    $word.say;
}
 
my $result = say-word("foo");
say $result.exception;

The routine form works in the same way, with an alternative syntax: fail ForbiddenWord.new(:word($word)).

(Exception) method gist §

Defined as:

multi method gist(Exception:D:)

Returns whatever the exception printer should produce for this exception. The default implementation returns message and backtrace separated by a newline.

my $e = X::AdHoc.new(payload => "This exception is pretty bad");
try $e.throw;
if ($!) { say $!.gist; };
# OUTPUT: «This exception is pretty bad 
#   in block <unit> at <unknown file> line 1␤»

(Exception) routine die §

Defined as:

multi sub die()
multi sub die(*@message)
multi sub die(Exception:D $e)
method    die(Exception:D:)

Throws a fatal Exception. The default exception handler prints each element of the list to $*ERR (STDERR).

die "Important reason";

If the subroutine form is called without arguments, the value of $! variable is checked. If it is set to a .DEFINITE value, its value will be used as the Exception to throw if it's of type Exception, otherwise, it will be used as payload of X::AdHoc exception. If $! is not .DEFINITE, X::AdHoc with string "Died" as payload will be thrown.

die will print by default the line number where it happens

die "Dead";
# OUTPUT: «(exit code 1) Dead␤ 
# in block <unit> at /tmp/dead.p6 line 1␤␤» 

However, that default behavior is governed at the Exception level and thus can be changed to anything we want by capturing the exception using CATCH. This can be used, for instance, to suppress line numbers.

CATCH {
  default {
    .payload.say
  }
};
die "Dead" # OUTPUT: «Dead␤» 

(Exception) sub warn §

Defined as:

multi sub warn(*@message)

Throws a resumable warning exception, which is considered a control exception, and hence is invisible to most normal exception handlers. The outermost control handler will print the warning to $*ERR. After printing the warning, the exception is resumed where it was thrown. To override this behavior, catch the exception in a CONTROL block. A quietly {...} block is the opposite of a try {...} block in that it will suppress any warnings but pass fatal exceptions through.

To simply print to $*ERR, please use note instead. warn should be reserved for use in threatening situations when you don't quite want to throw an exception.

warn "Warning message";