Module:...ception(3)

📦 version 1.1.3, in alpine 3.24

💖 NAME 💖

Module::Generic::Exception — Generic Module Exception Class

okay so this is the User Contributed Perl Documentation page for Module::Generic::Exception, and the manual name is Module:...ception(3) (yes, the truncation is giving ✨mystery✨ but we move). It’s a generic module exception class, and it’s here to make your errors cute and informative. 💅

✨ SYNOPSIS ✨

bestie, here are the main-character ways to make one:

    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 strings 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.4.0 — short, sweet, and absolutely the version, no cap.

🦋 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. iconic behavior, honestly.

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

💅 METHODS 💅

🎀 `new`

It takes either a Module::Generic::Exception object, or a hash reference of properties, or a list of arguments that will be concatenated to form the error message. The list of arguments can contain code references such as references to subroutines, which 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 serves 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 a 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 the unique argument, then the properties message, code, type, and retry_after are copied from it into 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 subroutine from which this was called. This is populated using the subroutine in Devel::StackTrace.
type — an optional error type.

It returns the exception object. periodt. 💖

🪞 `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`

okay bestie, this is how caught vibes with Nice::Try:

    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 lets you do this instead:

    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 a hash reference of metadata that serves to provide more context on the error.

This returns a 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 Text::PO::Gettext to implement the 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 $@.

🔄 `reset`

The stringification of the exception is cached. This method, reset, resets that cache so the exception can be stringified again.

🌀 `rethrow`

This rethrows (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 wait before retrying whatever caused 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 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.

🌈 THREAD SAFETY 🌈

This module is thread-safe.

Each instance of Module::Generic::Exception is self-contained and immutable once created and does not share any mutable state across threads. slay, no shared-state chaos. 💚

🌸 AUTHOR 🌸

Jacques Deguest (jack@deguest.jp) — the icon behind this page. 💖

⚖️ COPYRIGHT & LICENSE ⚖️

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

🎀 cute sign-off: this page comes from perl v5.42.2, dated 2026-02-15, and the footer manual label is Module:...ception(3). bye bestie, go throw exceptions responsibly 💖

📦 where this page comes from

alpine 3.24: perl-module-generic-doc 1.1.3-r1 · GPL-1.0-or-later OR Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

Module:...ception(3)

💖 NAME 💖

✨ SYNOPSIS ✨

🌸 VERSION 🌸

🦋 DESCRIPTION 🦋

💅 METHODS 💅

🎀 new

🪞 as_string

🫶 caught

🎁 cause

🔢 code

📁 file

🌍 lang

📏 line

🗺️ locale

💬 message

📦 package

🚨 PROPAGATE

🔄 reset

🌀 rethrow

⏳ retry_after

🧩 subroutine

🗣️ throw

🧾 TO_JSON

🧵 trace

🏷️ type