1Error(3) User Contributed Perl Documentation Error(3)
2
6 Error - Error/exception handling in an OO-ish way
7
9 version 0.17026
10
12 use Error qw(:try);
13 throw Error::Simple( "A simple error");
15 sub xyz {
17 ...
18 record Error::Simple("A simple error")
19 and return;
20 }
21 unlink($file) or throw Error::Simple("$file: $!",$!);
23 try {
25 do_some_stuff();
26 die "error!" if $condition;
27 throw Error::Simple "Oops!" if $other_condition;
28 }
29 catch Error::IO with {
30 my $E = shift;
31 print STDERR "File ", $E->{'-file'}, " had a problem\n";
32 }
33 except {
34 my $E = shift;
35 my $general_handler=sub {send_message $E->{-description}};
36 return {
37 UserException1 => $general_handler,
38 UserException2 => $general_handler
39 };
40 }
41 otherwise {
42 print STDERR "Well I don't know what to say\n";
43 }
44 finally {
45 close_the_garage_door_already(); # Should be reliable
46 }; # Don't forget the trailing ; or you might be surprised
47
49 The "Error" package provides two interfaces. Firstly "Error" provides a
50 procedural interface to exception handling. Secondly "Error" is a base
51 class for errors/exceptions that can either be thrown, for subsequent
52 catch, or can simply be recorded.
53 Errors in the class "Error" should not be thrown directly, but the user
55 should throw errors from a sub-class of "Error".
56
58 version 0.17026
59
61 Using the "Error" module is no longer recommended due to the black-
62 magical nature of its syntactic sugar, which often tends to break. Its
63 maintainers have stopped actively writing code that uses it, and
64 discourage people from doing so. See the "SEE ALSO" section below for
65 better recommendations.
66
68 "Error" exports subroutines to perform exception handling. These will
69 be exported if the ":try" tag is used in the "use" line.
70 try BLOCK CLAUSES
72 "try" is the main subroutine called by the user. All other
73 subroutines exported are clauses to the try subroutine.
74 The BLOCK will be evaluated and, if no error is throw, try will
76 return the result of the block.
77 "CLAUSES" are the subroutines below, which describe what to do in
79 the event of an error being thrown within BLOCK.
80 catch CLASS with BLOCK
82 This clauses will cause all errors that satisfy "$err->isa(CLASS)"
83 to be caught and handled by evaluating "BLOCK".
84 "BLOCK" will be passed two arguments. The first will be the error
86 being thrown. The second is a reference to a scalar variable. If
87 this variable is set by the catch block then, on return from the
88 catch block, try will continue processing as if the catch block was
89 never found. The error will also be available in $@.
90 To propagate the error the catch block may call "$err->throw"
92 If the scalar reference by the second argument is not set, and the
94 error is not thrown. Then the current try block will return with
95 the result from the catch block.
96 except BLOCK
98 When "try" is looking for a handler, if an except clause is found
99 "BLOCK" is evaluated. The return value from this block should be a
100 HASHREF or a list of key-value pairs, where the keys are class
101 names and the values are CODE references for the handler of errors
102 of that type.
103 otherwise BLOCK
105 Catch any error by executing the code in "BLOCK"
106 When evaluated "BLOCK" will be passed one argument, which will be
108 the error being processed. The error will also be available in $@.
109 Only one otherwise block may be specified per try block
111 finally BLOCK
113 Execute the code in "BLOCK" either after the code in the try block
114 has successfully completed, or if the try block throws an error
115 then "BLOCK" will be executed after the handler has completed.
116 If the handler throws an error then the error will be caught, the
118 finally block will be executed and the error will be re-thrown.
119 Only one finally block may be specified per try block
121
123 Moose exports a keyword called "with" which clashes with Error's. This
124 example returns a prototype mismatch error:
125 package MyTest;
127 use warnings;
129 use Moose;
130 use Error qw(:try);
131 (Thanks to "maik.hentsche@amd.com" for the report.).
133
135 CONSTRUCTORS
136 The "Error" object is implemented as a HASH. This HASH is initialized
137 with the arguments that are passed to it's constructor. The elements
138 that are used by, or are retrievable by the "Error" class are listed
139 below, other classes may add to these.
140 -file
142 -line
143 -text
144 -value
145 -object
146 If "-file" or "-line" are not specified in the constructor arguments
148 then these will be initialized with the file name and line number where
149 the constructor was called from.
150 If the error is associated with an object then the object should be
152 passed as the "-object" argument. This will allow the "Error" package
153 to associate the error with the object.
154 The "Error" package remembers the last error created, and also the last
156 error associated with a package. This could either be the last error
157 created by a sub in that package, or the last error which passed an
158 object blessed into that package as the "-object" argument.
159 Error->new()
161 See the Error::Simple documentation.
162 throw ( [ ARGS ] )
164 Create a new "Error" object and throw an error, which will be
165 caught by a surrounding "try" block, if there is one. Otherwise it
166 will cause the program to exit.
167 "throw" may also be called on an existing error to re-throw it.
169 with ( [ ARGS ] )
171 Create a new "Error" object and returns it. This is defined for
172 syntactic sugar, eg
173 die with Some::Error ( ... );
175 record ( [ ARGS ] )
177 Create a new "Error" object and returns it. This is defined for
178 syntactic sugar, eg
179 record Some::Error ( ... )
181 and return;
182 STATIC METHODS
184 prior ( [ PACKAGE ] )
185 Return the last error created, or the last error associated with
186 "PACKAGE"
187 flush ( [ PACKAGE ] )
189 Flush the last error created, or the last error associated with
190 "PACKAGE".It is necessary to clear the error stack before exiting
191 the package or uncaught errors generated using "record" will be
192 reported.
193 $Error->flush;
195 OBJECT METHODS
197 stacktrace
198 If the variable $Error::Debug was non-zero when the error was
199 created, then "stacktrace" returns a string created by calling
200 "Carp::longmess". If the variable was zero the "stacktrace" returns
201 the text of the error appended with the filename and line number of
202 where the error was created, providing the text does not end with a
203 newline.
204 object
206 The object this error was associated with
207 file
209 The file where the constructor of this error was called from
210 line
212 The line where the constructor of this error was called from
213 text
215 The text of the error
216 $err->associate($obj)
218 Associates an error with an object to allow error propagation. I.e:
219 $ber->encode(...) or
221 return Error->prior($ber)->associate($ldap);
222 OVERLOAD METHODS
224 stringify
225 A method that converts the object into a string. This method may
226 simply return the same as the "text" method, or it may append more
227 information. For example the file name and line number.
228 By default this method returns the "-text" argument that was passed
230 to the constructor, or the string "Died" if none was given.
231 value
233 A method that will return a value that can be associated with the
234 error. For example if an error was created due to the failure of a
235 system call, then this may return the numeric value of $! at the
236 time.
237 By default this method returns the "-value" argument that was
239 passed to the constructor.
240
242 Error::Simple
243 This class can be used to hold simple error strings and values. It's
244 constructor takes two arguments. The first is a text value, the second
245 is a numeric value. These values are what will be returned by the
246 overload methods.
247 If the text value ends with "at file line 1" as $@ strings do, then
249 this information will be used to set the "-file" and "-line" arguments
250 of the error object.
251 This class is used internally if an eval'd block die's with an error
253 that is a plain string. (Unless $Error::ObjectifyCallback is modified)
254
256 This variable holds a reference to a subroutine that converts errors
257 that are plain strings to objects. It is used by Error.pm to convert
258 textual errors to objects, and can be overridden by the user.
259 It accepts a single argument which is a hash reference to named
261 parameters. Currently the only named parameter passed is 'text' which
262 is the text of the error, but others may be available in the future.
263 For example the following code will cause Error.pm to throw objects of
265 the class MyError::Bar by default:
266 sub throw_MyError_Bar
268 {
269 my $args = shift;
270 my $err = MyError::Bar->new();
271 $err->{'MyBarText'} = $args->{'text'};
272 return $err;
273 }
274 {
276 local $Error::ObjectifyCallback = \&throw_MyError_Bar;
277 # Error handling here.
279 }
280
282 "Error" also provides handlers to extend the output of the "warn()"
283 perl function, and to handle the printing of a thrown "Error" that is
284 not caught or otherwise handled. These are not installed by default,
285 but are requested using the ":warndie" tag in the "use" line.
286 use Error qw( :warndie );
288 These new error handlers are installed in $SIG{__WARN__} and
290 $SIG{__DIE__}. If these handlers are already defined when the tag is
291 imported, the old values are stored, and used during the new code.
292 Thus, to arrange for custom handling of warnings and errors, you will
293 need to perform something like the following:
294 BEGIN {
296 $SIG{__WARN__} = sub {
297 print STDERR "My special warning handler: $_[0]"
298 };
299 }
300 use Error qw( :warndie );
302 Note that setting $SIG{__WARN__} after the ":warndie" tag has been
304 imported will overwrite the handler that "Error" provides. If this
305 cannot be avoided, then the tag can be explicitly "import"ed later
306 use Error;
308 $SIG{__WARN__} = ...;
310 import Error qw( :warndie );
312 EXAMPLE
314 The "__DIE__" handler turns messages such as
315 Can't call method "foo" on an undefined value at examples/warndie.pl line 16.
317 into
319 Unhandled perl error caught at toplevel:
321 Can't call method "foo" on an undefined value
323 Thrown from: examples/warndie.pl:16
325 Full stack trace:
327 main::inner('undef') called at examples/warndie.pl line 20
329 main::outer('undef') called at examples/warndie.pl line 23
330
332 See Exception::Class for a different module providing Object-Oriented
333 exception handling, along with a convenient syntax for declaring
334 hierarchies for them. It doesn't provide Error's syntactic sugar of
335 "try { ... }", "catch { ... }", etc. which may be a good thing or a bad
336 thing based on what you want. (Because Error's syntactic sugar tends to
337 break.)
338 Error::Exception aims to combine Error and Exception::Class "with
340 correct stringification".
341 TryCatch and Try::Tiny are similar in concept to Error.pm only
343 providing a syntax that hopefully breaks less.
344
346 None, but that does not mean there are not any.
347
349 Graham Barr <gbarr@pobox.com>
350 The code that inspired me to write this was originally written by Peter
352 Seibel <peter@weblogic.com> and adapted by Jesse Glick
353 <jglick@sig.bsh.com>.
354 ":warndie" handlers added by Paul Evans <leonerd@leonerd.org.uk>
356
358 Shlomi Fish, <http://www.shlomifish.org/> .
359
361 Arun Kumar U <u_arunkumar@yahoo.com>
362
364 Copyright (c) 1997-8 Graham Barr. All rights reserved. This program
365 is free software; you can redistribute it and/or modify it under the
366 same terms as Perl itself.
367
369 Shlomi Fish ( http://www.shlomifish.org/ )
370
372 This software is copyright (c) 2018 by Shlomi Fish (
373 http://www.shlomifish.org/ ).
374 This is free software; you can redistribute it and/or modify it under
376 the same terms as the Perl 5 programming language system itself.
377
379 Please report any bugs or feature requests on the bugtracker website
380 <https://github.com/shlomif/error/issues>
381 When submitting a bug or request, please include a test-file or a patch
383 to an existing test-file that illustrates the bug or desired feature.
384
386 Perldoc
387 You can find documentation for this module with the perldoc command.
388 perldoc Error
390 Websites
392 The following websites have more information about this module, and may
393 be of help to you. As always, in addition to those websites please use
394 your favorite search engine to discover more resources.
395 · MetaCPAN
397 A modern, open-source CPAN search engine, useful to view POD in
399 HTML format.
400 <https://metacpan.org/release/Error>
402 · Search CPAN
404 The default CPAN search engine, useful to view POD in HTML format.
406 <http://search.cpan.org/dist/Error>
408 · RT: CPAN's Bug Tracker
410 The RT ( Request Tracker ) website is the default bug/issue
412 tracking system for CPAN.
413 <https://rt.cpan.org/Public/Dist/Display.html?Name=Error>
415 · AnnoCPAN
417 The AnnoCPAN is a website that allows community annotations of Perl
419 module documentation.
420 <http://annocpan.org/dist/Error>
422 · CPAN Ratings
424 The CPAN Ratings is a website that allows community ratings and
426 reviews of Perl modules.
427 <http://cpanratings.perl.org/d/Error>
429 · CPANTS
431 The CPANTS is a website that analyzes the Kwalitee ( code metrics )
433 of a distribution.
434 <http://cpants.cpanauthors.org/dist/Error>
436 · CPAN Testers
438 The CPAN Testers is a network of smoke testers who run automated
440 tests on uploaded CPAN distributions.
441 <http://www.cpantesters.org/distro/E/Error>
443 · CPAN Testers Matrix
445 The CPAN Testers Matrix is a website that provides a visual
447 overview of the test results for a distribution on various
448 Perls/platforms.
449 <http://matrix.cpantesters.org/?dist=Error>
451 · CPAN Testers Dependencies
453 The CPAN Testers Dependencies is a website that shows a chart of
455 the test results of all dependencies for a distribution.
456 <http://deps.cpantesters.org/?module=Error>
458 Bugs / Feature Requests
460 Please report any bugs or feature requests by email to "bug-error at
461 rt.cpan.org", or through the web interface at
462 <https://rt.cpan.org/Public/Bug/Report.html?Queue=Error>. You will be
463 automatically notified of any progress on the request by the system.
464 Source Code
466 The code is open to the world, and available for you to hack on. Please
467 feel free to browse it and play with it, or whatever. If you want to
468 contribute patches, please send me a diff or prod me to pull from your
469 repository :)
470 <https://github.com/shlomif/error>
472 git clone https://bitbucket.org/shlomif/perl-error.pm
474perl v5.28.0 2018-05-23 Error(3)