NAME

Zoidberg::Error - error handling module

SYNOPSIS

use Zoidberg::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 die(). 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.

TODO

More tracing stuff: We could use for example an environment variable to control verbosity, see caller(). Or on global in the caller package.

Carp and croak like funtions (use other names to avoid confusion)

Maybe a function that traces till the top level input line is found ? This is very croak like, but just a little different. Possibly this needs an oo interface, or an global in the caller package ...

EXPORT

By default error(), bug() and todo().

METHODS

Exported methods

error($error, ..)

Raises an exception which passes on \%error.

bug($error, ..)

Like error(), but with is_bug field set.

todo($error, ..)

Like error(), but with is_todo field set.

Object methods

stringify(%opts)

Returns an error string.

Known options:

format

Types 'gnu' and 'perl' are supported. The format 'perl' is the default.

PROPAGATE($file, $line)

Is automaticly called by die() when you use for example:

use Zoidberg::Error;

eval { error 'test' }
die if $@; # die is called without explicit argument !

See "die" in perlfunc.

ATTRIBUTES

The exception raised can have the folowing attributes:

string

Original error string.

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 $DEBUG set to a non-zero value.

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 hashes containg information about files 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 %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, http://zoidberg.sourceforge.net, http://www.gnu.org/prep/standards_15.html#SEC15