.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Graph::Error 3"
.TH Graph::Error 3 "2013-07-05" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
GD::Graph::Error \- Error handling for GD::Graph classes
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
use GD::Graph::Error_subclass;
.SH "DESCRIPTION"
.IX Header "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.
.PP
Errors are stored in a lexical hash in this package, so the
implementation of the subclass should be irrelevant.
.SH "PUBLIC METHODS"
.IX Header "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.
.ie n .SS "$object\->\fIerror()\fP \s-1OR\s0 Class\->\fIerror()\fP"
.el .SS "\f(CW$object\fP\->\fIerror()\fP \s-1OR\s0 Class\->\fIerror()\fP"
.IX Subsection "$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:
.PP
.Vb 4
\&  my $data = GD::Graph::Data\->new()    
\&      or die GD::Graph::Data\->error;
\&  $data\->read(file => \*(Aq/foo/bar.data\*(Aq) 
\&      or die $data\->error;
.Ve
.PP
or if you really are only interested in the last error:
.PP
.Vb 2
\&  $data\->read(file => \*(Aq/foo/bar.data\*(Aq) 
\&      or die scalar $data\->error;
.Ve
.PP
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 \f(CW\*(C`clear_error()\*(C'\fR now
and again.
.PP
Errors are more verbose about where the errors originated if the
\&\f(CW$GD::Graph::Error::Debug\fR variable is set to a true value, and even more
verbose if this value is larger than 5.
.PP
If \f(CW$Debug\fR is larger than 3, both of these will always return the
full list of errors and warnings (although the meaning of \f(CW\*(C`has_warning\*(C'\fR
and \f(CW\*(C`has_error\*(C'\fR does not change).
.ie n .SS "$object\->\fIhas_error()\fP \s-1OR\s0 Class\->\fIhas_error()\fP"
.el .SS "\f(CW$object\fP\->\fIhas_error()\fP \s-1OR\s0 Class\->\fIhas_error()\fP"
.IX Subsection "$object->has_error() OR Class->has_error()"
.ie n .SS "$object\->\fIhas_warning()\fP \s-1OR\s0 Class\->\fIhas_warning()\fP"
.el .SS "\f(CW$object\fP\->\fIhas_warning()\fP \s-1OR\s0 Class\->\fIhas_warning()\fP"
.IX Subsection "$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.
.PP
This allows you to check for errors and warnings after a large number of
operations which each might fail:
.PP
.Vb 8
\&  $data\->read(file => \*(Aq/foo/bar.data\*(Aq) or die $data\->error;
\&  while (my @foo = $sth\->fetchrow_array)
\&  {
\&      $data\->add_point(@foo);
\&  }
\&  $data\->set_x(12, \*(AqFoo\*(Aq);
\&  $data\->has_warning and warn $data\->warning;
\&  $data\->has_error   and die  $data\->error;
.Ve
.PP
The reason to call this, instead of just calling \f(CW\*(C`error()\*(C'\fR or
\&\f(CW\*(C`warning()\*(C'\fR and looking at its return value, is that this method is
much more efficient and fast.
.PP
If you want to count anything as bad, just set \f(CW$ErrorLevel\fR to 0, after
which you only need to call \f(CW\*(C`has_error\*(C'\fR.
.ie n .SS "$object\->\fIclear_errors()\fP or Class\->\fIclear_errors()\fP"
.el .SS "\f(CW$object\fP\->\fIclear_errors()\fP or Class\->\fIclear_errors()\fP"
.IX Subsection "$object->clear_errors() or Class->clear_errors()"
Clears all outstanding errors.
.SH "PROTECTED METHODS"
.IX Header "PROTECTED METHODS"
These methods are only to be called from within this class and its
Subclasses.
.ie n .SS "$object\->_set_error(\fIarg\fP) or Class\->_set_error(\fIarg\fP)"
.el .SS "\f(CW$object\fP\->_set_error(\fIarg\fP) or Class\->_set_error(\fIarg\fP)"
.IX Subsection "$object->_set_error(arg) or Class->_set_error(arg)"
.ie n .SS "$object\->_set_warning(\fIarg\fP) or Class\->_set_warning(\fIarg\fP)"
.el .SS "\f(CW$object\fP\->_set_warning(\fIarg\fP) or Class\->_set_warning(\fIarg\fP)"
.IX Subsection "$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
\&\f(CW$ErrorLevel\fR.
.PP
If the error level is >= \f(CW$CriticalLevel\fR the program will die, using
Carp::croak to display the current message, as well as all the other
error messages pending.
.PP
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.
.ie n .SS "$object\->_move_errors"
.el .SS "\f(CW$object\fP\->_move_errors"
.IX Subsection "$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)
.SH "VARIABLES"
.IX Header "VARIABLES"
.ie n .SS "$GD::Graph::Error::Debug"
.el .SS "\f(CW$GD::Graph::Error::Debug\fP"
.IX Subsection "$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.
.ie n .SS "$GD::Graph::Error::ErrorLevel"
.el .SS "\f(CW$GD::Graph::Error::ErrorLevel\fP"
.IX Subsection "$GD::Graph::Error::ErrorLevel"
Errors levels below this value will be counted as warnings, and error
levels above (and inclusive) up to \f(CW$CriticalLevel\fR will be counted as
errors. This is also the default error level for the \f(CW\*(C`_set_error()\*(C'\fR
method. This value should be 0 or larger, and smaller than
\&\f(CW$CriticalLevel\fR. Default: 5.
.ie n .SS "$GD::Graph::Error::CriticalLevel"
.el .SS "\f(CW$GD::Graph::Error::CriticalLevel\fP"
.IX Subsection "$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.
.SH "NOTES"
.IX Header "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.
.SH "AUTHOR"
.IX Header "AUTHOR"
Martien Verbruggen <mgjv@tradingpost.com.au>
.SS "Copyright"
.IX Subsection "Copyright"
(c) Martien Verbruggen.
.PP
All rights reserved. This package is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
GD::Graph, GD::Graph::Data