NAME

GT::Base - Common base module to be inherited by all classes.

SYNOPSIS

    use GT::Base;
    use vars qw/@ISA $ATTRIBS $ERRORS/
    @ISA     = qw/GT::Base/;
    $ATTRIBS = {
        accessor  => default,
        accessor2 => default,
    };
    $ERRORS = {
        BADARGS => "Invalid argument: %s passed to subroutine: %s",
    };

DESCRIPTION

GT::Base is a base class that is used to provide common error handling, debugging, creators and accessor methods.

To use GT::Base, simply make your module inherit from GT::Base. That will provide the following functionality:

Debugging

Two new methods are available for debugging:

    $self->debug($msg, [DEBUG_LEVEL]);

This will send a $msg to STDERR if the current debug level is greater then the debug level passed in (defaults to 1).

    $self->debug_level(DEBUG_LEVEL);
    Class->debug_level(DEBUG_LEVEL);

You can call debug_level() to set or get the debug level. It can be set per object by calling it as an object method, or class wide which will initilize all new objects with that debug level (only if using the built in creator).

The debugging uses a package variable:

    $Class::DEBUG = 0;

and assumes it exists.

Error Handling

Your object can now generate errors using the method:

    $self->error(CODE, LEVEL, [args]);

CODE should be a key to a hash of error codes to user readable error messages. This hash should be stored in $ERRORS which is defined in your pacakge, or the package named in $ERROR_MESSAGE.

LEVEL should be either 'FATAL' or 'WARN'. If not specified it defaults to FATAL. If it's a fatal error, the program will print the message to STDERR and die.

args can be used to format the error message. For instance, you can defined commonly used errors like:

    CANTOPEN => "Unable to open file: '%s': %s"

in your $ERRORS hash. Then you can call error like:

    open FILE, "somefile.txt"
        or return $self->error(CANTOPEN => FATAL => "somefile.txt", "$!");

The error handler will format your message using sprintf(), so all regular printf formatting strings are allowed.

Since errors are kept within an array, too many errors can pose a memory problem. To clear the error stack simply call:

    $self->clear_errors();

Error Trapping

You can specify at run time to trap errors.

    $self->catch_errors(\&code_ref);

which sets a $SIG{__DIE__} handler. Any fatal errors that occur, will run your function. The function will not be run if the fatal was thrown inside of an eval though.

Stack Trace

You can print out a stack trace at any time by using:

    $self->stack_trace(1);
    Class->stack_trace(1);

If you pass in 1, the stack trace will be returned as a string, otherwise it will be printed to STDOUT.

Accessor Methods

Using GT::Base automatically provides accessor methods for all your attributes. By specifying:

    $ATTRIBS = {
        attrib => 'default',
        ...
    };

in your package, you can now call:

    my $val = $obj->attrib();
    $obj->attrib($set_val);

to set and retrieve the attributes for that value.

Note: This uses AUTOLOAD, so if you implement AUTOLOAD in your package, you must have it fall back to GT::Base::AUTOLOAD if it fails. This can be done with:

    AUTOLOAD {
        ...
        goto &GT::Base::AUTOLOAD;
    }

which will pass all arguments as well.

Parameter Parsing

GT::Base also provides a method to parse parameters. In your methods you can do:

    my $self = shift;
    my $parm = $self->common_param(@_);

This will convert any of a hash reference, hash or CGI object into a hash reference.

COPYRIGHT

VERSION

Revision: $Id: Base.pm,v 1.132 2005/06/22 19:59:25 jagerman Exp $