NAME¶
GD::Graph::Error - Error handling for GD::Graph classes
SYNOPSIS¶
use GD::Graph::Error_subclass;
DESCRIPTION¶
This class is a parent for all GD::Graph classes, including GD::Graph::Data, and
offers error and warning handling and some debugging control.
Errors are stored in a lexical hash in this package, so the implementation of
the subclass should be irrelevant.
PUBLIC METHODS¶
These methods can be used by users of any of the subclasses of GD::Graph::Error
to get at the errors of objects or classes.
$object->error() OR Class->error()¶
Returns a list of all the errors that the current object has accumulated. In
scalar context, returns the last error. If called as a class method it works
at a class level. This is handy when a constructor fails, for example:
my $data = GD::Graph::Data->new()
or die GD::Graph::Data->error;
$data->read(file => '/foo/bar.data')
or die $data->error;
or if you really are only interested in the last error:
$data->read(file => '/foo/bar.data')
or die scalar $data->error;
This implementation does not clear the error list, so if you don't die on
errors, you will need to make sure to never ask for anything but the last
error (put this in scalar context) or to call "clear_error()" now
and again.
Errors are more verbose about where the errors originated if the
$GD::Graph::Error::Debug variable is set to a true value, and even more
verbose if this value is larger than 5.
If $Debug is larger than 3, both of these will always return the full list of
errors and warnings (although the meaning of "has_warning" and
"has_error" does not change).
$object->has_error() OR
Class->has_error()¶
$object->has_warning() OR
Class->has_warning()¶
Returns true if there are pending errors (warnings) for the object (or class).
To be more precise, it returns a list of errors in list context, and the
number of errors in scalar context.
This allows you to check for errors and warnings after a large number of
operations which each might fail:
$data->read(file => '/foo/bar.data') or die $data->error;
while (my @foo = $sth->fetchrow_array)
{
$data->add_point(@foo);
}
$data->set_x(12, 'Foo');
$data->has_warning and warn $data->warning;
$data->has_error and die $data->error;
The reason to call this, instead of just calling "error()" or
"warning()" and looking at its return value, is that this method is
much more efficient and fast.
If you want to count anything as bad, just set $ErrorLevel to 0, after which you
only need to call "has_error".
$object->clear_errors() or
Class->clear_errors()¶
Clears all outstanding errors.
PROTECTED METHODS¶
These methods are only to be called from within this class and its Subclasses.
$object->_set_error(arg) or
Class->_set_error(arg)¶
$object->_set_warning(arg) or
Class->_set_warning(arg)¶
Subclasses call this to set an error. The argument can be a reference to an
array, of which the first element should be the error level, and the second
element the error message. Alternatively, it can just be the message, in which
case the error level will be assumed to be $ErrorLevel.
If the error level is >= $CriticalLevel the program will die, using
Carp::croak to display the current message, as well as all the other error
messages pending.
In the current implementation these are almost identical when called with a
scalar argument, except that the default error level is different. When called
with an array reference, they are identical in function. This may change in
the future. They're mainly here for code clarity.
$object->_move_errors¶
Move errors from an object into the class it belongs to. This can be useful if
something nasty happens in the constructor, while instantiating one of these
objects, and you need to move these errors into the class space before
returning. (see GD::Graph::Data::new for an example)
VARIABLES¶
$GD::Graph::Error::Debug¶
The higher this value, the more verbose error messages will be. At the moment,
any true value will cause the line number and source file of the caller at the
top of the stack to be included, a value of more than 2 will include the error
severity, and a value of more than 5 will also include the direct caller's
(i.e. the spot where the error message was generated) line number and package.
Default: 0.
$GD::Graph::Error::ErrorLevel¶
Errors levels below this value will be counted as warnings, and error levels
above (and inclusive) up to $CriticalLevel will be counted as errors. This is
also the default error level for the "_set_error()" method. This
value should be 0 or larger, and smaller than $CriticalLevel. Default: 5.
$GD::Graph::Error::CriticalLevel¶
Any errorlevel of or above this level will immediately cause the program to die
with the specified message, using Carp::croak. Default: 10.
NOTES¶
As with all Modules for Perl: Please stick to using the interface. If you try to
fiddle too much with knowledge of the internals of this module, you could get
burned. I may change them at any time.
AUTHOR¶
Martien Verbruggen <mgjv@tradingpost.com.au>
Copyright¶
(c) Martien Verbruggen.
All rights reserved. This package is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.
SEE ALSO¶
GD::Graph, GD::Graph::Data