NAME

Error::Helper - Provides some easy error related methods.

VERSION

Version 2.1.0

SYNOPSIS

Below is a example script showing it's usage.

    use warnings;
    use strict;
    {
        package Foo;
        use base 'Error::Helper';
        sub new {
                my $arg = $_[1];
                my $self = {
                        perror        => undef,
                        error         => undef,
                        errorLine     => undef,
                        errorFilename => undef,
                        errorString   => "",
                        errorExtra    => {
                                all_errors_fatal => 0,
                                flags            => {
                                        1 => 'UndefArg',
                                        2 => 'test',
                                        3 => 'derp',
                                        4 => 'test2',
                                },
                                fatal_flags => {
                                        derp => 1,
                                },
                                perror_not_fatal => 0,
                        },
                };
                bless $self;
                # error if $arg is set to "test"
                if ( defined($arg)
                        && $arg eq "test" )
                {
                        $self->{perror}      = 1;
                        $self->{error}       = 2;
                        $self->{errorString} = 'A value of "test" has been set';
                        $self->warn;
                        return $self;
                }
                # error if $arg is set to "test2", error fatally
                if ( defined($arg)
                        && $arg eq "test" )
                {
                        $self->{perror}      = 1;
                        $self->{error}       = 4;
                        $self->{errorString} = 'A value of "test" has been set';
                        $self->warn;
                        return $self;
                }
                return $self;
        } ## end sub new
        sub foo {
                my $self = $_[0];
                my $a    = $_[1];
                if ( !$self->errorblank ) {
                        return undef;
                }
                if ( !defined($a) ) {
                        $self->{error}       = 1;
                        $self->{errorString} = 'No value specified';
                        $self->warn;
                        return undef;
                }
            # this will be fatal as it error flag derp is set to fatal
                if ( $a eq 'derp' ) {
                        $self->{error}       = 3;
                        $self->{errorString} = 'foo was called with a value of derp';
                        $self->warn;
                }
                return 1;
        } ## end sub foo
    }
    my $foo_obj;
    eval {
        $foo_obj = Foo->new( $ARGV[0] );
        # will never be evaulated as perrors are fatal
        if ( $foo_obj->error ) {
                warn( 'error:' . $foo_obj->error . ': ' . $foo_obj->errorString );
                exit $foo_obj->error;
        }
    };
    if ($@) {
        print 'Error: ' . $Error::Helper::error .
            "\nError String: " . $Error::Helper::errorString .
            "\nError Flag: " . $Error::Helper::errorFlag .
            "\nError File: " . $Error::Helper::errorFilename .
            "\nError Line: " . $Error::Helper::errorLine .
            "\nError Sub: " . $Error::Helper::errorSub .
            "\nError Sub Short: " . $Error::Helper::errorSubShort .
            "\nError Package: " . $Error::Helper::errorPackage .
            "\nError PackageShort: " . $Error::Helper::errorPackageShort . "\n";
        exit $Error::Helper::error;
    }
    # catches fatal errors
    eval{
        $foo_obj->foo( $ARGV[1] );
    };
    if ($@) {
        # do something...
        warn( '$foo_obj->foo( $ARGV[1] ) errored.... '.$@);
        if ($foo_obj->errorFlag eq 'derp') {
                warn('error flag derp found... calling again with a value of default');
                $foo_obj->foo( 'default' );
        }
    } elsif ($foo_obj->error) {
        # do something...
        warn( '$foo_obj->foo( $ARGV[1] ) errored');
    }

There are five required variables in the blessed hash object.

    - $self->{error} :: This contains the current error code.
        - Type :: int or undef
    - $self->{errorFilename} :: File from which $self->warn was called.
        - Type :: string or undef
    - $self->{errorLine} :: Line from which $self->warn was called.
        - Type :: int or undef
    - $self->{errorString} :: This contains a description of the current error.
        - Type :: string or undef
    - $self->{perror} :: This is set to true is a permanent error is present.
            If note, it needs set to false.
        - Type :: Perl boolean

The following are optional.

    - $self->{errorExtra} :: This is a hash reserved for any additional Error::Helper items.
    - $self->{errorExtra}{all_errors_fatal} :: If true, this will die when $self->warn is called instead of
            printing the error to STDERR. This is for if you want to use it eval for capturing errors and this
            module more for handling grabbing error specifics, such as dieing and additional code based on the
            return of $self->errorFlag.
        - Type :: Perl boolean
        - Default :: undef
    - $self->{errorExtra}{fatal_errors} :: This is a hash in which the keys are errors codes that are fatal. When
            $self->warn is called it will check if the error code is fatal or not. $self->{errorExtra}{fatal_errors}{33}=>1
            would be fatal, but $self->{errorExtra}{fatal_errors}{33}=>0 would now.
    - $self->{errorExtra}{flags} :: This hash contains error integer to flag mapping. The
            keys are the error integer and the value is the flag. For any unmatched error
            integers, 'other' is returned.
    - $self->{errorExtra}{fatal_flags} :: This is a hash in which the keys are error flags that are fatal. When
            $self->warn is called it will check if the flag for the error code is fatal or not. For the flag foo
            $self->{errorExtra}{fatal_flags}{foo}=>1 would be fatal, but
            $self->{errorExtra}{fatal_flags}{foo}=>0 would now.
    - $self->{errorExtra}{perror_not_fatal} :: Controls if $self->{perror} is fatal or not.
        - Type :: Perl boolean
        - Default :: undef

This module also sets several other variables as well for when something like a new method is called and dies, before something blessed can be returned. These allow examining the the error that resulted in it dieing.

The following are mapped to the the ones above.

    $Error::Helper::perror
    $Error::Helper::error
    $Error::Helper::errorString
    $Error::Helper::errorFlag
    $Error::Helper::errorFilename
    $Error::Helper::errorLine

The following don't have mappings above.

    - $Error::Helper::errorSub :: The sub that warn was called from.
    - $Error::Helper::errorSubShort :: Same as errorSub, but everything prior to the subname is
            removed. So Foo::bar would become bar.
    - $Error::Helper::errorPackage :: The package from which warn was called from.
    - $Error::Helper::errorPackageShort :: Saome as package, but everthing prior to the last item
            in the name space is removed. So Foo::Foo::Bar would just become Bar.

METHODS

    if($self->error){
        # do something
    }

        $self->{error}         = undef;
        $self->{errorFilename} = undef;
        $self->{errorLine}     = undef;
        $self->{errorString}   = "";

    if($self->error){
        print 'error happened in '.$self->errorFilename."\n";
    }

    if ( $self->errorFlag ){
        if ( $self->errorFlag eq 'foo' ){
            # do something
        }else{
            die('error flag '.$self->errorFlag.' can not be handled');
        }
    }

    if($self->error){
        print 'error happened at line '.$self->errorLine."\n";
    }

    if($self->error){
        warn('error: '.$self->error.":".$self->errorString);
    }

    if($self->perror){
                warn('A permanent error is set');
    }

    $self->warn;

    $self->warnString('some error');

ERROR FLAGS

Error flags are meant to be short non-spaced strings that are easier to remember than a specific error integer.

'other' is the generic error flag for when one is not defined.

An error flag should never evaluate to false if an error is present.

AUTHOR

Zane C. Bowers-Hadley, "<vvelox at vvelox.net>"

BUGS

Please report any bugs or feature requests to "bug-error-helper at rt.cpan.org", or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Error-Helper>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Error::Helper

You can also look for information at:

• RT: CPAN's request tracker

  <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Error-Helper>

• Search CPAN

  <https://metacpan.org/dist/Error-Helper>

LICENSE AND COPYRIGHT

Copyright 2023 Zane C. Bowers-Hadley.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.