NAME

Fry::Error - Redefines warn and die to trigger actions by error levels and tags.

DESCRIPTION

This is an error-handling module. independent of Fry::*, which offers the following:

        - Redefining die or warn to call die-like or warn-like subs ie Carp::croak and Carp::carp.
        - Errors are assigned levels, generally indicating severity of error.
        - Errors can have actions, the most obvious being logging an error, throwing a warning or
                dying. This means that logging can be done simply with &warn.
        - Errors can have tags associated with them which can affect actions or level settings.

Since this class overrides perl's die and warn, it affects all module in an application when used by any one module ie Fry::Shell. To fallback on perl's warn and die, set the global variables $DefaultDie or $DefaultWarn to 1. To provide logic for when and when not to fallback you can subclass this module and set the variables within &setDefaultDie or &setDefaultWarn.

A Fry::Error has the following attributes:

        Attributes with a '*' next to them are always defined.
        *id($): Unique id indicating order among other errors
        *caller(\@): Contains all of caller()'s data for the error's origin.
        *from($): Has value of either 'die' or 'warn' indicating from what error subroutine it was called.
        *level($): Number indicating error level. By default the values should go from 0-7 similar
                to the syslog command.
        *arg($): Contains arguments to be passed to a warn or die subroutine.
        tags(\@): Keywords or tags associated with error.

PUBLIC METHODS

        Class methods
                sigHandler(%attr): Passes its arguments directly to &new. This subroutine first defines an
                        error object, provides an early exit via global variables and then performs
                        actions for the error.
                new(%attributes): Creates an error object.
                parseDieArgs(@args): Parses arguments given to die() and returns attributes to construct an
                        error object via &new. By default, if the last argument is a hashref, it is
                        interpreted as parameters for the object

                        ie: die('really strange',{tags=>[qw/bizarre/]})

                parseWarnArgs(@args): Parses arguments given to warn() and returns attributes to construct an
                        error object via &new. Same default as parseDieArgs. In addition, multiple
                        arguments (up to three) are implicitly matched with the attributes: arg, level,tags.

                        ie: warn('yo',4,'interjection'); would create the following attribute hash
                        {qw/arg yo level 4 tags interjection/}

                setDefaultDie(@args): Set $DefaultDie for desired cases ie only certain modules.
                setDefaultWarn(@args): Set $DefaultWarn for desired cases.
                diesub(@arg): Calls a die-like sub with given arguments ie Carp::croak
                warnsub(@arg): Calls a warn-like sub with given arguments ie Carp::carp.

        Object methods
                setLevel(): Sets an object's level via more complex requirements ie other object
                        attributes such as tags or caller.
                takeAction(): Can take action on an error based on any attribute, the most likely
                        being 'level'. Aside from the obvious actions of calling a diesub or warnsub,
                        another action could be logging via logging modules such as Log::Dispatch or
                        Log::Log4perl or simplyt to a file. When subclassing this method, don't
                        forget calls to &warnsub and &diesub.

TODO

Implement more thorough logging capabilities.

AUTHOR

Me. Gabriel that is. I welcome feedback and bug reports to cldwalker AT chwhat DOT com . If you like using perl,linux,vim and databases to make your life easier (not lazier ;) check out my website at www.chwhat.com.

COPYRIGHT & LICENSE

Copyright (c) 2004, Gabriel Horner. All rights reserved.

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