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

=TITLE class X::NYI

=SUBTITLE Error due to use of an unimplemented feature

    class X::NYI is Exception { }

Error class for unimplemented features. I<NYI> stands for I<Not Yet
Implemented>.

If a Raku compiler is not yet feature complete, it may throw an C<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 C<X::NYI> class for compatibility reasons.

A typical error message is

=for code :lang<text>
HyperWhatever is not yet implemented. Sorry.

=head1 Methods

=head2 method new

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

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

=begin code
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");
=end code

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

=begin code
# 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
=end code

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

=head2 method feature

Returns a C<Str> describing the missing feature.

=head2 method did-you-mean

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

=head2 method workaround

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

=head2 method message

Returns the message including the above properties.

=end pod
