=begin pod

=TITLE class Exception

    class Exception { ... }

All exceptions that are placed into the C<$!> variable (or into C<$_>
in C<CATCH> blocks) inherit from C<Exception>. When you call C<die>
or C<fail> with a non-Exception argument, it is wrapped into an
C<X::AdHoc> object, which also inherits from C<Exception>.

User-defined exception classes should inherit from C<Exception> too, and
define at least a method C<message>.

    class X::YourApp::SomeError is Exception {
        method message() {
            "A YourApp-Specific error occurred: out of coffee!";
        }
    }

=head1 Methods

=head2 message

    method message(Exception:D:) returns 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.

=head2 backtrace

    method backtrace(Exception:D:) returns Backtrace:D

Returns the backtrace associated with the exception. Only makes sense
on exceptions that have been thrown at least once.

=head2 throw

    method throw(Exception:D:)

Throws the exception.

=head2 rethrow

    method rethrow(Exception:D:)

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

=head2 fail

    method fail(Exception:D:)

Same as C<fail $exception>; i.e., it exits the calling C<Routine>
and returns the exception wrapped in a L<Failure> object.

=head2 gist

    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.

=end pod