=begin pod

=TITLE class Failure

=SUBTITLE Delayed exception

    class Failure { }

A C<Failure> is a I<soft> or I<unthrown> exception, usually generated by
calling C<&fail>. It acts as a wrapper around an L<Exception> object.

Sink (void) context causes a Failure to throw, i.e. turn into a normal
exception.

Checking a Failure for truth (with the C<Bool> method) or definedness (with
the C<defined> method) marks the failure as handled, and causes it not to
throw in sink context anymore.

You can call the C<handled> method to check if a failure has been handled.

Calling methods on unhandled failures propagates the failure. The
specification says the result is another C<Failure>, in Rakudo it causes the
failure to throw.

=head1 Methods

=head2 method handled

Defined as:

    method handled(Failure:D:) returns Bool:D

Usage:

    FAILURE.handled

Returns C<True> for handled failures, C<False> otherwise.

=head2 method exception

Defined as:

    method exception(Failure:D:) returns Exception

Usage:

    FAILURE.exception

Returns the L<Exception> object that the failure wraps.

=head2 method Bool

Defined as:

    multi method Bool(Failure:D:) returns Bool:D

Usage:

    FAILURE.Bool

Returns C<False>, and marks the failure as handled.

=head2 method defined

Defined as:

    multi method defined(Failure:D:) returns Bool:D

Usage:

    FAILURE.defined

Returns C<False> (failures are officially undefined), and marks
the failure as handled.

=end pod
