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