man Zoidberg::Utils::Error () - OO error handling

NAME

Zoidberg::Utils::Error - OO error handling

SYNOPSIS

        use Zoidberg::Utils qw/:error/;

        sub some_command {
                error "Wrong number of arguments"
                        unless scalar(@_) == 3;
                # do stuff
        }

        # this raises an object oriented exception

DESCRIPTION

This library supplies the methods to replace CWdie(). These methods raise an exception but passing a object containing both the error string and caller information. Thus, when the exception is caught, more subtle error messages can be produced depending on for example verbosity settings.

If the global variable CW$ERROR_CALLER is set in a package using this library, all errors will pretend to originate from the call-frame identified by the number of the variable. Setting CW$ERROR_CALLER to 1 will result in Carp like behaviour.

Although when working within the Zoidberg framework this module should be used through the Zoidberg::Utils interface, it also can be used on it's own.

EXPORT

By default CWerror(), CWbug() and CWtodo(). When using the Zoidberg::Utils interface you also get CWcomplain(), which actually belongs to Zoidberg::Utils::Output.

METHODS

Exported methods

Raises an exception which passes on CW\%error. Like CWerror(), but with CWis_bug field set. Like CWerror(), but with CWis_todo field set.

Object methods

Returns an error string. Known options:

format
Types 'gnu' and 'perl' are supported. The format 'perl' is the default, 'gnu' is used by zoidberg's CWcomplain() function. Is automaticly called by CWdie() when you use for example:
        use Zoidberg::Utils::Error;
        eval { error 'test' }
        die if $@; # die is called without explicit argument !
See also die in perlfunc.

ATTRIBUTES

The exception raised can have the folowing attributes:

string
Original error string.
scope
The global CW$Zoidberg::Utils::Error::Scope at the time of the exception. This is used to hide the real caller information in the gnu formatted error string with for example the name of a builtin command.
package
Calling package.
file
Source file where the exception was raised.
line
Line in source file where the exception was raised.
debug
The calling package had the global variable CW$DEBUG set to a non-zero value.
stack
When debug was in effect, the caller stack is traced for a number of frames equal to the value of the debug variable and put in the stack attribute.
is_bug
This exception should never happen, if it does this is considered a bug.
is_todo
This exception is raised because some feature isn't yet implemented.
propagated
Array of arrays containg information about file and line numbers where this error was propagated, see PROPAGATE.

Overloading

When the methods are given a hash reference as one of there arguments this hash overloads the default values of CW%error. Thus it is possible to fake for example the calling package, or add meta data to an exception.

AUTHOR

Jaap Karssenberg || Pardus [Larus] <pardus@cpan.org>

Copyright (c) 2003 Jaap G Karssenberg. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

Zoidberg, Zoidberg::Utils, <http://www.gnu.org/prep/standards_15.html#SEC15>