NAME
    errors - Error Handling for Perl

STATUS
    This module is still under design. Don't use it in production yet.

SYNOPSIS
        use strict;
        use warnings;
        use errors;

        try {
            $cool = something();
            throw UncoolError("Something is not cool")
                if not $cool;
            assert($ok, "Everything is ok");
        }
        catch AssertionError with {
            my $e = shift;
            warn "$e";
        }
        catch UncoolError with {
            # $@ is the same as $_[0]
            warn "$@";
        }
        except {
            warn "Some other error: $@";
        }
        finally {
            cleanup();
        };

DESCRIPTION
    The "errors" module adds clean, simple, sane, flexible and usable error
    handling to Perl. The module does several things:

    First, "errors" exports a error handling syntax that is backwards
    compatible with Error.pm, but with a few improvements. Error.pm syntax
    is very well done; about as close to other modern language's exception
    handling as you can get using Pure Normal Perl.

    Second, all errors that are thrown are first class Perl objects. They
    all inherit from the "Error" class, which is provided by default. This
    allows you to manipulate errors in a consistent and intuitive way.

    Third, The "errors" module makes it trivial to define your own error
    classes, and encourages you to do so. Simply define a class that
    inherits from "Error" (or one of its subclasses).

    Fourth, "errors" turns plain (string based) system errors and other
    die/croak errors into specific Perl objects. It uses heuristics on the
    error string to determine which Error class to use, and defaults to the
    "RuntimeError" class.

    Fifth, "errors" provides dozens of predefined error classes that you can
    use or that get used automatically by the auto-objectification. These
    classes are in an inheritance hierarchy that should become standard for
    Perl.

    Lastly, "errors" is designed to play nice with all the modern Perl
    frameworks (like Moose) and the other popular error handling modules.

SIMPLE TO USE
    The main goal of "errors" is to encourage the widespread use of error
    handling in Perl. In other languages like Python, coining your own named
    error classes and using raise/except is as common as using if/else
    statements. Here's a Python example.

        class FooError(Exception):
            pass

        try:
            something()
        catch FooError as e:
            handle_error(e)

    Now you can do that in Perl:

        use errors;

        package FooError;
        use base 'Error';
        package MyModule;

        try {
            something();
        }
        catch FooError with {
            my $e = shift;
            handle_error($e);
        };

    As you can see, using "errors" is simple and unobtrusive. Why not start
    all your programs with:

        use strict;
        use errors;
        use warnings;

    Defining your own error classes is also trivial, and "errors" provides
    an even more concise way to do it:

        use errors -class => 'FooError';

    In the catch/with clause, you can also use $@ to access the current
    error object like this:

        catch FooError with {
            handle_error($@);
        };

USAGE
    There are a few different usages of "errors" that you should be aware
    of:

    use errors;
        This exports the "errors" syntax, and loads all the "errors"
        functionality.

    use errors -class => 'ClassName' [, -isa => 'BaseClass'];
        The "-class" directive gives you a way to define an error subclass
        at compile time, in one simple line of code. You can optionally
        specify the base class. The default base class is "Error".

        NOTE: This usage does not export the "errors" (try/catch) syntax.

    use errors -with_using;
        Unfortunately "Moose" and "errors" both export the "with"
        subroutine. If "errors" sees that "Moose" (or someone else) has
        already exported "with", it will export the "using" subroutine
        instead:

            use Moose;
            use errors;
            try {...} catch Error using {...};

        The "-with_using" directive tells "errors" to do this regardless.

SYNTAX
    The "errors" module introduces a number of keyword constructs that you
    can use to create and manage error objects.

    try { ... }
        Like an eval block. After the code is evaluated, the appropriate
        clauses (catch, except, otherwise, finally) are called.

    catch <error-selector> with { ... }
        This clause is invoked when an error happens in the "try" block, and
        the class of the error object satisfies the ErrorSelector specified.
        You may specify many "catch" clauses, to deal with different error
        situations.

        The <error-selector> can be any of the following forms:

            # Class matches a specific error class
            catch ErrorClass with { ... }
            # Class matches a specific regexp
            catch qr/.../ with { ... }
            # A subroutine returns a true value
            catch sub { ... } with { ... }
            # One of a list of error selectors
            catch selector1, selector2, selector3 with { ... }
            # All of an array list of selectors
            catch [ selector1, selector2, selector3 ] with { ... }

        NOTE: This is a major difference from Error.pm, which only allows a
        single class as a selector.

    except { ... }
        This clause is invoked when there is an error from the "try" block,
        but no "catch" clauses were invoked.

    otherwise { ... }
        This clause is invoked when no error occurs in the "try" block.

    finally { ... }
        This clause is always invoked as the final step in the "try"
        sequence, regardless of whatever things happen.

    throw("...");
        The throw keyword is not actually exported. It is a method call on
        the Error object. So you can use it indirectly or directly. These
        two calls are identical:

            throw MyError("Something is wrong");
            MyError->throw("Something is wrong");

        You can also use throw to reraise an error in a catch/except block,
        like this:

            $@->throw();

    assert($value, "assertion message");
        This function will throw an AssertionError error unless $value is
        true.

ERROR OBJECTS
    All errrors are Perl objects. They all have the 'Error' class as their
    topmost parent class. They all have the following methods and
    properties:

    throw Error($msg [, %properties]);
        This method throws a new instance of the error class. It is
        described more fully above.

    $@->text()
        The "text" method gets or sets the error message for the object.

    Stringification
        All Error objects turn into their "text" string value when used in
        string context.

    Numification
        All Error objects turn into a unique number when used in numeric
        context.

PREDEFINED CLASSES
    The "errors" module defines a number of error classes that it uses to
    cast errors into. You can also create error objects yourself using these
    classes. The classes are defined in a hierarchy:

        + Error
          + StandardError
            + ArithmeticError
              + DivideByZeroError
            + AssertionError
            + IOError
              + IOFileError
                + IOFileOpenError
            + NotImplementedError
            + SyntaxError
            + RuntimeError
          + UserError
            + user defined errors should inherit from this

    Some of these are obvious. Some deserve elaboration.

    AssertionError
        Indicates a failed "assert" call.

    SyntaxError
        Indicates a bad string eval.

    NotImplementedError
        You can throw this in a stub subroutine.

    RuntimeError
        Indicates an unknown system error.

    NOTE: These error classes are still being determined. This list is not
    yet complete. The current hierarchy was influenced from these sources.

        * http://search.cpan.org/perldoc?autodie#CATEGORIES
        * http://www.python.org/dev/peps/pep-0348/#new-hierarchy

FAQ
    Q: What is the difference between 'errors' and 'exceptions'?
    A: Four letters.
    Q: Is "errors" performant?
    A: Yes. Very. The module is small, simple, has no dependencies and no
    string evals.
    Q: Why another error/exception module?
    A: Because it has the perfect name.

ACKNOWLEDGEMENTS
    The original code and ideas for this module were taken from Error.pm.

AUTHOR
    Ingy dt Net <ingy@cpan.org>

COPYRIGHT
    Copyright (c) 2009. Ingy dt Net.

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

    See http://www.perl.com/perl/misc/Artistic.html

POD ERRORS
    Hey! The above document had some coding errors, which are explained
    below:

    Around line 302:
        You forgot a '=back' before '=head1'

        You forgot a '=back' before '=head1'

