/ 
X-Tiny-0.01-TRIAL
River stage two • 15 direct dependents • 20 total dependents
/ X::Tiny::Base

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) = @_;

    ...
}

sub get {
    my ($self, $attr_name) = @_;

    ...
}

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 is meant for you to subclass into your distribution’s own exception base class (e.g., My::Module::X::Base); you should then subclass that base class for your distribution’s specific exception classes (e.g., My::Module::X::BadInput).

X::Tiny::Base, then, 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:

  • A stack trace

  • Propagations

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

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( 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.