1Error(3) User Contributed Perl Documentation Error(3)
2
6 Error
7
9 version 0.17027
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 Error - Error/exception handling in an OO-ish way
59
61 version 0.17027
62
64 Using the "Error" module is no longer recommended due to the black-
65 magical nature of its syntactic sugar, which often tends to break. Its
66 maintainers have stopped actively writing code that uses it, and
67 discourage people from doing so. See the "SEE ALSO" section below for
68 better recommendations.
69
71 "Error" exports subroutines to perform exception handling. These will
72 be exported if the ":try" tag is used in the "use" line.
73 try BLOCK CLAUSES
75 "try" is the main subroutine called by the user. All other
76 subroutines exported are clauses to the try subroutine.
77 The BLOCK will be evaluated and, if no error is throw, try will
79 return the result of the block.
80 "CLAUSES" are the subroutines below, which describe what to do in
82 the event of an error being thrown within BLOCK.
83 catch CLASS with BLOCK
85 This clauses will cause all errors that satisfy "$err->isa(CLASS)"
86 to be caught and handled by evaluating "BLOCK".
87 "BLOCK" will be passed two arguments. The first will be the error
89 being thrown. The second is a reference to a scalar variable. If
90 this variable is set by the catch block then, on return from the
91 catch block, try will continue processing as if the catch block was
92 never found. The error will also be available in $@.
93 To propagate the error the catch block may call "$err->throw"
95 If the scalar reference by the second argument is not set, and the
97 error is not thrown. Then the current try block will return with
98 the result from the catch block.
99 except BLOCK
101 When "try" is looking for a handler, if an except clause is found
102 "BLOCK" is evaluated. The return value from this block should be a
103 HASHREF or a list of key-value pairs, where the keys are class
104 names and the values are CODE references for the handler of errors
105 of that type.
106 otherwise BLOCK
108 Catch any error by executing the code in "BLOCK"
109 When evaluated "BLOCK" will be passed one argument, which will be
111 the error being processed. The error will also be available in $@.
112 Only one otherwise block may be specified per try block
114 finally BLOCK
116 Execute the code in "BLOCK" either after the code in the try block
117 has successfully completed, or if the try block throws an error
118 then "BLOCK" will be executed after the handler has completed.
119 If the handler throws an error then the error will be caught, the
121 finally block will be executed and the error will be re-thrown.
122 Only one finally block may be specified per try block
124
126 Moose exports a keyword called "with" which clashes with Error's. This
127 example returns a prototype mismatch error:
128 package MyTest;
130 use warnings;
132 use Moose;
133 use Error qw(:try);
134 (Thanks to "maik.hentsche@amd.com" for the report.).
136
138 CONSTRUCTORS
139 The "Error" object is implemented as a HASH. This HASH is initialized
140 with the arguments that are passed to it's constructor. The elements
141 that are used by, or are retrievable by the "Error" class are listed
142 below, other classes may add to these.
143 -file
145 -line
146 -text
147 -value
148 -object
149 If "-file" or "-line" are not specified in the constructor arguments
151 then these will be initialized with the file name and line number where
152 the constructor was called from.
153 If the error is associated with an object then the object should be
155 passed as the "-object" argument. This will allow the "Error" package
156 to associate the error with the object.
157 The "Error" package remembers the last error created, and also the last
159 error associated with a package. This could either be the last error
160 created by a sub in that package, or the last error which passed an
161 object blessed into that package as the "-object" argument.
162 Error->new()
164 See the Error::Simple documentation.
165 throw ( [ ARGS ] )
167 Create a new "Error" object and throw an error, which will be
168 caught by a surrounding "try" block, if there is one. Otherwise it
169 will cause the program to exit.
170 "throw" may also be called on an existing error to re-throw it.
172 with ( [ ARGS ] )
174 Create a new "Error" object and returns it. This is defined for
175 syntactic sugar, eg
176 die with Some::Error ( ... );
178 record ( [ ARGS ] )
180 Create a new "Error" object and returns it. This is defined for
181 syntactic sugar, eg
182 record Some::Error ( ... )
184 and return;
185 STATIC METHODS
187 prior ( [ PACKAGE ] )
188 Return the last error created, or the last error associated with
189 "PACKAGE"
190 flush ( [ PACKAGE ] )
192 Flush the last error created, or the last error associated with
193 "PACKAGE".It is necessary to clear the error stack before exiting
194 the package or uncaught errors generated using "record" will be
195 reported.
196 $Error->flush;
198 OBJECT METHODS
200 stacktrace
201 If the variable $Error::Debug was non-zero when the error was
202 created, then "stacktrace" returns a string created by calling
203 "Carp::longmess". If the variable was zero the "stacktrace" returns
204 the text of the error appended with the filename and line number of
205 where the error was created, providing the text does not end with a
206 newline.
207 object
209 The object this error was associated with
210 file
212 The file where the constructor of this error was called from
213 line
215 The line where the constructor of this error was called from
216 text
218 The text of the error
219 $err->associate($obj)
221 Associates an error with an object to allow error propagation. I.e:
222 $ber->encode(...) or
224 return Error->prior($ber)->associate($ldap);
225 OVERLOAD METHODS
227 stringify
228 A method that converts the object into a string. This method may
229 simply return the same as the "text" method, or it may append more
230 information. For example the file name and line number.
231 By default this method returns the "-text" argument that was passed
233 to the constructor, or the string "Died" if none was given.
234 value
236 A method that will return a value that can be associated with the
237 error. For example if an error was created due to the failure of a
238 system call, then this may return the numeric value of $! at the
239 time.
240 By default this method returns the "-value" argument that was
242 passed to the constructor.
243
245 Error::Simple
246 This class can be used to hold simple error strings and values. It's
247 constructor takes two arguments. The first is a text value, the second
248 is a numeric value. These values are what will be returned by the
249 overload methods.
250 If the text value ends with "at file line 1" as $@ strings do, then
252 this information will be used to set the "-file" and "-line" arguments
253 of the error object.
254 This class is used internally if an eval'd block die's with an error
256 that is a plain string. (Unless $Error::ObjectifyCallback is modified)
257
259 This variable holds a reference to a subroutine that converts errors
260 that are plain strings to objects. It is used by Error.pm to convert
261 textual errors to objects, and can be overridden by the user.
262 It accepts a single argument which is a hash reference to named
264 parameters. Currently the only named parameter passed is 'text' which
265 is the text of the error, but others may be available in the future.
266 For example the following code will cause Error.pm to throw objects of
268 the class MyError::Bar by default:
269 sub throw_MyError_Bar
271 {
272 my $args = shift;
273 my $err = MyError::Bar->new();
274 $err->{'MyBarText'} = $args->{'text'};
275 return $err;
276 }
277 {
279 local $Error::ObjectifyCallback = \&throw_MyError_Bar;
280 # Error handling here.
282 }
283
285 "Error" also provides handlers to extend the output of the "warn()"
286 perl function, and to handle the printing of a thrown "Error" that is
287 not caught or otherwise handled. These are not installed by default,
288 but are requested using the ":warndie" tag in the "use" line.
289 use Error qw( :warndie );
291 These new error handlers are installed in $SIG{__WARN__} and
293 $SIG{__DIE__}. If these handlers are already defined when the tag is
294 imported, the old values are stored, and used during the new code.
295 Thus, to arrange for custom handling of warnings and errors, you will
296 need to perform something like the following:
297 BEGIN {
299 $SIG{__WARN__} = sub {
300 print STDERR "My special warning handler: $_[0]"
301 };
302 }
303 use Error qw( :warndie );
305 Note that setting $SIG{__WARN__} after the ":warndie" tag has been
307 imported will overwrite the handler that "Error" provides. If this
308 cannot be avoided, then the tag can be explicitly "import"ed later
309 use Error;
311 $SIG{__WARN__} = ...;
313 import Error qw( :warndie );
315 EXAMPLE
317 The "__DIE__" handler turns messages such as
318 Can't call method "foo" on an undefined value at examples/warndie.pl line 16.
320 into
322 Unhandled perl error caught at toplevel:
324 Can't call method "foo" on an undefined value
326 Thrown from: examples/warndie.pl:16
328 Full stack trace:
330 main::inner('undef') called at examples/warndie.pl line 20
332 main::outer('undef') called at examples/warndie.pl line 23
333
335 See Exception::Class for a different module providing Object-Oriented
336 exception handling, along with a convenient syntax for declaring
337 hierarchies for them. It doesn't provide Error's syntactic sugar of
338 "try { ... }", "catch { ... }", etc. which may be a good thing or a bad
339 thing based on what you want. (Because Error's syntactic sugar tends to
340 break.)
341 Error::Exception aims to combine Error and Exception::Class "with
343 correct stringification".
344 TryCatch and Try::Tiny are similar in concept to Error.pm only
346 providing a syntax that hopefully breaks less.
347
349 None, but that does not mean there are not any.
350
352 Graham Barr <gbarr@pobox.com>
353 The code that inspired me to write this was originally written by Peter
355 Seibel <peter@weblogic.com> and adapted by Jesse Glick
356 <jglick@sig.bsh.com>.
357 ":warndie" handlers added by Paul Evans <leonerd@leonerd.org.uk>
359
361 Shlomi Fish, <http://www.shlomifish.org/> .
362
364 Arun Kumar U <u_arunkumar@yahoo.com>
365
367 Copyright (c) 1997-8 Graham Barr. All rights reserved. This program
368 is free software; you can redistribute it and/or modify it under the
369 same terms as Perl itself.
370
372 Websites
373 The following websites have more information about this module, and may
374 be of help to you. As always, in addition to those websites please use
375 your favorite search engine to discover more resources.
376 · MetaCPAN
378 A modern, open-source CPAN search engine, useful to view POD in
380 HTML format.
381 <https://metacpan.org/release/Error>
383 · Search CPAN
385 The default CPAN search engine, useful to view POD in HTML format.
387 <http://search.cpan.org/dist/Error>
389 · RT: CPAN's Bug Tracker
391 The RT ( Request Tracker ) website is the default bug/issue
393 tracking system for CPAN.
394 <https://rt.cpan.org/Public/Dist/Display.html?Name=Error>
396 · AnnoCPAN
398 The AnnoCPAN is a website that allows community annotations of Perl
400 module documentation.
401 <http://annocpan.org/dist/Error>
403 · CPAN Ratings
405 The CPAN Ratings is a website that allows community ratings and
407 reviews of Perl modules.
408 <http://cpanratings.perl.org/d/Error>
410 · CPANTS
412 The CPANTS is a website that analyzes the Kwalitee ( code metrics )
414 of a distribution.
415 <http://cpants.cpanauthors.org/dist/Error>
417 · CPAN Testers
419 The CPAN Testers is a network of smoke testers who run automated
421 tests on uploaded CPAN distributions.
422 <http://www.cpantesters.org/distro/E/Error>
424 · CPAN Testers Matrix
426 The CPAN Testers Matrix is a website that provides a visual
428 overview of the test results for a distribution on various
429 Perls/platforms.
430 <http://matrix.cpantesters.org/?dist=Error>
432 · CPAN Testers Dependencies
434 The CPAN Testers Dependencies is a website that shows a chart of
436 the test results of all dependencies for a distribution.
437 <http://deps.cpantesters.org/?module=Error>
439 Bugs / Feature Requests
441 Please report any bugs or feature requests by email to "bug-error at
442 rt.cpan.org", or through the web interface at
443 <https://rt.cpan.org/Public/Bug/Report.html?Queue=Error>. You will be
444 automatically notified of any progress on the request by the system.
445 Source Code
447 The code is open to the world, and available for you to hack on. Please
448 feel free to browse it and play with it, or whatever. If you want to
449 contribute patches, please send me a diff or prod me to pull from your
450 repository :)
451 <https://github.com/shlomif/error>
453 git clone https://bitbucket.org/shlomif/perl-error.pm
455
457 Shlomi Fish ( http://www.shlomifish.org/ )
458
460 Please report any bugs or feature requests on the bugtracker website
461 <https://github.com/shlomif/error/issues>
462 When submitting a bug or request, please include a test-file or a patch
464 to an existing test-file that illustrates the bug or desired feature.
465
467 This software is copyright (c) 2018 by Shlomi Fish (
468 http://www.shlomifish.org/ ).
469 This is free software; you can redistribute it and/or modify it under
471 the same terms as the Perl 5 programming language system itself.
472perl v5.28.1 2018-10-28 Error(3)