1Error(3) User Contributed Perl Documentation Error(3)
2
3
4
6 Error
7
9 version 0.17027
10
12 use Error qw(:try);
13
14 throw Error::Simple( "A simple error");
15
16 sub xyz {
17 ...
18 record Error::Simple("A simple error")
19 and return;
20 }
21
22 unlink($file) or throw Error::Simple("$file: $!",$!);
23
24 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
54 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
74 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
78 The BLOCK will be evaluated and, if no error is throw, try will
79 return the result of the block.
80
81 "CLAUSES" are the subroutines below, which describe what to do in
82 the event of an error being thrown within BLOCK.
83
84 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
88 "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
94 To propagate the error the catch block may call "$err->throw"
95
96 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
100 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
107 otherwise BLOCK
108 Catch any error by executing the code in "BLOCK"
109
110 When evaluated "BLOCK" will be passed one argument, which will be
111 the error being processed. The error will also be available in $@.
112
113 Only one otherwise block may be specified per try block
114
115 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
120 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
123 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
129 package MyTest;
130
131 use warnings;
132 use Moose;
133 use Error qw(:try);
134
135 (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
144 -file
145 -line
146 -text
147 -value
148 -object
149
150 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
154 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
158 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
163 Error->new()
164 See the Error::Simple documentation.
165
166 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
171 "throw" may also be called on an existing error to re-throw it.
172
173 with ( [ ARGS ] )
174 Create a new "Error" object and returns it. This is defined for
175 syntactic sugar, eg
176
177 die with Some::Error ( ... );
178
179 record ( [ ARGS ] )
180 Create a new "Error" object and returns it. This is defined for
181 syntactic sugar, eg
182
183 record Some::Error ( ... )
184 and return;
185
186 STATIC METHODS
187 prior ( [ PACKAGE ] )
188 Return the last error created, or the last error associated with
189 "PACKAGE"
190
191 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
197 $Error->flush;
198
199 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
208 object
209 The object this error was associated with
210
211 file
212 The file where the constructor of this error was called from
213
214 line
215 The line where the constructor of this error was called from
216
217 text
218 The text of the error
219
220 $err->associate($obj)
221 Associates an error with an object to allow error propagation. I.e:
222
223 $ber->encode(...) or
224 return Error->prior($ber)->associate($ldap);
225
226 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
232 By default this method returns the "-text" argument that was passed
233 to the constructor, or the string "Died" if none was given.
234
235 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
241 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
251 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
255 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
263 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
267 For example the following code will cause Error.pm to throw objects of
268 the class MyError::Bar by default:
269
270 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
278 {
279 local $Error::ObjectifyCallback = \&throw_MyError_Bar;
280
281 # 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
290 use Error qw( :warndie );
291
292 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
298 BEGIN {
299 $SIG{__WARN__} = sub {
300 print STDERR "My special warning handler: $_[0]"
301 };
302 }
303
304 use Error qw( :warndie );
305
306 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
310 use Error;
311
312 $SIG{__WARN__} = ...;
313
314 import Error qw( :warndie );
315
316 EXAMPLE
317 The "__DIE__" handler turns messages such as
318
319 Can't call method "foo" on an undefined value at examples/warndie.pl line 16.
320
321 into
322
323 Unhandled perl error caught at toplevel:
324
325 Can't call method "foo" on an undefined value
326
327 Thrown from: examples/warndie.pl:16
328
329 Full stack trace:
330
331 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
342 Error::Exception aims to combine Error and Exception::Class "with
343 correct stringification".
344
345 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
354 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
358 ":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
377 · MetaCPAN
378
379 A modern, open-source CPAN search engine, useful to view POD in
380 HTML format.
381
382 <https://metacpan.org/release/Error>
383
384 · Search CPAN
385
386 The default CPAN search engine, useful to view POD in HTML format.
387
388 <http://search.cpan.org/dist/Error>
389
390 · RT: CPAN's Bug Tracker
391
392 The RT ( Request Tracker ) website is the default bug/issue
393 tracking system for CPAN.
394
395 <https://rt.cpan.org/Public/Dist/Display.html?Name=Error>
396
397 · AnnoCPAN
398
399 The AnnoCPAN is a website that allows community annotations of Perl
400 module documentation.
401
402 <http://annocpan.org/dist/Error>
403
404 · CPAN Ratings
405
406 The CPAN Ratings is a website that allows community ratings and
407 reviews of Perl modules.
408
409 <http://cpanratings.perl.org/d/Error>
410
411 · CPANTS
412
413 The CPANTS is a website that analyzes the Kwalitee ( code metrics )
414 of a distribution.
415
416 <http://cpants.cpanauthors.org/dist/Error>
417
418 · CPAN Testers
419
420 The CPAN Testers is a network of smoke testers who run automated
421 tests on uploaded CPAN distributions.
422
423 <http://www.cpantesters.org/distro/E/Error>
424
425 · CPAN Testers Matrix
426
427 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
431 <http://matrix.cpantesters.org/?dist=Error>
432
433 · CPAN Testers Dependencies
434
435 The CPAN Testers Dependencies is a website that shows a chart of
436 the test results of all dependencies for a distribution.
437
438 <http://deps.cpantesters.org/?module=Error>
439
440 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
446 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
452 <https://github.com/shlomif/error>
453
454 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
463 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
470 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.
472
473
474
475perl v5.28.1 2018-10-28 Error(3)