<commit_before>=begin pod

=TITLE Exceptions

=SUBTITLE Using exceptions in Perl 6

Exceptions in Perl 6 are a special kind of object used to signify when
something has gone wrong, for instance, unexpected data was received, a
network connection is no longer available, or a file is missing which was
expected to exist.

All built-in exceptions inherit from L<Exception>, which provides some basic
behavior, such as storing a backtrace and providing an interface for the
backtrace printer.

=head2 Ad-hoc exceptions

Ad-hoc exceptions work just like in traditional Perl 5, one can simply use
C<die> with a message as to what went wrong:

    die "oops, something went wrong";
    #!> oops, something went wrong in block <unit> at /tmp/0IeSX_XSWO:1

=head2 Typed exceptions

Typed exceptions provide more information about the kind of error that
occurred within the exception object itself.  For instance, if while
executing C<.zombie copy> on an object the path C<foo/bar> is unavailable
(and was expected to be available), then one could raise an
L<X::IO::DoesNotExist> exception like so:

    die X::IO::DoesNotExist.new(:path("foo/bar"), :trying("zombie copy"))
    #!> Failed to find 'foo/bar' while trying to do '.zombie copy'
    #!> in block <unit> at /tmp/BgTfZOotgc:1

Note how the object has provided the backtrace with information about what
went wrong so that hopefully the user of the code can find and correct the
issue more easily.

=head2 Catching exceptions

It is possible to handle exceptional circumstances by supplying a C<CATCH> block:

    die X::IO::DoesNotExist.new(:path("foo/bar"), :trying("zombie copy"));
    CATCH {
        when X::IO { say "some kind of IO exception was caught!" }
    }
    #!> some kind of IO exception was caught!

Here, we are saying that if any exception of type C<X::IO> occurs, then the
message C<some kind of IO exception was caught!> will be displayed.

A C<CATCH> block uses smart matching similarly to how C<given/when> smart
matches on options, thus it is possible to catch various categories of
exceptions and handle them appropriately inside a C<when> block.

=head2 Throwing exceptions

One can also explicitly throw exceptions via the C<.throw> method on an
C<Exception> object.

This example throws an C<AdHoc> exception, catching it and allowing the code
to continue from the point of the exception.

    {
        X::AdHoc.new(:payload<foo>).throw;
        "OHAI".say;
        CATCH {
            when X::AdHoc { $_.resume }
        }
    }
    "OBAI".say;
    #-> OHAI
    #-> OBAI
<commit_msg>Fix grammar<commit_after>=begin pod

=TITLE Exceptions

=SUBTITLE Using exceptions in Perl 6

Exceptions in Perl 6 are a special kind of object used to signify when
something has gone wrong, for instance, unexpected data was received, a
network connection is no longer available, or a file is missing which was
expected to exist.

All built-in exceptions inherit from L<Exception>, which provides some basic
behavior, such as storing a backtrace and providing an interface for the
backtrace printer.

=head2 Ad-hoc exceptions

Ad-hoc exceptions work just like in traditional Perl 5, one can simply use
C<die> with a message as to what went wrong:

    die "oops, something went wrong";
    #!> oops, something went wrong in block <unit> at /tmp/0IeSX_XSWO:1

=head2 Typed exceptions

Typed exceptions provide more information about the kind of error that
occurred within the exception object itself.  For instance, if while
executing C<.zombie copy> on an object the path C<foo/bar> is unavailable
(and was expected to be available), then one could raise an
L<X::IO::DoesNotExist> exception like so:

    die X::IO::DoesNotExist.new(:path("foo/bar"), :trying("zombie copy"))
    #!> Failed to find 'foo/bar' while trying to do '.zombie copy'
    #!> in block <unit> at /tmp/BgTfZOotgc:1

Note how the object has provided the backtrace with information about what
went wrong so that hopefully the user of the code can find and correct the
issue more easily.

=head2 Catching exceptions

It is possible to handle exceptional circumstances by supplying a C<CATCH> block:

    die X::IO::DoesNotExist.new(:path("foo/bar"), :trying("zombie copy"));
    CATCH {
        when X::IO { say "some kind of IO exception was caught!" }
    }
    #!> some kind of IO exception was caught!

Here, we are saying that if any exception of type C<X::IO> occurs, then the
message C<some kind of IO exception was caught!> will be displayed.

A C<CATCH> block uses smart matching similarly to how C<given/when> smart
matches on options, thus it is possible to catch various categories of
exceptions and handle them appropriately inside a C<when> block.

=head2 Throwing exceptions

One can also explicitly throw exceptions via the C<.throw> method on an
C<Exception> object.

This example throws an C<AdHoc> exception, catches it and allows the code
to continue from the point of the exception.

    {
        X::AdHoc.new(:payload<foo>).throw;
        "OHAI".say;
        CATCH {
            when X::AdHoc { $_.resume }
        }
    }
    "OBAI".say;
    #-> OHAI
    #-> OBAI

{'fraction_non_alphanumeric': 0.07579605391678063, 'fraction_numerical': 0.003907013088493847, 'mean_word_length': 3.8210922787193975, 'pattern_counts': {'":': 0, '<': 37, '<?xml version=': 0, '>': 49, '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': '5871078', 'n_tokens_mistral': 1502, 'n_tokens_neox': 1455, 'n_words': 707}