=begin pod

=TITLE class Exception

=SUBTITLE Anomalous event capable of interrupting normal control-flow

    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 method message

Defined as:

    method message(Exception:D:) returns Str:D

Usage:

    EXCEPTION.message

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 method backtrace

Defined as:

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

Usage:

    EXCEPTION.backtrace

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

=head2 method throw

Defined as:

    method throw(Exception:D:)

Usage:

    EXCEPTION.throw

Throws the exception.

=head2 method resume

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

Defined as:

    method resume(Exception:D:)

Usage:

    CATCH { default { .resume } }

=head2 method rethrow

Defined as:

    method rethrow(Exception:D:)

Usage:

    EXCEPTION.rethrow

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 method fail

Defined as:

    sub    fail(*@text)
    sub    fail(Exception $e)
    method fail(Exception:D $e:)

Usage:

    fail(TEXT)
    fail(EXCEPTION)
    EXCEPTION.fail

Exits the calling C<Routine> and returns a L<Failure> object wrapping the
exception C<$e> - or, for the C<*@text> form, an L<X::AdHoc> exception
constructed from the concatenation of C<@text>.

    sub copy-directory-tree ($dir) {
        fail "$dir is not a directory" if !$dir.IO.d;
        ...
    }

=head2 method gist

Defined as:

    multi method gist(Exception:D:)

Usage:

    EXCEPTION.gist

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

=head2 sub die

Defined as:

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

Usage:

    die(MESSAGE)
    die(EXCEPTION)
    EXCEPTION.die

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

=head2 sub warn

Defined as:

    multi sub warn(*@message)

Usage:

    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 C<$*ERR>. After printing
the warning, the exception is resumed where it was thrown.  To override this
behavior, catch the exception in a C<CONTROL> block.  A C<quietly {...}>
block is the opposite of a C<try {...}> block in that it will suppress any
warnings but pass fatal exceptions through.

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

=end pod

# vim: expandtab shiftwidth=4 ft=perl6
