=begin pod

=TITLE class Failure

    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 handled

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

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

=head2 exception

    method handled(Failure:D:) returns Exception

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

=head2 Bool

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

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

=head2 defined

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

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

=end pod