GD::Graph::Error(3pm)

1Graph::Error(3)       User Contributed Perl Documentation      Graph::Error(3)
2
3
4

NAME

6       GD::Graph::Error - Error handling for GD::Graph classes
7

SYNOPSIS

9       use GD::Graph::Error_subclass;
10

DESCRIPTION

12       This class is a parent for all GD::Graph classes, including
13       GD::Graph::Data, and offers error and warning handling and some debug‐
14       ging control.
15
16       Errors are stored in a lexical hash in this package, so the implementa‐
17       tion of the subclass should be irrelevant.
18

PUBLIC METHODS

20       These methods can be used by users of any of the subclasses of
21       GD::Graph::Error to get at the errors of objects or classes.
22
23       $object->error() OR Class->error()
24
25       Returns a list of all the errors that the current object has accumu‐
26       lated. In scalar context, returns the last error. If called as a class
27       method it works at a class level. This is handy when a constructor
28       fails, for example:
29
30         my $data = GD::Graph::Data->new()
31             or die GD::Graph::Data->error;
32         $data->read(file => '/foo/bar.data')
33             or die $data->error;
34
35       or if you really are only interested in the last error:
36
37         $data->read(file => '/foo/bar.data')
38             or die scalar $data->error;
39
40       This implementation does not clear the error list, so if you don't die
41       on errors, you will need to make sure to never ask for anything but the
42       last error (put this in scalar context) or to call "clear_error()" now
43       and again.
44
45       Errors are more verbose about where the errors originated if the
46       $GD::Graph::Error::Debug variable is set to a true value, and even more
47       verbose if this value is larger than 5.
48
49       If $Debug is larger than 3, both of these will always return the full
50       list of errors and warnings (although the meaning of "has_warning" and
51       "has_error" does not change).
52
53       $object->has_error() OR Class->has_error()
54
55       $object->has_warning() OR Class->has_warning()
56
57       Returns true if there are pending errors (warnings) for the object (or
58       class). To be more precise, it returns a list of errors in list con‐
59       text, and the number of errors in scalar context.
60
61       This allows you to check for errors and warnings after a large number
62       of operations which each might fail:
63
64         $data->read(file => '/foo/bar.data') or die $data->error;
65         while (my @foo = $sth->fetchrow_array)
66         {
67             $data->add_point(@foo);
68         }
69         $data->set_x(12, 'Foo');
70         $data->has_warning and warn $data->warning;
71         $data->has_error   and die  $data->error;
72
73       The reason to call this, instead of just calling "error()" or "warn‐
74       ing()" and looking at its return value, is that this method is much
75       more efficient and fast.
76
77       If you want to count anything as bad, just set $ErrorLevel to 0, after
78       which you only need to call "has_error".
79
80       $object->clear_errors() or Class->clear_errors()
81
82       Clears all outstanding errors.
83

PROTECTED METHODS

85       These methods are only to be called from within this class and its Sub‐
86       classes.
87
88       $object->_set_error(arg) or Class->_set_error(arg)
89
90       $object->_set_warning(arg) or Class->_set_warning(arg)
91
92       Subclasses call this to set an error. The argument can be a reference
93       to an array, of which the first element should be the error level, and
94       the second element the error message. Alternatively, it can just be the
95       message, in which case the error level will be assumed to be $Error‐
96       Level.
97
98       If the error level is >= $CriticalLevel the program will die, using
99       Carp::croak to display the current message, as well as all the other
100       error messages pending.
101
102       In the current implementation these are almost identical when called
103       with a scalar argument, except that the default ewrror level is differ‐
104       ent. When called with an array reference, they are identical in func‐
105       tion. This may change in the future. They're mainly here for code clar‐
106       ity.
107
108       $object->_move_errors
109
110       Move errors from an object into the class it belongs to.  This can be
111       useful if something nasty happens in the constructor, while instantiat‐
112       ing one of these objects, and you need to move these errors into the
113       class space before returning. (see GD::Graph::Data::new for an example)
114

VARIABLES

116       $GD::Graph::Error::Debug
117
118       The higher this value, the more verbose error messages will be. At the
119       moment, any true value will cause the line number and source file of
120       the caller at the top of the stack to be included, a value of more than
121       2 will include the error severity, and a value of more than 5 will also
122       include the direct caller's (i.e. the spot where the error message was
123       generated) line number and package. Default: 0.
124
125       $GD::Graph::Error::ErrorLevel
126
127       Errors levels below this value will be counted as warnings, and error
128       levels above (and inclusive) up to $CriticalLevel will be counted as
129       errors. This is also the default error level for the "_set_error()"
130       method. This value should be 0 or larger, and smaller than $Critical‐
131       Level. Default: 5.
132
133       $GD::Graph::Error::CriticalLevel
134
135       Any errorlevel of or above this level will immediately cause the pro‐
136       gram to die with the specified message, using Carp::croak. Default: 10.
137

NOTES

139       As with all Modules for Perl: Please stick to using the interface. If
140       you try to fiddle too much with knowledge of the internals of this mod‐
141       ule, you could get burned. I may change them at any time.
142

AUTHOR

144       Martien Verbruggen <mgjv@tradingpost.com.au>
145
146       Copyright
147
148       (c) Martien Verbruggen.
149
150       All rights reserved. This package is free software; you can redis‐
151       tribute it and/or modify it under the same terms as Perl itself.
152