1Error(3) User Contributed Perl Documentation Error(3)
2
6 Error - Error/exception handling in an OO-ish way
7
9 use Error qw(:try);
10 throw Error::Simple( "A simple error");
12 sub xyz {
14 ...
15 record Error::Simple("A simple error")
16 and return;
17 }
18 unlink($file) or throw Error::Simple("$file: $!",$!);
20 try {
22 do_some_stuff();
23 die "error!" if $condition;
24 throw Error::Simple "Oops!" if $other_condition;
25 }
26 catch Error::IO with {
27 my $E = shift;
28 print STDERR "File ", $E->{'-file'}, " had a problem\n";
29 }
30 except {
31 my $E = shift;
32 my $general_handler=sub {send_message $E->{-description}};
33 return {
34 UserException1 => $general_handler,
35 UserException2 => $general_handler
36 };
37 }
38 otherwise {
39 print STDERR "Well I don't know what to say\n";
40 }
41 finally {
42 close_the_garage_door_already(); # Should be reliable
43 }; # Don't forget the trailing ; or you might be surprised
44
46 The "Error" package provides two interfaces. Firstly "Error" provides a
47 procedural interface to exception handling. Secondly "Error" is a base
48 class for errors/exceptions that can either be thrown, for subsequent
49 catch, or can simply be recorded.
50 Errors in the class "Error" should not be thrown directly, but the user
52 should throw errors from a sub-class of "Error".
53
55 "Error" exports subroutines to perform exception handling. These will
56 be exported if the ":try" tag is used in the "use" line.
57 try BLOCK CLAUSES
59 "try" is the main subroutine called by the user. All other subrou‐
60 tines exported are clauses to the try subroutine.
61 The BLOCK will be evaluated and, if no error is throw, try will
63 return the result of the block.
64 "CLAUSES" are the subroutines below, which describe what to do in
66 the event of an error being thrown within BLOCK.
67 catch CLASS with BLOCK
69 This clauses will cause all errors that satisfy "$err->isa(CLASS)"
70 to be caught and handled by evaluating "BLOCK".
71 "BLOCK" will be passed two arguments. The first will be the error
73 being thrown. The second is a reference to a scalar variable. If
74 this variable is set by the catch block then, on return from the
75 catch block, try will continue processing as if the catch block was
76 never found. The error will also be available in $@.
77 To propagate the error the catch block may call "$err->throw"
79 If the scalar reference by the second argument is not set, and the
81 error is not thrown. Then the current try block will return with
82 the result from the catch block.
83 except BLOCK
85 When "try" is looking for a handler, if an except clause is found
86 "BLOCK" is evaluated. The return value from this block should be a
87 HASHREF or a list of key-value pairs, where the keys are class
88 names and the values are CODE references for the handler of errors
89 of that type.
90 otherwise BLOCK
92 Catch any error by executing the code in "BLOCK"
93 When evaluated "BLOCK" will be passed one argument, which will be
95 the error being processed. The error will also be available in $@.
96 Only one otherwise block may be specified per try block
98 finally BLOCK
100 Execute the code in "BLOCK" either after the code in the try block
101 has successfully completed, or if the try block throws an error
102 then "BLOCK" will be executed after the handler has completed.
103 If the handler throws an error then the error will be caught, the
105 finally block will be executed and the error will be re-thrown.
106 Only one finally block may be specified per try block
108
110 CONSTRUCTORS
111 The "Error" object is implemented as a HASH. This HASH is initialized
113 with the arguments that are passed to it's constructor. The elements
114 that are used by, or are retrievable by the "Error" class are listed
115 below, other classes may add to these.
116 -file
118 -line
119 -text
120 -value
121 -object
122 If "-file" or "-line" are not specified in the constructor arguments
124 then these will be initialized with the file name and line number where
125 the constructor was called from.
126 If the error is associated with an object then the object should be
128 passed as the "-object" argument. This will allow the "Error" package
129 to associate the error with the object.
130 The "Error" package remembers the last error created, and also the last
132 error associated with a package. This could either be the last error
133 created by a sub in that package, or the last error which passed an
134 object blessed into that package as the "-object" argument.
135 Error->new()
137 See the Error::Simple documentation.
138 throw ( [ ARGS ] )
140 Create a new "Error" object and throw an error, which will be
141 caught by a surrounding "try" block, if there is one. Otherwise it
142 will cause the program to exit.
143 "throw" may also be called on an existing error to re-throw it.
145 with ( [ ARGS ] )
147 Create a new "Error" object and returns it. This is defined for
148 syntactic sugar, eg
149 die with Some::Error ( ... );
151 record ( [ ARGS ] )
153 Create a new "Error" object and returns it. This is defined for
154 syntactic sugar, eg
155 record Some::Error ( ... )
157 and return;
158 STATIC METHODS
160 prior ( [ PACKAGE ] )
162 Return the last error created, or the last error associated with
163 "PACKAGE"
164 flush ( [ PACKAGE ] )
166 Flush the last error created, or the last error associated with
167 "PACKAGE".It is necessary to clear the error stack before exiting
168 the package or uncaught errors generated using "record" will be
169 reported.
170 $Error->flush;
172 OBJECT METHODS
174 stacktrace
176 If the variable $Error::Debug was non-zero when the error was cre‐
177 ated, then "stacktrace" returns a string created by calling
178 "Carp::longmess". If the variable was zero the "stacktrace" returns
179 the text of the error appended with the filename and line number of
180 where the error was created, providing the text does not end with a
181 newline.
182 object
184 The object this error was associated with
185 file
187 The file where the constructor of this error was called from
188 line
190 The line where the constructor of this error was called from
191 text
193 The text of the error
194 $err->associate($obj)
196 Associates an error with an object to allow error propagation. I.e:
197 $ber->encode(...) or
199 return Error->prior($ber)->associate($ldap);
200 OVERLOAD METHODS
202 stringify
204 A method that converts the object into a string. This method may
205 simply return the same as the "text" method, or it may append more
206 information. For example the file name and line number.
207 By default this method returns the "-text" argument that was passed
209 to the constructor, or the string "Died" if none was given.
210 value
212 A method that will return a value that can be associated with the
213 error. For example if an error was created due to the failure of a
214 system call, then this may return the numeric value of $! at the
215 time.
216 By default this method returns the "-value" argument that was
218 passed to the constructor.
219
221 Error::Simple
222 This class can be used to hold simple error strings and values. It's
224 constructor takes two arguments. The first is a text value, the second
225 is a numeric value. These values are what will be returned by the over‐
226 load methods.
227 If the text value ends with "at file line 1" as $@ strings do, then
229 this infomation will be used to set the "-file" and "-line" arguments
230 of the error object.
231 This class is used internally if an eval'd block die's with an error
233 that is a plain string. (Unless $Error::ObjectifyCallback is modified)
234
236 This variable holds a reference to a subroutine that converts errors
237 that are plain strings to objects. It is used by Error.pm to convert
238 textual errors to objects, and can be overrided by the user.
239 It accepts a single argument which is a hash reference to named parame‐
241 ters. Currently the only named parameter passed is 'text' which is the
242 text of the error, but others may be available in the future.
243 For example the following code will cause Error.pm to throw objects of
245 the class MyError::Bar by default:
246 sub throw_MyError_Bar
248 {
249 my $args = shift;
250 my $err = MyError::Bar->new();
251 $err->{'MyBarText'} = $args->{'text'};
252 return $err;
253 }
254 {
256 local $Error::ObjectifyCallback = \&throw_MyError_Bar;
257 # Error handling here.
259 }
260
262 "Error" also provides handlers to extend the output of the "warn()"
263 perl function, and to handle the printing of a thrown "Error" that is
264 not caught or otherwise handled. These are not installed by default,
265 but are requested using the ":warndie" tag in the "use" line.
266 use Error qw( :warndie );
268 These new error handlers are installed in $SIG{__WARN__} and
270 $SIG{__DIE__}. If these handlers are already defined when the tag is
271 imported, the old values are stored, and used during the new code.
272 Thus, to arrange for custom handling of warnings and errors, you will
273 need to perform something like the following:
274 BEGIN {
276 $SIG{__WARN__} = sub {
277 print STDERR "My special warning handler: $_[0]"
278 };
279 }
280 use Error qw( :warndie );
282 Note that setting $SIG{__WARN__} after the ":warndie" tag has been
284 imported will overwrite the handler that "Error" provides. If this can‐
285 not be avoided, then the tag can be explicitly "import"ed later
286 use Error;
288 $SIG{__WARN__} = ...;
290 import Error qw( :warndie );
292 EXAMPLE
294 The "__DIE__" handler turns messages such as
296 Can't call method "foo" on an undefined value at examples/warndie.pl line 16.
298 into
300 Unhandled perl error caught at toplevel:
302 Can't call method "foo" on an undefined value
304 Thrown from: examples/warndie.pl:16
306 Full stack trace:
308 main::inner('undef') called at examples/warndie.pl line 20
310 main::outer('undef') called at examples/warndie.pl line 23
311
313 None, but that does not mean there are not any.
314
316 Graham Barr <gbarr@pobox.com>
317 The code that inspired me to write this was originally written by Peter
319 Seibel <peter@weblogic.com> and adapted by Jesse Glick
320 <jglick@sig.bsh.com>.
321 ":warndie" handlers added by Paul Evans <leonerd@leonerd.org.uk>
323
325 Shlomi Fish <shlomif@iglu.org.il>
326
328 Arun Kumar U <u_arunkumar@yahoo.com>
329
331 Copyright (c) 1997-8 Graham Barr. All rights reserved. This program
332 is free software; you can redistribute it and/or modify it under the
333 same terms as Perl itself.
334perl v5.8.8 2007-11-22 Error(3)