Commit | Line | Data |
cb57845a |
1 | =pod |
2 | |
3 | =encoding UTF-8 |
4 | |
5 | =head1 NAME |
6 | |
fae6bce6 |
7 | Try::Tiny - Minimal try/catch with proper preservation of $@ |
cb57845a |
8 | |
9 | =head1 VERSION |
10 | |
0a844ed9 |
11 | version 0.31 |
cb57845a |
12 | |
13 | =head1 SYNOPSIS |
14 | |
15 | You can use Try::Tiny's C<try> and C<catch> to expect and handle exceptional |
16 | conditions, avoiding quirks in Perl and common mistakes: |
17 | |
18 | # handle errors with a catch handler |
19 | try { |
20 | die "foo"; |
21 | } catch { |
22 | warn "caught error: $_"; # not $@ |
23 | }; |
24 | |
25 | You can also use it like a standalone C<eval> to catch and ignore any error |
26 | conditions. Obviously, this is an extreme measure not to be undertaken |
27 | lightly: |
28 | |
29 | # just silence errors |
30 | try { |
31 | die "foo"; |
32 | }; |
33 | |
34 | =head1 DESCRIPTION |
35 | |
36 | This module provides bare bones C<try>/C<catch>/C<finally> statements that are designed to |
37 | minimize common mistakes with eval blocks, and NOTHING else. |
38 | |
39 | This is unlike L<TryCatch> which provides a nice syntax and avoids adding |
40 | another call stack layer, and supports calling C<return> from the C<try> block to |
41 | return from the parent subroutine. These extra features come at a cost of a few |
42 | dependencies, namely L<Devel::Declare> and L<Scope::Upper> which are |
43 | occasionally problematic, and the additional catch filtering uses L<Moose> |
44 | type constraints which may not be desirable either. |
45 | |
46 | The main focus of this module is to provide simple and reliable error handling |
47 | for those having a hard time installing L<TryCatch>, but who still want to |
48 | write correct C<eval> blocks without 5 lines of boilerplate each time. |
49 | |
50 | It's designed to work as correctly as possible in light of the various |
51 | pathological edge cases (see L</BACKGROUND>) and to be compatible with any style |
52 | of error values (simple strings, references, objects, overloaded objects, etc). |
53 | |
54 | If the C<try> block dies, it returns the value of the last statement executed in |
55 | the C<catch> block, if there is one. Otherwise, it returns C<undef> in scalar |
56 | context or the empty list in list context. The following examples all |
57 | assign C<"bar"> to C<$x>: |
58 | |
59 | my $x = try { die "foo" } catch { "bar" }; |
60 | my $x = try { die "foo" } || "bar"; |
61 | my $x = (try { die "foo" }) // "bar"; |
62 | |
63 | my $x = eval { die "foo" } || "bar"; |
64 | |
65 | You can add C<finally> blocks, yielding the following: |
66 | |
67 | my $x; |
68 | try { die 'foo' } finally { $x = 'bar' }; |
69 | try { die 'foo' } catch { warn "Got a die: $_" } finally { $x = 'bar' }; |
70 | |
71 | C<finally> blocks are always executed making them suitable for cleanup code |
72 | which cannot be handled using local. You can add as many C<finally> blocks to a |
73 | given C<try> block as you like. |
74 | |
75 | Note that adding a C<finally> block without a preceding C<catch> block |
76 | suppresses any errors. This behaviour is consistent with using a standalone |
77 | C<eval>, but it is not consistent with C<try>/C<finally> patterns found in |
78 | other programming languages, such as Java, Python, Javascript or C#. If you |
0a844ed9 |
79 | learned the C<try>/C<finally> pattern from one of these languages, watch out for |
cb57845a |
80 | this. |
81 | |
82 | =head1 EXPORTS |
83 | |
84 | All functions are exported by default using L<Exporter>. |
85 | |
86 | If you need to rename the C<try>, C<catch> or C<finally> keyword consider using |
87 | L<Sub::Import> to get L<Sub::Exporter>'s flexibility. |
88 | |
89 | =over 4 |
90 | |
91 | =item try (&;@) |
92 | |
93 | Takes one mandatory C<try> subroutine, an optional C<catch> subroutine and C<finally> |
94 | subroutine. |
95 | |
96 | The mandatory subroutine is evaluated in the context of an C<eval> block. |
97 | |
98 | If no error occurred the value from the first block is returned, preserving |
99 | list/scalar context. |
100 | |
101 | If there was an error and the second subroutine was given it will be invoked |
102 | with the error in C<$_> (localized) and as that block's first and only |
103 | argument. |
104 | |
105 | C<$@> does B<not> contain the error. Inside the C<catch> block it has the same |
106 | value it had before the C<try> block was executed. |
107 | |
108 | Note that the error may be false, but if that happens the C<catch> block will |
109 | still be invoked. |
110 | |
111 | Once all execution is finished then the C<finally> block, if given, will execute. |
112 | |
113 | =item catch (&;@) |
114 | |
115 | Intended to be used in the second argument position of C<try>. |
116 | |
117 | Returns a reference to the subroutine it was given but blessed as |
118 | C<Try::Tiny::Catch> which allows try to decode correctly what to do |
119 | with this code reference. |
120 | |
121 | catch { ... } |
122 | |
123 | Inside the C<catch> block the caught error is stored in C<$_>, while previous |
124 | value of C<$@> is still available for use. This value may or may not be |
125 | meaningful depending on what happened before the C<try>, but it might be a good |
126 | idea to preserve it in an error stack. |
127 | |
128 | For code that captures C<$@> when throwing new errors (i.e. |
129 | L<Class::Throwable>), you'll need to do: |
130 | |
131 | local $@ = $_; |
132 | |
133 | =item finally (&;@) |
134 | |
135 | try { ... } |
136 | catch { ... } |
137 | finally { ... }; |
138 | |
139 | Or |
140 | |
141 | try { ... } |
142 | finally { ... }; |
143 | |
144 | Or even |
145 | |
146 | try { ... } |
147 | finally { ... } |
148 | catch { ... }; |
149 | |
150 | Intended to be the second or third element of C<try>. C<finally> blocks are always |
151 | executed in the event of a successful C<try> or if C<catch> is run. This allows |
152 | you to locate cleanup code which cannot be done via C<local()> e.g. closing a file |
153 | handle. |
154 | |
155 | When invoked, the C<finally> block is passed the error that was caught. If no |
156 | error was caught, it is passed nothing. (Note that the C<finally> block does not |
157 | localize C<$_> with the error, since unlike in a C<catch> block, there is no way |
158 | to know if C<$_ == undef> implies that there were no errors.) In other words, |
159 | the following code does just what you would expect: |
160 | |
161 | try { |
162 | die_sometimes(); |
163 | } catch { |
164 | # ...code run in case of error |
165 | } finally { |
166 | if (@_) { |
167 | print "The try block died with: @_\n"; |
168 | } else { |
169 | print "The try block ran without error.\n"; |
170 | } |
171 | }; |
172 | |
173 | B<You must always do your own error handling in the C<finally> block>. C<Try::Tiny> will |
174 | not do anything about handling possible errors coming from code located in these |
175 | blocks. |
176 | |
177 | Furthermore B<exceptions in C<finally> blocks are not trappable and are unable |
178 | to influence the execution of your program>. This is due to limitation of |
179 | C<DESTROY>-based scope guards, which C<finally> is implemented on top of. This |
180 | may change in a future version of Try::Tiny. |
181 | |
182 | In the same way C<catch()> blesses the code reference this subroutine does the same |
183 | except it bless them as C<Try::Tiny::Finally>. |
184 | |
185 | =back |
186 | |
187 | =head1 BACKGROUND |
188 | |
189 | There are a number of issues with C<eval>. |
190 | |
191 | =head2 Clobbering $@ |
192 | |
193 | When you run an C<eval> block and it succeeds, C<$@> will be cleared, potentially |
194 | clobbering an error that is currently being caught. |
195 | |
196 | This causes action at a distance, clearing previous errors your caller may have |
197 | not yet handled. |
198 | |
199 | C<$@> must be properly localized before invoking C<eval> in order to avoid this |
200 | issue. |
201 | |
5aa01536 |
202 | More specifically, |
203 | L<before Perl version 5.14.0|perl5140delta/"Exception Handling"> |
204 | C<$@> was clobbered at the beginning of the C<eval>, which |
205 | also made it impossible to capture the previous error before you die (for |
cb57845a |
206 | instance when making exception objects with error stacks). |
207 | |
208 | For this reason C<try> will actually set C<$@> to its previous value (the one |
209 | available before entering the C<try> block) in the beginning of the C<eval> |
210 | block. |
211 | |
212 | =head2 Localizing $@ silently masks errors |
213 | |
214 | Inside an C<eval> block, C<die> behaves sort of like: |
215 | |
216 | sub die { |
217 | $@ = $_[0]; |
218 | return_undef_from_eval(); |
219 | } |
220 | |
221 | This means that if you were polite and localized C<$@> you can't die in that |
222 | scope, or your error will be discarded (printing "Something's wrong" instead). |
223 | |
224 | The workaround is very ugly: |
225 | |
226 | my $error = do { |
227 | local $@; |
228 | eval { ... }; |
229 | $@; |
230 | }; |
231 | |
232 | ... |
233 | die $error; |
234 | |
235 | =head2 $@ might not be a true value |
236 | |
237 | This code is wrong: |
238 | |
239 | if ( $@ ) { |
240 | ... |
241 | } |
242 | |
243 | because due to the previous caveats it may have been unset. |
244 | |
245 | C<$@> could also be an overloaded error object that evaluates to false, but |
246 | that's asking for trouble anyway. |
247 | |
5aa01536 |
248 | The classic failure mode (fixed in L<Perl 5.14.0|perl5140delta/"Exception Handling">) is: |
cb57845a |
249 | |
250 | sub Object::DESTROY { |
251 | eval { ... } |
252 | } |
253 | |
254 | eval { |
255 | my $obj = Object->new; |
256 | |
257 | die "foo"; |
258 | }; |
259 | |
260 | if ( $@ ) { |
261 | |
262 | } |
263 | |
264 | In this case since C<Object::DESTROY> is not localizing C<$@> but still uses |
265 | C<eval>, it will set C<$@> to C<"">. |
266 | |
267 | The destructor is called when the stack is unwound, after C<die> sets C<$@> to |
268 | C<"foo at Foo.pm line 42\n">, so by the time C<if ( $@ )> is evaluated it has |
269 | been cleared by C<eval> in the destructor. |
270 | |
271 | The workaround for this is even uglier than the previous ones. Even though we |
272 | can't save the value of C<$@> from code that doesn't localize, we can at least |
273 | be sure the C<eval> was aborted due to an error: |
274 | |
275 | my $failed = not eval { |
276 | ... |
277 | |
278 | return 1; |
279 | }; |
280 | |
281 | This is because an C<eval> that caught a C<die> will always return a false |
282 | value. |
283 | |
5aa01536 |
284 | =head1 ALTERNATE SYNTAX |
cb57845a |
285 | |
5aa01536 |
286 | Using Perl 5.10 you can use L<perlsyn/"Switch statements"> (but please don't, |
287 | because that syntax has since been deprecated because there was too much |
288 | unexpected magical behaviour). |
cb57845a |
289 | |
290 | =for stopwords topicalizer |
291 | |
292 | The C<catch> block is invoked in a topicalizer context (like a C<given> block), |
293 | but note that you can't return a useful value from C<catch> using the C<when> |
294 | blocks without an explicit C<return>. |
295 | |
296 | This is somewhat similar to Perl 6's C<CATCH> blocks. You can use it to |
297 | concisely match errors: |
298 | |
299 | try { |
300 | require Foo; |
301 | } catch { |
302 | when (/^Can't locate .*?\.pm in \@INC/) { } # ignore |
303 | default { die $_ } |
304 | }; |
305 | |
306 | =head1 CAVEATS |
307 | |
308 | =over 4 |
309 | |
310 | =item * |
311 | |
312 | C<@_> is not available within the C<try> block, so you need to copy your |
313 | argument list. In case you want to work with argument values directly via C<@_> |
314 | aliasing (i.e. allow C<$_[1] = "foo">), you need to pass C<@_> by reference: |
315 | |
316 | sub foo { |
317 | my ( $self, @args ) = @_; |
318 | try { $self->bar(@args) } |
319 | } |
320 | |
321 | or |
322 | |
323 | sub bar_in_place { |
324 | my $self = shift; |
325 | my $args = \@_; |
326 | try { $_ = $self->bar($_) for @$args } |
327 | } |
328 | |
329 | =item * |
330 | |
331 | C<return> returns from the C<try> block, not from the parent sub (note that |
332 | this is also how C<eval> works, but not how L<TryCatch> works): |
333 | |
334 | sub parent_sub { |
335 | try { |
336 | die; |
337 | } |
338 | catch { |
339 | return; |
340 | }; |
341 | |
342 | say "this text WILL be displayed, even though an exception is thrown"; |
343 | } |
344 | |
345 | Instead, you should capture the return value: |
346 | |
347 | sub parent_sub { |
348 | my $success = try { |
349 | die; |
350 | 1; |
351 | }; |
352 | return unless $success; |
353 | |
354 | say "This text WILL NEVER appear!"; |
355 | } |
356 | # OR |
357 | sub parent_sub_with_catch { |
358 | my $success = try { |
359 | die; |
360 | 1; |
361 | } |
362 | catch { |
363 | # do something with $_ |
364 | return undef; #see note |
365 | }; |
366 | return unless $success; |
367 | |
368 | say "This text WILL NEVER appear!"; |
369 | } |
370 | |
371 | Note that if you have a C<catch> block, it must return C<undef> for this to work, |
372 | since if a C<catch> block exists, its return value is returned in place of C<undef> |
373 | when an exception is thrown. |
374 | |
375 | =item * |
376 | |
377 | C<try> introduces another caller stack frame. L<Sub::Uplevel> is not used. L<Carp> |
378 | will not report this when using full stack traces, though, because |
379 | C<%Carp::Internal> is used. This lack of magic is considered a feature. |
380 | |
381 | =for stopwords unhygienically |
382 | |
383 | =item * |
384 | |
385 | The value of C<$_> in the C<catch> block is not guaranteed to be the value of |
386 | the exception thrown (C<$@>) in the C<try> block. There is no safe way to |
387 | ensure this, since C<eval> may be used unhygienically in destructors. The only |
388 | guarantee is that the C<catch> will be called if an exception is thrown. |
389 | |
390 | =item * |
391 | |
392 | The return value of the C<catch> block is not ignored, so if testing the result |
393 | of the expression for truth on success, be sure to return a false value from |
394 | the C<catch> block: |
395 | |
396 | my $obj = try { |
397 | MightFail->new; |
398 | } catch { |
399 | ... |
400 | |
401 | return; # avoid returning a true value; |
402 | }; |
403 | |
404 | return unless $obj; |
405 | |
406 | =item * |
407 | |
408 | C<$SIG{__DIE__}> is still in effect. |
409 | |
410 | Though it can be argued that C<$SIG{__DIE__}> should be disabled inside of |
411 | C<eval> blocks, since it isn't people have grown to rely on it. Therefore in |
412 | the interests of compatibility, C<try> does not disable C<$SIG{__DIE__}> for |
413 | the scope of the error throwing code. |
414 | |
415 | =item * |
416 | |
417 | Lexical C<$_> may override the one set by C<catch>. |
418 | |
419 | For example Perl 5.10's C<given> form uses a lexical C<$_>, creating some |
420 | confusing behavior: |
421 | |
422 | given ($foo) { |
423 | when (...) { |
424 | try { |
425 | ... |
426 | } catch { |
427 | warn $_; # will print $foo, not the error |
428 | warn $_[0]; # instead, get the error like this |
429 | } |
430 | } |
431 | } |
432 | |
5aa01536 |
433 | Note that this behavior was changed once again in |
434 | L<Perl5 version 18|https://metacpan.org/module/perldelta#given-now-aliases-the-global-_>. |
cb57845a |
435 | However, since the entirety of lexical C<$_> is now L<considered experimental |
436 | |https://metacpan.org/module/perldelta#Lexical-_-is-now-experimental>, it |
437 | is unclear whether the new version 18 behavior is final. |
438 | |
439 | =back |
440 | |
441 | =head1 SEE ALSO |
442 | |
443 | =over 4 |
444 | |
0a844ed9 |
445 | =item L<Syntax::Keyword::Try> |
446 | |
447 | Only available on perls >= 5.14, with a slightly different syntax (e.g. no trailing C<;> because |
448 | it's actually a keyword, not a sub, but this means you can C<return> and C<next> within it). Use |
449 | L<Feature::Compat::Try> to automatically switch to the native C<try> syntax in newer perls (when |
450 | available). See also L<Try Catch Exception Handling|perlsyn/Try-Catch-Exception-Handling>. |
451 | |
cb57845a |
452 | =item L<TryCatch> |
453 | |
454 | Much more feature complete, more convenient semantics, but at the cost of |
455 | implementation complexity. |
456 | |
457 | =item L<autodie> |
458 | |
459 | Automatic error throwing for builtin functions and more. Also designed to |
460 | work well with C<given>/C<when>. |
461 | |
462 | =item L<Throwable> |
463 | |
464 | A lightweight role for rolling your own exception classes. |
465 | |
466 | =item L<Error> |
467 | |
468 | Exception object implementation with a C<try> statement. Does not localize |
469 | C<$@>. |
470 | |
471 | =item L<Exception::Class::TryCatch> |
472 | |
473 | Provides a C<catch> statement, but properly calling C<eval> is your |
474 | responsibility. |
475 | |
476 | The C<try> keyword pushes C<$@> onto an error stack, avoiding some of the |
477 | issues with C<$@>, but you still need to localize to prevent clobbering. |
478 | |
479 | =back |
480 | |
481 | =head1 LIGHTNING TALK |
482 | |
483 | I gave a lightning talk about this module, you can see the slides (Firefox |
484 | only): |
485 | |
486 | L<http://web.archive.org/web/20100628040134/http://nothingmuch.woobling.org/talks/takahashi.xul> |
487 | |
488 | Or read the source: |
489 | |
490 | L<http://web.archive.org/web/20100305133605/http://nothingmuch.woobling.org/talks/yapc_asia_2009/try_tiny.yml> |
491 | |
cb57845a |
492 | =head1 SUPPORT |
493 | |
494 | Bugs may be submitted through L<the RT bug tracker|https://rt.cpan.org/Public/Dist/Display.html?Name=Try-Tiny> |
495 | (or L<bug-Try-Tiny@rt.cpan.org|mailto:bug-Try-Tiny@rt.cpan.org>). |
496 | |
497 | =head1 AUTHORS |
498 | |
499 | =over 4 |
500 | |
501 | =item * |
502 | |
503 | יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org> |
504 | |
505 | =item * |
506 | |
507 | Jesse Luehrs <doy@tozt.net> |
508 | |
509 | =back |
510 | |
511 | =head1 CONTRIBUTORS |
512 | |
0a844ed9 |
513 | =for stopwords Karen Etheridge Peter Rabbitson Ricardo Signes Mark Fowler Graham Knop Aristotle Pagaltzis Dagfinn Ilmari Mannsåker Lukas Mai Alex anaxagoras Andrew Yates awalker chromatic cm-perl David Lowe Glenn Hans Dieter Pearcey Jens Berthold Jonathan Yu Marc Mims Stosberg Pali Paul Howarth Rudolf Leermakers |
cb57845a |
514 | |
515 | =over 4 |
516 | |
517 | =item * |
518 | |
08068486 |
519 | Karen Etheridge <ether@cpan.org> |
cb57845a |
520 | |
521 | =item * |
522 | |
08068486 |
523 | Peter Rabbitson <ribasushi@cpan.org> |
cb57845a |
524 | |
525 | =item * |
526 | |
527 | Ricardo Signes <rjbs@cpan.org> |
528 | |
529 | =item * |
530 | |
531 | Mark Fowler <mark@twoshortplanks.com> |
532 | |
533 | =item * |
534 | |
535 | Graham Knop <haarg@haarg.org> |
536 | |
537 | =item * |
538 | |
5aa01536 |
539 | Aristotle Pagaltzis <pagaltzis@gmx.de> |
540 | |
541 | =item * |
542 | |
a3769675 |
543 | Dagfinn Ilmari Mannsåker <ilmari@ilmari.org> |
cb57845a |
544 | |
545 | =item * |
546 | |
0a844ed9 |
547 | Lukas Mai <l.mai@web.de> |
fae6bce6 |
548 | |
549 | =item * |
550 | |
0a844ed9 |
551 | Alex <alex@koban.(none)> |
cb57845a |
552 | |
553 | =item * |
554 | |
555 | anaxagoras <walkeraj@gmail.com> |
556 | |
557 | =item * |
558 | |
0a844ed9 |
559 | Andrew Yates <ayates@haddock.local> |
cb57845a |
560 | |
561 | =item * |
562 | |
0a844ed9 |
563 | awalker <awalker@sourcefire.com> |
cb57845a |
564 | |
565 | =item * |
566 | |
0a844ed9 |
567 | chromatic <chromatic@wgz.org> |
cb57845a |
568 | |
569 | =item * |
570 | |
571 | cm-perl <cm-perl@users.noreply.github.com> |
572 | |
573 | =item * |
574 | |
cb57845a |
575 | David Lowe <davidl@lokku.com> |
576 | |
577 | =item * |
578 | |
579 | Glenn Fowler <cebjyre@cpan.org> |
580 | |
581 | =item * |
582 | |
583 | Hans Dieter Pearcey <hdp@weftsoar.net> |
584 | |
585 | =item * |
586 | |
5aa01536 |
587 | Jens Berthold <jens@jebecs.de> |
588 | |
589 | =item * |
590 | |
cb57845a |
591 | Jonathan Yu <JAWNSY@cpan.org> |
592 | |
593 | =item * |
594 | |
595 | Marc Mims <marc@questright.com> |
596 | |
597 | =item * |
598 | |
599 | Mark Stosberg <mark@stosberg.com> |
600 | |
a3769675 |
601 | =item * |
602 | |
fae6bce6 |
603 | Pali <pali@cpan.org> |
a3769675 |
604 | |
0a844ed9 |
605 | =item * |
606 | |
607 | Paul Howarth <paul@city-fan.org> |
608 | |
609 | =item * |
610 | |
611 | Rudolf Leermakers <rudolf@hatsuseno.org> |
612 | |
cb57845a |
613 | =back |
614 | |
615 | =head1 COPYRIGHT AND LICENCE |
616 | |
617 | This software is Copyright (c) 2009 by יובל קוג'מן (Yuval Kogman). |
618 | |
619 | This is free software, licensed under: |
620 | |
621 | The MIT (X11) License |
622 | |
623 | =cut |