<commit_before>=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

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

    method throw(Exception:D:)

Throws the exception.

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

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

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

    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.

=head2 multi sub die

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

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

=head2 multi sub warn

    multi sub 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<commit_msg>Correct headings to allow die and warn to show up in search<commit_after>=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

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

    method throw(Exception:D:)

Throws the exception.

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

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

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

    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.

=head2 sub die

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

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

=head2 sub warn

    multi sub 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
{'fraction_non_alphanumeric': 0.07534913933095161, 'fraction_numerical': 0.0035725885027606367, 'mean_word_length': 3.9036624203821657, 'pattern_counts': {'":': 0, '<': 55, '<?xml version=': 0, '>': 55, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7020944', 'n_tokens_mistral': 1768, 'n_tokens_neox': 1698, 'n_words': 820}