/ 
Module-Generic-v0.37.3
River stage two • 17 direct dependents • 20 total dependents
/ Module::Generic::Exception

NAME

Module::Generic::Exception - Generic Module Exception Class

SYNOPSIS

my $ex = Module::Generic::Exception->new({
    code => 404,
    type => $error_type,
    file => '/home/joe/some/lib/My/Module.pm',
    lang => 'en_GB',
    # or alternatively
    # locale => 'en_GB',
    line => 120,
    message => 'Invalid property provided',
    package => 'My::Module',
    subroutine => 'customer_info',
    # Some optional discretionary metadata hash reference
    cause =>
        {
        object => $some_object,
        payload => $raw_data,
        },
});

or, providing a list of string that will be concatenated:

my $ex = Module::Generic::Exception->new( "Some error", "has occurred:", $details );

or, re-using an exception object:

my $ex = Module::Generic::Exception->new( $other_exception_object );

print( "Error stack trace: ", $ex->stack_trace, "\n" );
# or
$object->customer_orders || die( "Error in file ", $object->error->file, " at line ", $object->error->line, "\n" );
# or simply:
$object->customer_orders || die( "Error: ", $object->error, "\n" );
$ex->cause->payload;

VERSION

v1.3.1

DESCRIPTION

This is a simple and straightforward exception class you can use or inherit from. The error object can be stringified or compared.

When stringified, it provides the error message along with precise information about where the error occurred and a stack trace.

Module::Generic::Exception objects are created by "error" in Module::Generic method.

METHODS

new

It takes either an Module::Generic::Exception object or an hash reference of properties, or a list of arguments that will be concatanated to form the error message. The list of arguments can contain code reference such as reference to sub routines, who will be called and their returned value added to the error message string. For example :

my $ex = Module::Generic::Exception->new( "Invalid property. Value recieved are: ", sub{ Dumper( $hash ) } );

# or

my $ex = Module::Generic::Exception->new( $other_exception_object_for_reuse );
# This will the object property

# or

my #ex = Module::Generic::Exception->new({
    message => "Invalid property.",
    code => 404,
    type => 'customer',
})

Possible properties that can be specified are :

  • cause

    An optional and arbitrary hash reference of metadata that serve to provide more context on the error.

  • code

    An error code

  • file

    The location where the error occurred. This is populated using the "filename" in Devel::StackTrace

  • lang

    An iso 639 language code that represents the language the error message is in.

    You can use locale alternatively. See the "lang" method below for more information.

  • line

    The line number in the file where the error occurred. This is populated using the "line" in Devel::StackTrace

  • locale

    An iso 639 language code that represents the language the error message is in.

    You can use lang alternatively. See the "lang" method below for more information.

  • message

    The error message. It can be provided as a list of arguments that will be concatenated, or as the message property in an hash reference, or copied from another exception object passed as the sole argument.

  • object

    When this is set, such as when another Module::Generic::Exception object is provided as unique argument, then the properties message, code, type, retry_after are copied from it in the new exception object.

  • package

    The package name where the error occurred. This is populated using the "package" in Devel::StackTrace

  • retry_after

    An optional value to indicate in seconds how long to wait to retry.

  • skip_frames

    This is used as a parameter to Devel::StackTrace upon instantiation to instruct how many it should skip to start creating the stack trace.

  • subroutine

    The name of the sub routine from which this was called. This is populated using the "subroutine" in Devel::StackTrace

  • type

    An optional error type

It returns the exception object.

as_string

This returns a string representation of the Exception such as :

Invalid property within package My::Module at line 120 in file /home/john/lib/My/Module.pm
    # then some strack trace here

caught

use Nice::Try;
try
{
    # An error made with Module::Generic::Exception
    die( $object->error );
}
catch( $e )
{
    # If this error is one of ours
    if( Module::Generic::Exception->caught( $e ) )
    {
        # Do something about it
    }
}

But Nice::Try let's you do this:

try
{
    die( $object->error );
}
catch( Module::Generic::Exception $e )
{
    # Do something about it
}

cause

my $ex = Module::Generic::Exception->new({
    code => 401,
    message => 'Not authorised',
    cause => {
        id => 1234,
    },
});
say $ex->cause->id; # 1234

Sets or gets an hash reference of metadata that serve to provide more context on the error.

This returns an hash object.

code

Set or get the error code. It returns the current value.

file

Set or get the file path where the error originated. It returns the current value.

lang

Set or get the language iso 639 code representing the language the error message is in.

If the error message is a string object that has a locale or lang object, it will be used to set this lang value.

This is the case if you use the module Text::PO::Gettext to implement GNU PO localisation framework. For example:

use Text::PO::Gettext;
my $po = Text::PO::Gettext->new || die( Text::PO::Gettext->error, "\n" );
my $po = Text::PO::Gettext->new({
    category => 'LC_MESSAGES',
    debug    => 3,
    domain   => "com.example.api",
    locale   => 'ja-JP',
    path     => "/home/joe/locale",
    use_json => 1,
}) || die( Text::PO::Gettext->error, "\n" );

my $message = $po->gettext( "Something wrong happened." );

Then, $message would be a Text::PO::String

See "gettext" in Text::PO::Gettext for more information.

line

Set or get the line where the error originated. It returns the current value.

locale

This is an alias for "lang"

message

Set or get the error message. It returns the current value.

It takes a string, or a list of strings which will be concatenated.

For example :

$ex->messsage( "I found some error:", $some_data );

package

Set or get the class/package name where the error originated. It returns the current value.

PROPAGATE

This method is called by perl when you call "die" in perlfunc with no parameters and $@ is set to a Module::Generic::Exception object.

This returns a new exception object that perl will use to replace the value in $@

rethrow

This rethrow (i.e. "die" in perlfunc) the original error. It must be called with the exception object or else it will return undef.

This is ok :

$ex->rethrow;

But this is not :

Module::Generic::Exception->rethrow;

retry_after

Set or get the number of seconds to way before to retry whatever cause the error. It returns the current value.

subroutine

Set or get the subroutine where the error originated. It returns the current value.

throw

Provided with a message string, this will create a new Module::Generic::Exception object and call "die" in perlfunc with it.

TO_JSON

Special method called by JSON to transform this object into a string suitable to be added in a json data.

trace

Set or get the Devel::StackTrace object used to provide a full stack trace of the error. It returns the current value.

type

Set or get the error type. It returns the current value.

CLASS FUNCTIONS

exception

exception My::Exception;
# or
exception Other::Exception extends => 'My::Exception';
die My::Exception->new( "Something bad has happened" );
say Other::Exception->error( "Another bad thing has happened" );

This class function takes a package name, and creates an exception class based on that package.

The following options are also available:

  • extends

    This takes a package name as value and will serve as the parent class

SERIALISATION

Serialisation by CBOR, Sereal and Storable::Improved (or the legacy Storable) is supported by this package. To that effect, the following subroutines are implemented: FREEZE, THAW, STORABLE_freeze and STORABLE_thaw

AUTHOR

Jacques Deguest <jack@deguest.jp>

COPYRIGHT & LICENSE

Copyright (c) 2000-2024 DEGUEST Pte. Ltd.

You can use, copy, modify and redistribute this package and associated files under the same terms as Perl itself.