Commit | Line | Data |
3176feef |
1 | package Try::Tiny; |
12b7dc6c |
2 | use 5.006; |
3 | # ABSTRACT: minimal try/catch with proper preservation of $@ |
3176feef |
4 | |
14a9ccca |
5 | our $VERSION = '0.27'; |
dbb907ac |
6 | |
3176feef |
7 | use strict; |
f9d19a00 |
8 | use warnings; |
3176feef |
9 | |
b4207115 |
10 | use Exporter 5.57 'import'; |
f9d19a00 |
11 | our @EXPORT = our @EXPORT_OK = qw(try catch finally); |
3176feef |
12 | |
f9d19a00 |
13 | use Carp; |
6f114080 |
14 | $Carp::Internal{+__PACKAGE__}++; |
15 | |
2f7f4153 |
16 | BEGIN { |
17 | my $su = $INC{'Sub/Util.pm'} && defined &Sub::Util::set_subname; |
18 | my $sn = $INC{'Sub/Name.pm'} && eval { Sub::Name->VERSION(0.08) }; |
19 | unless ($su || $sn) { |
20 | $su = eval { require Sub::Util; } && defined &Sub::Util::set_subname; |
21 | unless ($su) { |
22 | $sn = eval { require Sub::Name; Sub::Name->VERSION(0.08) }; |
23 | } |
24 | } |
25 | |
26 | *_subname = $su ? \&Sub::Util::set_subname |
27 | : $sn ? \&Sub::Name::subname |
28 | : sub { $_[1] }; |
29 | *_HAS_SUBNAME = ($su || $sn) ? sub(){1} : sub(){0}; |
30 | } |
5c9d800f |
31 | |
7cdef625 |
32 | my %_finally_guards; |
80352025 |
33 | |
7195fc08 |
34 | # Need to prototype as @ not $$ because of the way Perl evaluates the prototype. |
35 | # Keeping it at $$ means you only ever get 1 sub because we need to eval in a list |
36 | # context & not a scalar one |
37 | |
38 | sub try (&;@) { |
8d2ee831 |
39 | my ( $try, @code_refs ) = @_; |
40 | |
41 | # we need to save this here, the eval block will be in scalar context due |
42 | # to $failed |
43 | my $wantarray = wantarray; |
44 | |
130617d9 |
45 | # work around perl bug by explicitly initializing these, due to the likelyhood |
46 | # this will be used in global destruction (perl rt#119311) |
47 | my ( $catch, @finally ) = (); |
8d2ee831 |
48 | |
49 | # find labeled blocks in the argument list. |
50 | # catch and finally tag the blocks by blessing a scalar reference to them. |
51 | foreach my $code_ref (@code_refs) { |
8d2ee831 |
52 | |
4c5b99d6 |
53 | if ( ref($code_ref) eq 'Try::Tiny::Catch' ) { |
9d0e0466 |
54 | croak 'A try() may not be followed by multiple catch() blocks' |
55 | if $catch; |
8d2ee831 |
56 | $catch = ${$code_ref}; |
4c5b99d6 |
57 | } elsif ( ref($code_ref) eq 'Try::Tiny::Finally' ) { |
8d2ee831 |
58 | push @finally, ${$code_ref}; |
59 | } else { |
4c5b99d6 |
60 | croak( |
61 | 'try() encountered an unexpected argument (' |
62 | . ( defined $code_ref ? $code_ref : 'undef' ) |
63 | . ') - perhaps a missing semi-colon before or' |
64 | ); |
8d2ee831 |
65 | } |
66 | } |
67 | |
2b0d579d |
68 | # FIXME consider using local $SIG{__DIE__} to accumulate all errors. It's |
69 | # not perfect, but we could provide a list of additional errors for |
70 | # $catch->(); |
71 | |
5c9d800f |
72 | # name the blocks if we have Sub::Name installed |
1131a831 |
73 | my $caller = caller; |
2f7f4153 |
74 | _subname("${caller}::try {...} " => $try) |
75 | if _HAS_SUBNAME; |
5c9d800f |
76 | |
80352025 |
77 | # set up scope guards to invoke the finally blocks at the end. |
8447a3bf |
78 | # this should really be a function scope lexical variable instead of |
79 | # file scope + local but that causes issues with perls < 5.20 due to |
80 | # perl rt#119311 |
7cdef625 |
81 | local $_finally_guards{guards} = [ |
80352025 |
82 | map { Try::Tiny::ScopeGuard->_new($_) } |
8447a3bf |
83 | @finally |
84 | ]; |
80352025 |
85 | |
8d2ee831 |
86 | # save the value of $@ so we can set $@ back to it in the beginning of the eval |
2b0d579d |
87 | # and restore $@ after the eval finishes |
8d2ee831 |
88 | my $prev_error = $@; |
89 | |
2b0d579d |
90 | my ( @ret, $error ); |
8d2ee831 |
91 | |
2b0d579d |
92 | # failed will be true if the eval dies, because 1 will not be returned |
93 | # from the eval body |
94 | my $failed = not eval { |
95 | $@ = $prev_error; |
8d2ee831 |
96 | |
2b0d579d |
97 | # evaluate the try block in the correct context |
98 | if ( $wantarray ) { |
99 | @ret = $try->(); |
100 | } elsif ( defined $wantarray ) { |
101 | $ret[0] = $try->(); |
102 | } else { |
103 | $try->(); |
8d2ee831 |
104 | }; |
105 | |
f4b28b65 |
106 | return 1; # properly set $failed to false |
3db0dca6 |
107 | }; |
2b0d579d |
108 | |
3db0dca6 |
109 | # preserve the current error and reset the original value of $@ |
110 | $error = $@; |
2b0d579d |
111 | $@ = $prev_error; |
8d2ee831 |
112 | |
8d2ee831 |
113 | # at this point $failed contains a true value if the eval died, even if some |
114 | # destructor overwrote $@ as the eval was unwinding. |
115 | if ( $failed ) { |
80352025 |
116 | # pass $error to the finally blocks |
7cdef625 |
117 | push @$_, $error for @{$_finally_guards{guards}}; |
80352025 |
118 | |
8d2ee831 |
119 | # if we got an error, invoke the catch block. |
120 | if ( $catch ) { |
121 | # This works like given($error), but is backwards compatible and |
122 | # sets $_ in the dynamic scope for the body of C<$catch> |
123 | for ($error) { |
124 | return $catch->($error); |
125 | } |
126 | |
127 | # in case when() was used without an explicit return, the C<for> |
128 | # loop will be aborted and there's no useful return value |
129 | } |
130 | |
131 | return; |
132 | } else { |
133 | # no failure, $@ is back to what it was, everything is fine |
134 | return $wantarray ? @ret : $ret[0]; |
135 | } |
3176feef |
136 | } |
137 | |
7195fc08 |
138 | sub catch (&;@) { |
8d2ee831 |
139 | my ( $block, @rest ) = @_; |
7195fc08 |
140 | |
d2ae14ad |
141 | croak 'Useless bare catch()' unless wantarray; |
9d0e0466 |
142 | |
2f7f4153 |
143 | my $caller = caller; |
144 | _subname("${caller}::catch {...} " => $block) |
145 | if _HAS_SUBNAME; |
8d2ee831 |
146 | return ( |
147 | bless(\$block, 'Try::Tiny::Catch'), |
148 | @rest, |
149 | ); |
3176feef |
150 | } |
151 | |
7195fc08 |
152 | sub finally (&;@) { |
8d2ee831 |
153 | my ( $block, @rest ) = @_; |
7195fc08 |
154 | |
d2ae14ad |
155 | croak 'Useless bare finally()' unless wantarray; |
9d0e0466 |
156 | |
2f7f4153 |
157 | my $caller = caller; |
158 | _subname("${caller}::finally {...} " => $block) |
159 | if _HAS_SUBNAME; |
8d2ee831 |
160 | return ( |
161 | bless(\$block, 'Try::Tiny::Finally'), |
162 | @rest, |
163 | ); |
7195fc08 |
164 | } |
3176feef |
165 | |
b611f396 |
166 | { |
3ef3a4f0 |
167 | package # hide from PAUSE |
168 | Try::Tiny::ScopeGuard; |
b611f396 |
169 | |
5f5e92c0 |
170 | use constant UNSTABLE_DOLLARAT => ($] < '5.013002') ? 1 : 0; |
171 | |
b611f396 |
172 | sub _new { |
173 | shift; |
174 | bless [ @_ ]; |
175 | } |
176 | |
177 | sub DESTROY { |
5f5e92c0 |
178 | my ($code, @args) = @{ $_[0] }; |
179 | |
180 | local $@ if UNSTABLE_DOLLARAT; |
181 | eval { |
182 | $code->(@args); |
183 | 1; |
184 | } or do { |
185 | warn |
186 | "Execution of finally() block $code resulted in an exception, which " |
187 | . '*CAN NOT BE PROPAGATED* due to fundamental limitations of Perl. ' |
188 | . 'Your program will continue as if this event never took place. ' |
189 | . "Original exception text follows:\n\n" |
190 | . (defined $@ ? $@ : '$@ left undefined...') |
191 | . "\n" |
192 | ; |
193 | } |
b611f396 |
194 | } |
82ef0e61 |
195 | } |
196 | |
3176feef |
197 | __PACKAGE__ |
198 | |
199 | __END__ |
200 | |
201 | =pod |
202 | |
3176feef |
203 | =head1 SYNOPSIS |
204 | |
a2358317 |
205 | You can use Try::Tiny's C<try> and C<catch> to expect and handle exceptional |
206 | conditions, avoiding quirks in Perl and common mistakes: |
207 | |
8d2ee831 |
208 | # handle errors with a catch handler |
209 | try { |
210 | die "foo"; |
211 | } catch { |
212 | warn "caught error: $_"; # not $@ |
213 | }; |
3176feef |
214 | |
b999823d |
215 | You can also use it like a standalone C<eval> to catch and ignore any error |
a2358317 |
216 | conditions. Obviously, this is an extreme measure not to be undertaken |
217 | lightly: |
218 | |
8d2ee831 |
219 | # just silence errors |
220 | try { |
221 | die "foo"; |
222 | }; |
3176feef |
223 | |
224 | =head1 DESCRIPTION |
225 | |
7195fc08 |
226 | This module provides bare bones C<try>/C<catch>/C<finally> statements that are designed to |
1f7c5af6 |
227 | minimize common mistakes with eval blocks, and NOTHING else. |
3176feef |
228 | |
229 | This is unlike L<TryCatch> which provides a nice syntax and avoids adding |
ad10a9e2 |
230 | another call stack layer, and supports calling C<return> from the C<try> block to |
3176feef |
231 | return from the parent subroutine. These extra features come at a cost of a few |
232 | dependencies, namely L<Devel::Declare> and L<Scope::Upper> which are |
1f7c5af6 |
233 | occasionally problematic, and the additional catch filtering uses L<Moose> |
234 | type constraints which may not be desirable either. |
3176feef |
235 | |
1f7c5af6 |
236 | The main focus of this module is to provide simple and reliable error handling |
3176feef |
237 | for those having a hard time installing L<TryCatch>, but who still want to |
238 | write correct C<eval> blocks without 5 lines of boilerplate each time. |
239 | |
240 | It's designed to work as correctly as possible in light of the various |
b999823d |
241 | pathological edge cases (see L</BACKGROUND>) and to be compatible with any style |
3176feef |
242 | of error values (simple strings, references, objects, overloaded objects, etc). |
243 | |
ad10a9e2 |
244 | If the C<try> block dies, it returns the value of the last statement executed in |
245 | the C<catch> block, if there is one. Otherwise, it returns C<undef> in scalar |
c065237e |
246 | context or the empty list in list context. The following examples all |
ad10a9e2 |
247 | assign C<"bar"> to C<$x>: |
a5cd5f73 |
248 | |
8d2ee831 |
249 | my $x = try { die "foo" } catch { "bar" }; |
a7f27f92 |
250 | my $x = try { die "foo" } || "bar"; |
251 | my $x = (try { die "foo" }) // "bar"; |
a5cd5f73 |
252 | |
8d2ee831 |
253 | my $x = eval { die "foo" } || "bar"; |
a5cd5f73 |
254 | |
ad10a9e2 |
255 | You can add C<finally> blocks, yielding the following: |
7195fc08 |
256 | |
8d2ee831 |
257 | my $x; |
258 | try { die 'foo' } finally { $x = 'bar' }; |
259 | try { die 'foo' } catch { warn "Got a die: $_" } finally { $x = 'bar' }; |
7195fc08 |
260 | |
ad10a9e2 |
261 | C<finally> blocks are always executed making them suitable for cleanup code |
262 | which cannot be handled using local. You can add as many C<finally> blocks to a |
263 | given C<try> block as you like. |
7195fc08 |
264 | |
79039ae4 |
265 | Note that adding a C<finally> block without a preceding C<catch> block |
266 | suppresses any errors. This behaviour is consistent with using a standalone |
267 | C<eval>, but it is not consistent with C<try>/C<finally> patterns found in |
268 | other programming languages, such as Java, Python, Javascript or C#. If you |
269 | learnt the C<try>/C<finally> pattern from one of these languages, watch out for |
270 | this. |
271 | |
3176feef |
272 | =head1 EXPORTS |
273 | |
1f7c5af6 |
274 | All functions are exported by default using L<Exporter>. |
3176feef |
275 | |
7195fc08 |
276 | If you need to rename the C<try>, C<catch> or C<finally> keyword consider using |
6157bcb8 |
277 | L<Sub::Import> to get L<Sub::Exporter>'s flexibility. |
3176feef |
278 | |
279 | =over 4 |
280 | |
7195fc08 |
281 | =item try (&;@) |
3176feef |
282 | |
ad10a9e2 |
283 | Takes one mandatory C<try> subroutine, an optional C<catch> subroutine and C<finally> |
7195fc08 |
284 | subroutine. |
3176feef |
285 | |
286 | The mandatory subroutine is evaluated in the context of an C<eval> block. |
287 | |
1f7c5af6 |
288 | If no error occurred the value from the first block is returned, preserving |
289 | list/scalar context. |
3176feef |
290 | |
291 | If there was an error and the second subroutine was given it will be invoked |
292 | with the error in C<$_> (localized) and as that block's first and only |
293 | argument. |
294 | |
2dc64249 |
295 | C<$@> does B<not> contain the error. Inside the C<catch> block it has the same |
296 | value it had before the C<try> block was executed. |
297 | |
1f7c5af6 |
298 | Note that the error may be false, but if that happens the C<catch> block will |
1d64c1ad |
299 | still be invoked. |
3176feef |
300 | |
ad10a9e2 |
301 | Once all execution is finished then the C<finally> block, if given, will execute. |
7195fc08 |
302 | |
ae5ed1be |
303 | =item catch (&;@) |
1f7c5af6 |
304 | |
305 | Intended to be used in the second argument position of C<try>. |
3176feef |
306 | |
7195fc08 |
307 | Returns a reference to the subroutine it was given but blessed as |
308 | C<Try::Tiny::Catch> which allows try to decode correctly what to do |
309 | with this code reference. |
3176feef |
310 | |
8d2ee831 |
311 | catch { ... } |
3176feef |
312 | |
ad10a9e2 |
313 | Inside the C<catch> block the caught error is stored in C<$_>, while previous |
2dc64249 |
314 | value of C<$@> is still available for use. This value may or may not be |
315 | meaningful depending on what happened before the C<try>, but it might be a good |
316 | idea to preserve it in an error stack. |
ac4f5f9f |
317 | |
0a0641f9 |
318 | For code that captures C<$@> when throwing new errors (i.e. |
319 | L<Class::Throwable>), you'll need to do: |
320 | |
8d2ee831 |
321 | local $@ = $_; |
0a0641f9 |
322 | |
ae5ed1be |
323 | =item finally (&;@) |
7195fc08 |
324 | |
325 | try { ... } |
326 | catch { ... } |
327 | finally { ... }; |
328 | |
329 | Or |
330 | |
331 | try { ... } |
332 | finally { ... }; |
333 | |
334 | Or even |
335 | |
336 | try { ... } |
337 | finally { ... } |
338 | catch { ... }; |
339 | |
ad10a9e2 |
340 | Intended to be the second or third element of C<try>. C<finally> blocks are always |
7195fc08 |
341 | executed in the event of a successful C<try> or if C<catch> is run. This allows |
342 | you to locate cleanup code which cannot be done via C<local()> e.g. closing a file |
343 | handle. |
344 | |
ad10a9e2 |
345 | When invoked, the C<finally> block is passed the error that was caught. If no |
346 | error was caught, it is passed nothing. (Note that the C<finally> block does not |
347 | localize C<$_> with the error, since unlike in a C<catch> block, there is no way |
658a90e5 |
348 | to know if C<$_ == undef> implies that there were no errors.) In other words, |
349 | the following code does just what you would expect: |
d6e0f0df |
350 | |
351 | try { |
352 | die_sometimes(); |
353 | } catch { |
354 | # ...code run in case of error |
355 | } finally { |
356 | if (@_) { |
357 | print "The try block died with: @_\n"; |
358 | } else { |
359 | print "The try block ran without error.\n"; |
360 | } |
361 | }; |
362 | |
ad10a9e2 |
363 | B<You must always do your own error handling in the C<finally> block>. C<Try::Tiny> will |
7195fc08 |
364 | not do anything about handling possible errors coming from code located in these |
365 | blocks. |
366 | |
5f5e92c0 |
367 | Furthermore B<exceptions in C<finally> blocks are not trappable and are unable |
368 | to influence the execution of your program>. This is due to limitation of |
369 | C<DESTROY>-based scope guards, which C<finally> is implemented on top of. This |
370 | may change in a future version of Try::Tiny. |
371 | |
7195fc08 |
372 | In the same way C<catch()> blesses the code reference this subroutine does the same |
373 | except it bless them as C<Try::Tiny::Finally>. |
374 | |
3176feef |
375 | =back |
376 | |
377 | =head1 BACKGROUND |
378 | |
379 | There are a number of issues with C<eval>. |
380 | |
381 | =head2 Clobbering $@ |
382 | |
ad10a9e2 |
383 | When you run an C<eval> block and it succeeds, C<$@> will be cleared, potentially |
a717a876 |
384 | clobbering an error that is currently being caught. |
3176feef |
385 | |
1f7c5af6 |
386 | This causes action at a distance, clearing previous errors your caller may have |
387 | not yet handled. |
388 | |
389 | C<$@> must be properly localized before invoking C<eval> in order to avoid this |
390 | issue. |
3176feef |
391 | |
8e5b4441 |
392 | More specifically, C<$@> is clobbered at the beginning of the C<eval>, which |
511c05ca |
393 | also makes it impossible to capture the previous error before you die (for |
394 | instance when making exception objects with error stacks). |
395 | |
2b0d579d |
396 | For this reason C<try> will actually set C<$@> to its previous value (the one |
397 | available before entering the C<try> block) in the beginning of the C<eval> |
398 | block. |
511c05ca |
399 | |
3176feef |
400 | =head2 Localizing $@ silently masks errors |
401 | |
ad10a9e2 |
402 | Inside an C<eval> block, C<die> behaves sort of like: |
3176feef |
403 | |
8d2ee831 |
404 | sub die { |
405 | $@ = $_[0]; |
406 | return_undef_from_eval(); |
407 | } |
3176feef |
408 | |
409 | This means that if you were polite and localized C<$@> you can't die in that |
1f7c5af6 |
410 | scope, or your error will be discarded (printing "Something's wrong" instead). |
3176feef |
411 | |
412 | The workaround is very ugly: |
413 | |
8d2ee831 |
414 | my $error = do { |
415 | local $@; |
416 | eval { ... }; |
417 | $@; |
418 | }; |
3176feef |
419 | |
8d2ee831 |
420 | ... |
421 | die $error; |
3176feef |
422 | |
423 | =head2 $@ might not be a true value |
424 | |
425 | This code is wrong: |
426 | |
8d2ee831 |
427 | if ( $@ ) { |
428 | ... |
429 | } |
3176feef |
430 | |
1f7c5af6 |
431 | because due to the previous caveats it may have been unset. |
432 | |
1d64c1ad |
433 | C<$@> could also be an overloaded error object that evaluates to false, but |
434 | that's asking for trouble anyway. |
3176feef |
435 | |
436 | The classic failure mode is: |
437 | |
8d2ee831 |
438 | sub Object::DESTROY { |
439 | eval { ... } |
440 | } |
3176feef |
441 | |
8d2ee831 |
442 | eval { |
443 | my $obj = Object->new; |
3176feef |
444 | |
8d2ee831 |
445 | die "foo"; |
446 | }; |
3176feef |
447 | |
8d2ee831 |
448 | if ( $@ ) { |
3176feef |
449 | |
8d2ee831 |
450 | } |
3176feef |
451 | |
1f7c5af6 |
452 | In this case since C<Object::DESTROY> is not localizing C<$@> but still uses |
1d64c1ad |
453 | C<eval>, it will set C<$@> to C<"">. |
3176feef |
454 | |
1f7c5af6 |
455 | The destructor is called when the stack is unwound, after C<die> sets C<$@> to |
3176feef |
456 | C<"foo at Foo.pm line 42\n">, so by the time C<if ( $@ )> is evaluated it has |
1f7c5af6 |
457 | been cleared by C<eval> in the destructor. |
3176feef |
458 | |
1f7c5af6 |
459 | The workaround for this is even uglier than the previous ones. Even though we |
460 | can't save the value of C<$@> from code that doesn't localize, we can at least |
ad10a9e2 |
461 | be sure the C<eval> was aborted due to an error: |
3176feef |
462 | |
8d2ee831 |
463 | my $failed = not eval { |
464 | ... |
3176feef |
465 | |
8d2ee831 |
466 | return 1; |
467 | }; |
3176feef |
468 | |
1f7c5af6 |
469 | This is because an C<eval> that caught a C<die> will always return a false |
470 | value. |
3176feef |
471 | |
f9b91e2c |
472 | =head1 SHINY SYNTAX |
3176feef |
473 | |
1f7c5af6 |
474 | Using Perl 5.10 you can use L<perlsyn/"Switch statements">. |
3176feef |
475 | |
7788aa10 |
476 | =for stopwords topicalizer |
477 | |
1f7c5af6 |
478 | The C<catch> block is invoked in a topicalizer context (like a C<given> block), |
479 | but note that you can't return a useful value from C<catch> using the C<when> |
27293e40 |
480 | blocks without an explicit C<return>. |
3176feef |
481 | |
482 | This is somewhat similar to Perl 6's C<CATCH> blocks. You can use it to |
483 | concisely match errors: |
484 | |
8d2ee831 |
485 | try { |
486 | require Foo; |
487 | } catch { |
488 | when (/^Can't locate .*?\.pm in \@INC/) { } # ignore |
489 | default { die $_ } |
490 | }; |
3176feef |
491 | |
492 | =head1 CAVEATS |
493 | |
494 | =over 4 |
495 | |
496 | =item * |
497 | |
013dca8f |
498 | C<@_> is not available within the C<try> block, so you need to copy your |
7788aa10 |
499 | argument list. In case you want to work with argument values directly via C<@_> |
013dca8f |
500 | aliasing (i.e. allow C<$_[1] = "foo">), you need to pass C<@_> by reference: |
318cb1eb |
501 | |
8d2ee831 |
502 | sub foo { |
503 | my ( $self, @args ) = @_; |
504 | try { $self->bar(@args) } |
505 | } |
013dca8f |
506 | |
507 | or |
508 | |
8d2ee831 |
509 | sub bar_in_place { |
510 | my $self = shift; |
511 | my $args = \@_; |
512 | try { $_ = $self->bar($_) for @$args } |
513 | } |
318cb1eb |
514 | |
515 | =item * |
516 | |
517 | C<return> returns from the C<try> block, not from the parent sub (note that |
518 | this is also how C<eval> works, but not how L<TryCatch> works): |
519 | |
6651956b |
520 | sub parent_sub { |
8d2ee831 |
521 | try { |
522 | die; |
523 | } |
524 | catch { |
525 | return; |
526 | }; |
6651956b |
527 | |
8d2ee831 |
528 | say "this text WILL be displayed, even though an exception is thrown"; |
6651956b |
529 | } |
530 | |
531 | Instead, you should capture the return value: |
532 | |
533 | sub parent_sub { |
8d2ee831 |
534 | my $success = try { |
535 | die; |
536 | 1; |
86b8a58a |
537 | }; |
8d2ee831 |
538 | return unless $success; |
6651956b |
539 | |
8d2ee831 |
540 | say "This text WILL NEVER appear!"; |
6651956b |
541 | } |
d7aab6fa |
542 | # OR |
c87ad8ce |
543 | sub parent_sub_with_catch { |
544 | my $success = try { |
545 | die; |
546 | 1; |
547 | } |
548 | catch { |
549 | # do something with $_ |
550 | return undef; #see note |
551 | }; |
d7aab6fa |
552 | return unless $success; |
553 | |
554 | say "This text WILL NEVER appear!"; |
c87ad8ce |
555 | } |
318cb1eb |
556 | |
ad10a9e2 |
557 | Note that if you have a C<catch> block, it must return C<undef> for this to work, |
558 | since if a C<catch> block exists, its return value is returned in place of C<undef> |
6651956b |
559 | when an exception is thrown. |
318cb1eb |
560 | |
561 | =item * |
562 | |
1f7c5af6 |
563 | C<try> introduces another caller stack frame. L<Sub::Uplevel> is not used. L<Carp> |
c12e626f |
564 | will not report this when using full stack traces, though, because |
565 | C<%Carp::Internal> is used. This lack of magic is considered a feature. |
3176feef |
566 | |
7788aa10 |
567 | =for stopwords unhygienically |
568 | |
3176feef |
569 | =item * |
570 | |
57c50f41 |
571 | The value of C<$_> in the C<catch> block is not guaranteed to be the value of |
572 | the exception thrown (C<$@>) in the C<try> block. There is no safe way to |
7788aa10 |
573 | ensure this, since C<eval> may be used unhygienically in destructors. The only |
57c50f41 |
574 | guarantee is that the C<catch> will be called if an exception is thrown. |
3176feef |
575 | |
a5cd5f73 |
576 | =item * |
577 | |
578 | The return value of the C<catch> block is not ignored, so if testing the result |
579 | of the expression for truth on success, be sure to return a false value from |
580 | the C<catch> block: |
581 | |
8d2ee831 |
582 | my $obj = try { |
583 | MightFail->new; |
584 | } catch { |
585 | ... |
a5cd5f73 |
586 | |
8d2ee831 |
587 | return; # avoid returning a true value; |
588 | }; |
a5cd5f73 |
589 | |
8d2ee831 |
590 | return unless $obj; |
a5cd5f73 |
591 | |
eaca95b7 |
592 | =item * |
593 | |
594 | C<$SIG{__DIE__}> is still in effect. |
595 | |
596 | Though it can be argued that C<$SIG{__DIE__}> should be disabled inside of |
597 | C<eval> blocks, since it isn't people have grown to rely on it. Therefore in |
598 | the interests of compatibility, C<try> does not disable C<$SIG{__DIE__}> for |
599 | the scope of the error throwing code. |
600 | |
cbfb5327 |
601 | =item * |
602 | |
603 | Lexical C<$_> may override the one set by C<catch>. |
604 | |
605 | For example Perl 5.10's C<given> form uses a lexical C<$_>, creating some |
606 | confusing behavior: |
607 | |
8d2ee831 |
608 | given ($foo) { |
609 | when (...) { |
610 | try { |
611 | ... |
612 | } catch { |
613 | warn $_; # will print $foo, not the error |
614 | warn $_[0]; # instead, get the error like this |
615 | } |
616 | } |
617 | } |
cbfb5327 |
618 | |
aaf0d61f |
619 | Note that this behavior was changed once again in L<Perl5 version 18 |
620 | |https://metacpan.org/module/perldelta#given-now-aliases-the-global-_>. |
7788aa10 |
621 | However, since the entirety of lexical C<$_> is now L<considered experimental |
aaf0d61f |
622 | |https://metacpan.org/module/perldelta#Lexical-_-is-now-experimental>, it |
623 | is unclear whether the new version 18 behavior is final. |
624 | |
3176feef |
625 | =back |
626 | |
627 | =head1 SEE ALSO |
628 | |
629 | =over 4 |
630 | |
631 | =item L<TryCatch> |
632 | |
633 | Much more feature complete, more convenient semantics, but at the cost of |
634 | implementation complexity. |
635 | |
9bc603cb |
636 | =item L<autodie> |
637 | |
638 | Automatic error throwing for builtin functions and more. Also designed to |
639 | work well with C<given>/C<when>. |
640 | |
f8227e43 |
641 | =item L<Throwable> |
642 | |
643 | A lightweight role for rolling your own exception classes. |
644 | |
3176feef |
645 | =item L<Error> |
646 | |
647 | Exception object implementation with a C<try> statement. Does not localize |
648 | C<$@>. |
649 | |
650 | =item L<Exception::Class::TryCatch> |
651 | |
652 | Provides a C<catch> statement, but properly calling C<eval> is your |
653 | responsibility. |
654 | |
655 | The C<try> keyword pushes C<$@> onto an error stack, avoiding some of the |
1d64c1ad |
656 | issues with C<$@>, but you still need to localize to prevent clobbering. |
3176feef |
657 | |
658 | =back |
659 | |
faecd5a0 |
660 | =head1 LIGHTNING TALK |
661 | |
662 | I gave a lightning talk about this module, you can see the slides (Firefox |
663 | only): |
664 | |
9b3383e4 |
665 | L<http://web.archive.org/web/20100628040134/http://nothingmuch.woobling.org/talks/takahashi.xul> |
faecd5a0 |
666 | |
667 | Or read the source: |
668 | |
2245f1ae |
669 | L<http://web.archive.org/web/20100305133605/http://nothingmuch.woobling.org/talks/yapc_asia_2009/try_tiny.yml> |
faecd5a0 |
670 | |
3176feef |
671 | =head1 VERSION CONTROL |
672 | |
e5c5bdf1 |
673 | L<http://github.com/doy/try-tiny/> |
3176feef |
674 | |
3176feef |
675 | =cut |
676 | |