=pod

=for comment
DO NOT EDIT. This Pod was generated by Swim.
See http://github.com/ingydotnet/swim-pm#readme

=encoding utf8

=head1 errors-Design

The Thought Behind errors.pm

=head1 Goals

The primary goal behind the C<errors> module is to finally add error handling
to Perl that people actually want to use.

For that to happen it needs to be simple yet full featured. It needs to be
sexy, but also to Just Work.

In my opinion, the best part of the module is the name. You can simply say:

    use errors;

And all the right stuff should happen.

This will hopefully lead to the following prelude in Perl programs and
modules:

    use strict;
    use warnings;
    use errors;

=head1 Moving Parts

The module is designed to do 3 primary things when you use it.

=over

=item * Export a try/catch interface.

=item * Provide a base class for error objects.

=item * Provide a hierarchy of standard/system error classes.

=back

The first two things are done by a lot of modules. The third, not so much.

Under the hood, errors.pm coerces errors into the appropriate objects, and
tries to play nice (be interoperable) with the other error modules.

=head1 Other Modules

C<errors> should play nice with the following modules:

=over

=item * Error.pm

=item * Exception-Class

=item * autodie

=back

=head1 Python Exceptions

I first got interested in doing an exception module, after porting lots of
code back and forth between Python and Perl. Python code tends to use
exceptions a lot, so they probably got it pretty much right.

Here's some basic Python code:

    class FooError(Exception):
        pass
    class FooFooError(FooError):
        pass
    class BarError(Exception):
        pass

    try:
        something()
    except FooError, BarError as e:
        handle_foo_or_bar(e)
    except RuntimeError as e:
        handle_runtime_error(e)
    except:
        handle_other_errors(e)
    else:
        do_something_if_no_error()
    finally:
        do_this_last_regardless()

Notable things:

Python encourages you to make your own error subclasses, and catch them
specifically by name.

Python gives you an C<else> clause. Evidently, tryI<else is an idiom just
like if>else.

An except (think catch) clause lets you name one or many classes to match on.
It also allows no selection classes, which means match on any.

The C<errors> module will default to Python semantics as much as reasonable.

=head1 Error.pm

At first glance Error.pm seems almost equivalent to the Python way, just with
slightly differing names:

    - The default class is Error, not Exception.
    - Use throw instead of raise
    - Use 'catch Name with' instead of 'except Name:'
    - Use except as default (like catch with no named class selector)
    - Use otherwise instead of else (because else is Perl keyword)

It turns out this is not quite right. In Error.pm the semantics of 'except'
and 'otherwise' are quite different; 'otherwise' is like python except,
'except' has just plain weird semantics, and there is no analog for the
Python 'else'.

Therefore, while the C<errors> module probably needs to coexist and be aware
of Error.pm, it will not attempt to follow its exact syntax and semantics.

=head1 Exceptions.pm

There is a module called Exceptions to which the C<Exception> (non plural)
is indexed. It is only at version 0.01 and has no documentation. It appears
to be dead.

This is fortunate because we can use 'Exception' as our base class for all
errors. Using 'Error' would be a mistake because we could not interoperate
with code that uses Error.pm.

Python also uses 'Exception' as its root base class. Python also has the
convention that subclasses end with the word 'Error'. Like this:

    # Define a subclass of Exception called MyError
    class MyError(Exception):
        pass

=head1 Nesting

It seems like the following syntax fails for all the try/catch modules
I've tried:

    try { try {...} catch ... {...}; } catch ... {...};

In other words, you can't try inside a try. This works fine in Python and
should be made to work in Perl.

=head1 WORK IN PROGRESS

... more to come ...

I'm still working on getting the right design for this module, so that it can
serve the Perl community well, and evolve with it.

=head1 TO DO

Things I need to do:

=over

=item * Work with the authors/maintainers of Error.pm and autodie

=item * Look into how Perl 6 handles errors

=back

=head1 Author

Ingy döt Net <ingy@cpan.org>

=head1 Copyright

Copyright 2009-2014. Ingy döt Net.

This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.

See L<http://www.perl.com/perl/misc/Artistic.html>

=cut
