O, wise ones!

I have worked long and hard (well, for about 3 hours) and climbed high mountains (this technopark sits atop a little hill) to produce yet another useless module: Error::Layout. I would like to hear some feedback on the API given below. I would also appreciate pointers on the right way to do this sort of thing, probably mentioning Exception::Class and general OO advice. I will put those pointers in a DISCLAIMER/CAVEATS section, which could make the module useful after all.

NAME

Error::Layout - Helps manage error handlers in your application

VERSION

Version 0.01_01

SYNOPSIS

    package MyApp::Err;
    use Error::Layout;

    package MyApp::Foo;
    use MyApp::Err;  # exports handle_err()

    if ($error_condition) {
        handle_err();
    }

DESCRIPTION

This module tries to help you organize your error handling code and make your main logic code look less cluttered.

You use Error::Layout in a central error-handling module of your application:

    package MyApp::Err;
    use Error::Layout;
    sub handle_err { ... } # Optional default handler

Then, in any ordinary module of your application where error-handling code seems to crowd out the main logic, you can use MyApp::Err, the error-handling module you created:

    package MyApp::Foo;
    use MyApp::Err;

    eval {
        # Risky business
    };
    if ($@) {
        handle_err();
    }

in which case Error::Layout will try to find a sub named handle_err() in MyApp::Foo::Err and MyApp::Err, in that order.

    package MyApp::Foo::Err;
    sub handle_err {
        ...
    }

If you want to pass arguments to your handler, you can use an anonymous hash:

    handle_err({ FOO => $foo });

If it is interested in the arguments, your handler should start by unloading the arguments hashref:

    sub handle_err {
        my (args_href) = @_;
        ...
    }

Your handler will always be passed an args_href, even if you did not call it with one, and it will always have $@, the eval error, saved as the value for the key '_EVAL_ERR'

    sub handle_err {
        my (args_href) = @_;
        my $eval_err = $args_href->{_EVAL_ERR};
        ...
    }

If you have multiple handlers in one module, or just want to put the handler in a module that is named in a way that reflects its job, you can pass a module identifier (the name of the handler's separate module) to handle_err as the first argument:

    package MyApp::Foo;
    use MyApp::Err;  # exports handle_err()

    if ($error_condition_1) {
        handle_err('Condition_One');
    }
    ...
    if ($error_condition_2) {
        handle_err('Condition_Two', {FOO => $foo});
    }

For the call handle_err('Condition_One'), Error::Layout will look for an implementation of handle_err in MyApp::Foo::Err::Condition_One and MyApp::Err::Condition_One, in that order. Any parameters hashref should come after the identifier, as shown in the 'Condition Two' example above.

If you want your error handlers to be named something other than 'handle_err', you should pass your desired name to Error::Layout:

    use Error::Layout 'myapp_err';

Then, you should replace 'handle_err' with 'myapp_err' in all the examples above.