Commit | Line | Data |
8e50c419 |
1 | # PAUSE doesn't seem to case about this in t/role-basic/lib, but just in case ... |
2 | package # Hide from PAUSE |
3 | Try::Tiny; |
4 | |
5 | use strict; |
6 | #use warnings; |
7 | |
8 | use vars qw(@EXPORT @EXPORT_OK $VERSION @ISA); |
9 | |
10 | BEGIN { |
11 | require Exporter; |
12 | @ISA = qw(Exporter); |
13 | } |
14 | |
15 | $VERSION = "0.09"; |
16 | |
17 | $VERSION = eval $VERSION; |
18 | |
19 | @EXPORT = @EXPORT_OK = qw(try catch finally); |
20 | |
21 | $Carp::Internal{+__PACKAGE__}++; |
22 | |
23 | # Need to prototype as @ not $$ because of the way Perl evaluates the prototype. |
24 | # Keeping it at $$ means you only ever get 1 sub because we need to eval in a list |
25 | # context & not a scalar one |
26 | |
27 | sub try (&;@) { |
28 | my ( $try, @code_refs ) = @_; |
29 | |
30 | # we need to save this here, the eval block will be in scalar context due |
31 | # to $failed |
32 | my $wantarray = wantarray; |
33 | |
34 | my ( $catch, @finally ); |
35 | |
36 | # find labeled blocks in the argument list. |
37 | # catch and finally tag the blocks by blessing a scalar reference to them. |
38 | foreach my $code_ref (@code_refs) { |
39 | next unless $code_ref; |
40 | |
41 | my $ref = ref($code_ref); |
42 | |
43 | if ( $ref eq 'Try::Tiny::Catch' ) { |
44 | $catch = ${$code_ref}; |
45 | } elsif ( $ref eq 'Try::Tiny::Finally' ) { |
46 | push @finally, ${$code_ref}; |
47 | } else { |
48 | use Carp; |
49 | confess("Unknown code ref type given '${ref}'. Check your usage & try again"); |
50 | } |
51 | } |
52 | |
53 | # save the value of $@ so we can set $@ back to it in the beginning of the eval |
54 | my $prev_error = $@; |
55 | |
56 | my ( @ret, $error, $failed ); |
57 | |
58 | # FIXME consider using local $SIG{__DIE__} to accumulate all errors. It's |
59 | # not perfect, but we could provide a list of additional errors for |
60 | # $catch->(); |
61 | |
62 | { |
63 | # localize $@ to prevent clobbering of previous value by a successful |
64 | # eval. |
65 | local $@; |
66 | |
67 | # failed will be true if the eval dies, because 1 will not be returned |
68 | # from the eval body |
69 | $failed = not eval { |
70 | $@ = $prev_error; |
71 | |
72 | # evaluate the try block in the correct context |
73 | if ( $wantarray ) { |
74 | @ret = $try->(); |
75 | } elsif ( defined $wantarray ) { |
76 | $ret[0] = $try->(); |
77 | } else { |
78 | $try->(); |
79 | }; |
80 | |
81 | return 1; # properly set $fail to false |
82 | }; |
83 | |
84 | # copy $@ to $error; when we leave this scope, local $@ will revert $@ |
85 | # back to its previous value |
86 | $error = $@; |
87 | } |
88 | |
89 | # set up a scope guard to invoke the finally block at the end |
90 | my @guards = |
91 | map { Try::Tiny::ScopeGuard->_new($_, $failed ? $error : ()) } |
92 | @finally; |
93 | |
94 | # at this point $failed contains a true value if the eval died, even if some |
95 | # destructor overwrote $@ as the eval was unwinding. |
96 | if ( $failed ) { |
97 | # if we got an error, invoke the catch block. |
98 | if ( $catch ) { |
99 | # This works like given($error), but is backwards compatible and |
100 | # sets $_ in the dynamic scope for the body of C<$catch> |
101 | for ($error) { |
102 | return $catch->($error); |
103 | } |
104 | |
105 | # in case when() was used without an explicit return, the C<for> |
106 | # loop will be aborted and there's no useful return value |
107 | } |
108 | |
109 | return; |
110 | } else { |
111 | # no failure, $@ is back to what it was, everything is fine |
112 | return $wantarray ? @ret : $ret[0]; |
113 | } |
114 | } |
115 | |
116 | sub catch (&;@) { |
117 | my ( $block, @rest ) = @_; |
118 | |
119 | return ( |
120 | bless(\$block, 'Try::Tiny::Catch'), |
121 | @rest, |
122 | ); |
123 | } |
124 | |
125 | sub finally (&;@) { |
126 | my ( $block, @rest ) = @_; |
127 | |
128 | return ( |
129 | bless(\$block, 'Try::Tiny::Finally'), |
130 | @rest, |
131 | ); |
132 | } |
133 | |
134 | { |
135 | package # hide from PAUSE |
136 | Try::Tiny::ScopeGuard; |
137 | |
138 | sub _new { |
139 | shift; |
140 | bless [ @_ ]; |
141 | } |
142 | |
143 | sub DESTROY { |
144 | my @guts = @{ shift() }; |
145 | my $code = shift @guts; |
146 | $code->(@guts); |
147 | } |
148 | } |
149 | |
150 | __PACKAGE__ |
151 | |
152 | __END__ |
153 | |
154 | =pod |
155 | |
156 | =head1 NAME |
157 | |
158 | Try::Tiny - minimal try/catch with proper localization of $@ |
159 | |
160 | =head1 SYNOPSIS |
161 | |
162 | # handle errors with a catch handler |
163 | try { |
164 | die "foo"; |
165 | } catch { |
166 | warn "caught error: $_"; # not $@ |
167 | }; |
168 | |
169 | # just silence errors |
170 | try { |
171 | die "foo"; |
172 | }; |
173 | |
174 | =head1 DESCRIPTION |
175 | |
176 | This module provides bare bones C<try>/C<catch>/C<finally> statements that are designed to |
177 | minimize common mistakes with eval blocks, and NOTHING else. |
178 | |
179 | This is unlike L<TryCatch> which provides a nice syntax and avoids adding |
180 | another call stack layer, and supports calling C<return> from the try block to |
181 | return from the parent subroutine. These extra features come at a cost of a few |
182 | dependencies, namely L<Devel::Declare> and L<Scope::Upper> which are |
183 | occasionally problematic, and the additional catch filtering uses L<Moose> |
184 | type constraints which may not be desirable either. |
185 | |
186 | The main focus of this module is to provide simple and reliable error handling |
187 | for those having a hard time installing L<TryCatch>, but who still want to |
188 | write correct C<eval> blocks without 5 lines of boilerplate each time. |
189 | |
190 | It's designed to work as correctly as possible in light of the various |
191 | pathological edge cases (see L<BACKGROUND>) and to be compatible with any style |
192 | of error values (simple strings, references, objects, overloaded objects, etc). |
193 | |
194 | If the try block dies, it returns the value of the last statement executed in |
195 | the catch block, if there is one. Otherwise, it returns C<undef> in scalar |
196 | context or the empty list in list context. The following two examples both |
197 | assign C<"bar"> to C<$x>. |
198 | |
199 | my $x = try { die "foo" } catch { "bar" }; |
200 | |
201 | my $x = eval { die "foo" } || "bar"; |
202 | |
203 | You can add finally blocks making the following true. |
204 | |
205 | my $x; |
206 | try { die 'foo' } finally { $x = 'bar' }; |
207 | try { die 'foo' } catch { warn "Got a die: $_" } finally { $x = 'bar' }; |
208 | |
209 | Finally blocks are always executed making them suitable for cleanup code |
210 | which cannot be handled using local. You can add as many finally blocks to a |
211 | given try block as you like. |
212 | |
213 | =head1 EXPORTS |
214 | |
215 | All functions are exported by default using L<Exporter>. |
216 | |
217 | If you need to rename the C<try>, C<catch> or C<finally> keyword consider using |
218 | L<Sub::Import> to get L<Sub::Exporter>'s flexibility. |
219 | |
220 | =over 4 |
221 | |
222 | =item try (&;@) |
223 | |
224 | Takes one mandatory try subroutine, an optional catch subroutine & finally |
225 | subroutine. |
226 | |
227 | The mandatory subroutine is evaluated in the context of an C<eval> block. |
228 | |
229 | If no error occurred the value from the first block is returned, preserving |
230 | list/scalar context. |
231 | |
232 | If there was an error and the second subroutine was given it will be invoked |
233 | with the error in C<$_> (localized) and as that block's first and only |
234 | argument. |
235 | |
236 | C<$@> does B<not> contain the error. Inside the C<catch> block it has the same |
237 | value it had before the C<try> block was executed. |
238 | |
239 | Note that the error may be false, but if that happens the C<catch> block will |
240 | still be invoked. |
241 | |
242 | Once all execution is finished then the finally block if given will execute. |
243 | |
244 | =item catch (&;$) |
245 | |
246 | Intended to be used in the second argument position of C<try>. |
247 | |
248 | Returns a reference to the subroutine it was given but blessed as |
249 | C<Try::Tiny::Catch> which allows try to decode correctly what to do |
250 | with this code reference. |
251 | |
252 | catch { ... } |
253 | |
254 | Inside the catch block the caught error is stored in C<$_>, while previous |
255 | value of C<$@> is still available for use. This value may or may not be |
256 | meaningful depending on what happened before the C<try>, but it might be a good |
257 | idea to preserve it in an error stack. |
258 | |
259 | For code that captures C<$@> when throwing new errors (i.e. |
260 | L<Class::Throwable>), you'll need to do: |
261 | |
262 | local $@ = $_; |
263 | |
264 | =item finally (&;$) |
265 | |
266 | try { ... } |
267 | catch { ... } |
268 | finally { ... }; |
269 | |
270 | Or |
271 | |
272 | try { ... } |
273 | finally { ... }; |
274 | |
275 | Or even |
276 | |
277 | try { ... } |
278 | finally { ... } |
279 | catch { ... }; |
280 | |
281 | Intended to be the second or third element of C<try>. Finally blocks are always |
282 | executed in the event of a successful C<try> or if C<catch> is run. This allows |
283 | you to locate cleanup code which cannot be done via C<local()> e.g. closing a file |
284 | handle. |
285 | |
286 | When invoked, the finally block is passed the error that was caught. If no |
287 | error was caught, it is passed nothing. In other words, the following code |
288 | does just what you would expect: |
289 | |
290 | try { |
291 | die_sometimes(); |
292 | } catch { |
293 | # ...code run in case of error |
294 | } finally { |
295 | if (@_) { |
296 | print "The try block died with: @_\n"; |
297 | } else { |
298 | print "The try block ran without error.\n"; |
299 | } |
300 | }; |
301 | |
302 | B<You must always do your own error handling in the finally block>. C<Try::Tiny> will |
303 | not do anything about handling possible errors coming from code located in these |
304 | blocks. |
305 | |
306 | In the same way C<catch()> blesses the code reference this subroutine does the same |
307 | except it bless them as C<Try::Tiny::Finally>. |
308 | |
309 | =back |
310 | |
311 | =head1 BACKGROUND |
312 | |
313 | There are a number of issues with C<eval>. |
314 | |
315 | =head2 Clobbering $@ |
316 | |
317 | When you run an eval block and it succeeds, C<$@> will be cleared, potentially |
318 | clobbering an error that is currently being caught. |
319 | |
320 | This causes action at a distance, clearing previous errors your caller may have |
321 | not yet handled. |
322 | |
323 | C<$@> must be properly localized before invoking C<eval> in order to avoid this |
324 | issue. |
325 | |
326 | More specifically, C<$@> is clobbered at the beginning of the C<eval>, which |
327 | also makes it impossible to capture the previous error before you die (for |
328 | instance when making exception objects with error stacks). |
329 | |
330 | For this reason C<try> will actually set C<$@> to its previous value (before |
331 | the localization) in the beginning of the C<eval> block. |
332 | |
333 | =head2 Localizing $@ silently masks errors |
334 | |
335 | Inside an eval block C<die> behaves sort of like: |
336 | |
337 | sub die { |
338 | $@ = $_[0]; |
339 | return_undef_from_eval(); |
340 | } |
341 | |
342 | This means that if you were polite and localized C<$@> you can't die in that |
343 | scope, or your error will be discarded (printing "Something's wrong" instead). |
344 | |
345 | The workaround is very ugly: |
346 | |
347 | my $error = do { |
348 | local $@; |
349 | eval { ... }; |
350 | $@; |
351 | }; |
352 | |
353 | ... |
354 | die $error; |
355 | |
356 | =head2 $@ might not be a true value |
357 | |
358 | This code is wrong: |
359 | |
360 | if ( $@ ) { |
361 | ... |
362 | } |
363 | |
364 | because due to the previous caveats it may have been unset. |
365 | |
366 | C<$@> could also be an overloaded error object that evaluates to false, but |
367 | that's asking for trouble anyway. |
368 | |
369 | The classic failure mode is: |
370 | |
371 | sub Object::DESTROY { |
372 | eval { ... } |
373 | } |
374 | |
375 | eval { |
376 | my $obj = Object->new; |
377 | |
378 | die "foo"; |
379 | }; |
380 | |
381 | if ( $@ ) { |
382 | |
383 | } |
384 | |
385 | In this case since C<Object::DESTROY> is not localizing C<$@> but still uses |
386 | C<eval>, it will set C<$@> to C<"">. |
387 | |
388 | The destructor is called when the stack is unwound, after C<die> sets C<$@> to |
389 | C<"foo at Foo.pm line 42\n">, so by the time C<if ( $@ )> is evaluated it has |
390 | been cleared by C<eval> in the destructor. |
391 | |
392 | The workaround for this is even uglier than the previous ones. Even though we |
393 | can't save the value of C<$@> from code that doesn't localize, we can at least |
394 | be sure the eval was aborted due to an error: |
395 | |
396 | my $failed = not eval { |
397 | ... |
398 | |
399 | return 1; |
400 | }; |
401 | |
402 | This is because an C<eval> that caught a C<die> will always return a false |
403 | value. |
404 | |
405 | =head1 SHINY SYNTAX |
406 | |
407 | Using Perl 5.10 you can use L<perlsyn/"Switch statements">. |
408 | |
409 | The C<catch> block is invoked in a topicalizer context (like a C<given> block), |
410 | but note that you can't return a useful value from C<catch> using the C<when> |
411 | blocks without an explicit C<return>. |
412 | |
413 | This is somewhat similar to Perl 6's C<CATCH> blocks. You can use it to |
414 | concisely match errors: |
415 | |
416 | try { |
417 | require Foo; |
418 | } catch { |
419 | when (/^Can't locate .*?\.pm in \@INC/) { } # ignore |
420 | default { die $_ } |
421 | }; |
422 | |
423 | =head1 CAVEATS |
424 | |
425 | =over 4 |
426 | |
427 | =item * |
428 | |
429 | C<@_> is not available within the C<try> block, so you need to copy your |
430 | arglist. In case you want to work with argument values directly via C<@_> |
431 | aliasing (i.e. allow C<$_[1] = "foo">), you need to pass C<@_> by reference: |
432 | |
433 | sub foo { |
434 | my ( $self, @args ) = @_; |
435 | try { $self->bar(@args) } |
436 | } |
437 | |
438 | or |
439 | |
440 | sub bar_in_place { |
441 | my $self = shift; |
442 | my $args = \@_; |
443 | try { $_ = $self->bar($_) for @$args } |
444 | } |
445 | |
446 | =item * |
447 | |
448 | C<return> returns from the C<try> block, not from the parent sub (note that |
449 | this is also how C<eval> works, but not how L<TryCatch> works): |
450 | |
451 | sub bar { |
452 | try { return "foo" }; |
453 | return "baz"; |
454 | } |
455 | |
456 | say bar(); # "baz" |
457 | |
458 | =item * |
459 | |
460 | C<try> introduces another caller stack frame. L<Sub::Uplevel> is not used. L<Carp> |
461 | will not report this when using full stack traces, though, because |
462 | C<%Carp::Internal> is used. This lack of magic is considered a feature. |
463 | |
464 | =item * |
465 | |
466 | The value of C<$_> in the C<catch> block is not guaranteed to be the value of |
467 | the exception thrown (C<$@>) in the C<try> block. There is no safe way to |
468 | ensure this, since C<eval> may be used unhygenically in destructors. The only |
469 | guarantee is that the C<catch> will be called if an exception is thrown. |
470 | |
471 | =item * |
472 | |
473 | The return value of the C<catch> block is not ignored, so if testing the result |
474 | of the expression for truth on success, be sure to return a false value from |
475 | the C<catch> block: |
476 | |
477 | my $obj = try { |
478 | MightFail->new; |
479 | } catch { |
480 | ... |
481 | |
482 | return; # avoid returning a true value; |
483 | }; |
484 | |
485 | return unless $obj; |
486 | |
487 | =item * |
488 | |
489 | C<$SIG{__DIE__}> is still in effect. |
490 | |
491 | Though it can be argued that C<$SIG{__DIE__}> should be disabled inside of |
492 | C<eval> blocks, since it isn't people have grown to rely on it. Therefore in |
493 | the interests of compatibility, C<try> does not disable C<$SIG{__DIE__}> for |
494 | the scope of the error throwing code. |
495 | |
496 | =item * |
497 | |
498 | Lexical C<$_> may override the one set by C<catch>. |
499 | |
500 | For example Perl 5.10's C<given> form uses a lexical C<$_>, creating some |
501 | confusing behavior: |
502 | |
503 | given ($foo) { |
504 | when (...) { |
505 | try { |
506 | ... |
507 | } catch { |
508 | warn $_; # will print $foo, not the error |
509 | warn $_[0]; # instead, get the error like this |
510 | } |
511 | } |
512 | } |
513 | |
514 | =back |
515 | |
516 | =head1 SEE ALSO |
517 | |
518 | =over 4 |
519 | |
520 | =item L<TryCatch> |
521 | |
522 | Much more feature complete, more convenient semantics, but at the cost of |
523 | implementation complexity. |
524 | |
525 | =item L<autodie> |
526 | |
527 | Automatic error throwing for builtin functions and more. Also designed to |
528 | work well with C<given>/C<when>. |
529 | |
530 | =item L<Throwable> |
531 | |
532 | A lightweight role for rolling your own exception classes. |
533 | |
534 | =item L<Error> |
535 | |
536 | Exception object implementation with a C<try> statement. Does not localize |
537 | C<$@>. |
538 | |
539 | =item L<Exception::Class::TryCatch> |
540 | |
541 | Provides a C<catch> statement, but properly calling C<eval> is your |
542 | responsibility. |
543 | |
544 | The C<try> keyword pushes C<$@> onto an error stack, avoiding some of the |
545 | issues with C<$@>, but you still need to localize to prevent clobbering. |
546 | |
547 | =back |
548 | |
549 | =head1 LIGHTNING TALK |
550 | |
551 | I gave a lightning talk about this module, you can see the slides (Firefox |
552 | only): |
553 | |
554 | L<http://nothingmuch.woobling.org/talks/takahashi.xul?data=yapc_asia_2009/try_tiny.txt> |
555 | |
556 | Or read the source: |
557 | |
558 | L<http://nothingmuch.woobling.org/talks/yapc_asia_2009/try_tiny.yml> |
559 | |
560 | =head1 VERSION CONTROL |
561 | |
562 | L<http://github.com/nothingmuch/try-tiny/> |
563 | |
564 | =head1 AUTHOR |
565 | |
566 | Yuval Kogman E<lt>nothingmuch@woobling.orgE<gt> |
567 | |
568 | =head1 COPYRIGHT |
569 | |
570 | Copyright (c) 2009 Yuval Kogman. All rights reserved. |
571 | This program is free software; you can redistribute |
572 | it and/or modify it under the terms of the MIT license. |
573 | |
574 | =cut |
575 | |