NAME

X::Tiny::Base - super-light exception base class

SYNOPSIS

    package My::Module::X::Base;

    use parent qw( X::Tiny::Base );

    sub _new {
        my ($class, @args) = @_;

        ...
    }

    #Optionally, redefine this:
    sub get {
        my ($self, $attr_name) = @_;

        ...
    }

    #Optionally, redefine this:
    sub get_message { ... }

    #Optionally, redefine this:
    sub to_string { ... }

    #If you override this, be sure also to call the base method.
    sub DESTROY {
        my ($self) = @_;

        ...

        #vv This. Be sure to do this in your override method.
        $self->SUPER::DESTROY();
    }

DESCRIPTION

This base class can be subclassed into your distribution’s own exception base class (e.g., "My::Module::X::Base"), or you can treat it as that base class itself (i.e., forgo "My::Module::X::Base").

"X::Tiny::Base" serves two functions:

1) It is a useful set of defaults for overridable methods.
2) Framework handling of overload stringification behavior, e.g., when an uncaught exception is printed.

That stringification’s precise formatting is not defined; however, it will always include, in addition to the exception’s main message:

A stack trace (including function arguments)
IMPORTANT: For security purposes, take care not to expose any function arguments that might contain sensitive information (e.g., passwords).

Note that, in pre-5.16 Perls, this writes to the @DB::args global. (That shouldn’t affect you, but it’s interaction with the environment, so better documented than not.)
Propagations

There is currently no access provided in code to these; if that’s something you’d like to have, let me know.

NOTE: The overload stringification doesn’t seem to work as implemented in Perl 5.8 or earlier. Perl 5.8 went end-of-life on 14 December 2008. Yeah.

SUBCLASS INTERFACE

The default behaviors seem pretty usable and desirable to me, but there may be circumstances where someone wants other behaviors. Toward that end, the following methods are meant to be overridden in subclasses:

CLASS->OVERLOAD()

Returns a boolean to indicate whether this exception class should load overload as part of creating exceptions. If you don’t want the memory overhead of overload, then make this return 0. It returns 1 by default.

You might also make this 0 if, for example, you want to handle the overload behavior yourself. (But at that point, why use X::Tiny??)

CLASS->_new( MESSAGE, KEY1 => VALUE1, .. )

The main constructor. Whatever args this accepts are the args that you should use to create exceptions via your X::Tiny subclass’s "create()" method. You’re free to design whatever internal representation you want for your class: hash reference, array reference, etc.

The default implementation accepts a string message and, optionally, a list of key/value pairs. It is useful that subclasses of your base class define their own MESSAGE, so all you’ll pass in is a specific piece of information about this instance—e.g., an error code, a parameter name, etc.

OBJ->get_message()

Return the exception’s main MESSAGE. This is useful for contexts where you want to encapsulate the error internals from how you’re reporting them, e.g., for protocols.

OBJ->get( ATTRIBUTE_NAME )

Retrieves the value of an attribute.

OBJ->to_string()

Creates a simple string representation of your exception. The default implementation contains the class and the MESSAGE given on instantiation.

This method’s return value should NOT include a strack trace; X::Tiny::Base’s internals handle that one for you.

DESTRUCTOR METHODS

If you define your own "DESTROY()" method, make sure you also call "SUPER::DESTROY()", or else you’ll get memory leaks as X::Tiny::Base’s internal tracking of object properties will never be cleared out.