1Try::Tiny(3) User Contributed Perl Documentation Try::Tiny(3)
2
6 Try::Tiny - Minimal try/catch with proper preservation of $@
7
9 version 0.30
10
12 You can use Try::Tiny's "try" and "catch" to expect and handle
13 exceptional conditions, avoiding quirks in Perl and common mistakes:
14 # handle errors with a catch handler
16 try {
17 die "foo";
18 } catch {
19 warn "caught error: $_"; # not $@
20 };
21 You can also use it like a standalone "eval" to catch and ignore any
23 error conditions. Obviously, this is an extreme measure not to be
24 undertaken lightly:
25 # just silence errors
27 try {
28 die "foo";
29 };
30
32 This module provides bare bones "try"/"catch"/"finally" statements that
33 are designed to minimize common mistakes with eval blocks, and NOTHING
34 else.
35 This is unlike TryCatch which provides a nice syntax and avoids adding
37 another call stack layer, and supports calling "return" from the "try"
38 block to return from the parent subroutine. These extra features come
39 at a cost of a few dependencies, namely Devel::Declare and Scope::Upper
40 which are occasionally problematic, and the additional catch filtering
41 uses Moose type constraints which may not be desirable either.
42 The main focus of this module is to provide simple and reliable error
44 handling for those having a hard time installing TryCatch, but who
45 still want to write correct "eval" blocks without 5 lines of
46 boilerplate each time.
47 It's designed to work as correctly as possible in light of the various
49 pathological edge cases (see "BACKGROUND") and to be compatible with
50 any style of error values (simple strings, references, objects,
51 overloaded objects, etc).
52 If the "try" block dies, it returns the value of the last statement
54 executed in the "catch" block, if there is one. Otherwise, it returns
55 "undef" in scalar context or the empty list in list context. The
56 following examples all assign "bar" to $x:
57 my $x = try { die "foo" } catch { "bar" };
59 my $x = try { die "foo" } || "bar";
60 my $x = (try { die "foo" }) // "bar";
61 my $x = eval { die "foo" } || "bar";
63 You can add "finally" blocks, yielding the following:
65 my $x;
67 try { die 'foo' } finally { $x = 'bar' };
68 try { die 'foo' } catch { warn "Got a die: $_" } finally { $x = 'bar' };
69 "finally" blocks are always executed making them suitable for cleanup
71 code which cannot be handled using local. You can add as many
72 "finally" blocks to a given "try" block as you like.
73 Note that adding a "finally" block without a preceding "catch" block
75 suppresses any errors. This behaviour is consistent with using a
76 standalone "eval", but it is not consistent with "try"/"finally"
77 patterns found in other programming languages, such as Java, Python,
78 Javascript or C#. If you learnt the "try"/"finally" pattern from one of
79 these languages, watch out for this.
80
82 All functions are exported by default using Exporter.
83 If you need to rename the "try", "catch" or "finally" keyword consider
85 using Sub::Import to get Sub::Exporter's flexibility.
86 try (&;@)
88 Takes one mandatory "try" subroutine, an optional "catch"
89 subroutine and "finally" subroutine.
90 The mandatory subroutine is evaluated in the context of an "eval"
92 block.
93 If no error occurred the value from the first block is returned,
95 preserving list/scalar context.
96 If there was an error and the second subroutine was given it will
98 be invoked with the error in $_ (localized) and as that block's
99 first and only argument.
100 $@ does not contain the error. Inside the "catch" block it has the
102 same value it had before the "try" block was executed.
103 Note that the error may be false, but if that happens the "catch"
105 block will still be invoked.
106 Once all execution is finished then the "finally" block, if given,
108 will execute.
109 catch (&;@)
111 Intended to be used in the second argument position of "try".
112 Returns a reference to the subroutine it was given but blessed as
114 "Try::Tiny::Catch" which allows try to decode correctly what to do
115 with this code reference.
116 catch { ... }
118 Inside the "catch" block the caught error is stored in $_, while
120 previous value of $@ is still available for use. This value may or
121 may not be meaningful depending on what happened before the "try",
122 but it might be a good idea to preserve it in an error stack.
123 For code that captures $@ when throwing new errors (i.e.
125 Class::Throwable), you'll need to do:
126 local $@ = $_;
128 finally (&;@)
130 try { ... }
131 catch { ... }
132 finally { ... };
133 Or
135 try { ... }
137 finally { ... };
138 Or even
140 try { ... }
142 finally { ... }
143 catch { ... };
144 Intended to be the second or third element of "try". "finally"
146 blocks are always executed in the event of a successful "try" or if
147 "catch" is run. This allows you to locate cleanup code which cannot
148 be done via "local()" e.g. closing a file handle.
149 When invoked, the "finally" block is passed the error that was
151 caught. If no error was caught, it is passed nothing. (Note that
152 the "finally" block does not localize $_ with the error, since
153 unlike in a "catch" block, there is no way to know if "$_ == undef"
154 implies that there were no errors.) In other words, the following
155 code does just what you would expect:
156 try {
158 die_sometimes();
159 } catch {
160 # ...code run in case of error
161 } finally {
162 if (@_) {
163 print "The try block died with: @_\n";
164 } else {
165 print "The try block ran without error.\n";
166 }
167 };
168 You must always do your own error handling in the "finally" block.
170 "Try::Tiny" will not do anything about handling possible errors
171 coming from code located in these blocks.
172 Furthermore exceptions in "finally" blocks are not trappable and
174 are unable to influence the execution of your program. This is due
175 to limitation of "DESTROY"-based scope guards, which "finally" is
176 implemented on top of. This may change in a future version of
177 Try::Tiny.
178 In the same way "catch()" blesses the code reference this
180 subroutine does the same except it bless them as
181 "Try::Tiny::Finally".
182
184 There are a number of issues with "eval".
185 Clobbering $@
187 When you run an "eval" block and it succeeds, $@ will be cleared,
188 potentially clobbering an error that is currently being caught.
189 This causes action at a distance, clearing previous errors your caller
191 may have not yet handled.
192 $@ must be properly localized before invoking "eval" in order to avoid
194 this issue.
195 More specifically, before Perl version 5.14.0 $@ was clobbered at the
197 beginning of the "eval", which also made it impossible to capture the
198 previous error before you die (for instance when making exception
199 objects with error stacks).
200 For this reason "try" will actually set $@ to its previous value (the
202 one available before entering the "try" block) in the beginning of the
203 "eval" block.
204 Localizing $@ silently masks errors
206 Inside an "eval" block, "die" behaves sort of like:
207 sub die {
209 $@ = $_[0];
210 return_undef_from_eval();
211 }
212 This means that if you were polite and localized $@ you can't die in
214 that scope, or your error will be discarded (printing "Something's
215 wrong" instead).
216 The workaround is very ugly:
218 my $error = do {
220 local $@;
221 eval { ... };
222 $@;
223 };
224 ...
226 die $error;
227 $@ might not be a true value
229 This code is wrong:
230 if ( $@ ) {
232 ...
233 }
234 because due to the previous caveats it may have been unset.
236 $@ could also be an overloaded error object that evaluates to false,
238 but that's asking for trouble anyway.
239 The classic failure mode (fixed in Perl 5.14.0) is:
241 sub Object::DESTROY {
243 eval { ... }
244 }
245 eval {
247 my $obj = Object->new;
248 die "foo";
250 };
251 if ( $@ ) {
253 }
255 In this case since "Object::DESTROY" is not localizing $@ but still
257 uses "eval", it will set $@ to "".
258 The destructor is called when the stack is unwound, after "die" sets $@
260 to "foo at Foo.pm line 42\n", so by the time "if ( $@ )" is evaluated
261 it has been cleared by "eval" in the destructor.
262 The workaround for this is even uglier than the previous ones. Even
264 though we can't save the value of $@ from code that doesn't localize,
265 we can at least be sure the "eval" was aborted due to an error:
266 my $failed = not eval {
268 ...
269 return 1;
271 };
272 This is because an "eval" that caught a "die" will always return a
274 false value.
275
277 Using Perl 5.10 you can use "Switch statements" in perlsyn (but please
278 don't, because that syntax has since been deprecated because there was
279 too much unexpected magical behaviour).
280 The "catch" block is invoked in a topicalizer context (like a "given"
282 block), but note that you can't return a useful value from "catch"
283 using the "when" blocks without an explicit "return".
284 This is somewhat similar to Perl 6's "CATCH" blocks. You can use it to
286 concisely match errors:
287 try {
289 require Foo;
290 } catch {
291 when (/^Can't locate .*?\.pm in \@INC/) { } # ignore
292 default { die $_ }
293 };
294
296 · @_ is not available within the "try" block, so you need to copy
297 your argument list. In case you want to work with argument values
298 directly via @_ aliasing (i.e. allow "$_[1] = "foo""), you need to
299 pass @_ by reference:
300 sub foo {
302 my ( $self, @args ) = @_;
303 try { $self->bar(@args) }
304 }
305 or
307 sub bar_in_place {
309 my $self = shift;
310 my $args = \@_;
311 try { $_ = $self->bar($_) for @$args }
312 }
313 · "return" returns from the "try" block, not from the parent sub
315 (note that this is also how "eval" works, but not how TryCatch
316 works):
317 sub parent_sub {
319 try {
320 die;
321 }
322 catch {
323 return;
324 };
325 say "this text WILL be displayed, even though an exception is thrown";
327 }
328 Instead, you should capture the return value:
330 sub parent_sub {
332 my $success = try {
333 die;
334 1;
335 };
336 return unless $success;
337 say "This text WILL NEVER appear!";
339 }
340 # OR
341 sub parent_sub_with_catch {
342 my $success = try {
343 die;
344 1;
345 }
346 catch {
347 # do something with $_
348 return undef; #see note
349 };
350 return unless $success;
351 say "This text WILL NEVER appear!";
353 }
354 Note that if you have a "catch" block, it must return "undef" for
356 this to work, since if a "catch" block exists, its return value is
357 returned in place of "undef" when an exception is thrown.
358 · "try" introduces another caller stack frame. Sub::Uplevel is not
360 used. Carp will not report this when using full stack traces,
361 though, because %Carp::Internal is used. This lack of magic is
362 considered a feature.
363 · The value of $_ in the "catch" block is not guaranteed to be the
365 value of the exception thrown ($@) in the "try" block. There is no
366 safe way to ensure this, since "eval" may be used unhygienically in
367 destructors. The only guarantee is that the "catch" will be called
368 if an exception is thrown.
369 · The return value of the "catch" block is not ignored, so if testing
371 the result of the expression for truth on success, be sure to
372 return a false value from the "catch" block:
373 my $obj = try {
375 MightFail->new;
376 } catch {
377 ...
378 return; # avoid returning a true value;
380 };
381 return unless $obj;
383 · $SIG{__DIE__} is still in effect.
385 Though it can be argued that $SIG{__DIE__} should be disabled
387 inside of "eval" blocks, since it isn't people have grown to rely
388 on it. Therefore in the interests of compatibility, "try" does not
389 disable $SIG{__DIE__} for the scope of the error throwing code.
390 · Lexical $_ may override the one set by "catch".
392 For example Perl 5.10's "given" form uses a lexical $_, creating
394 some confusing behavior:
395 given ($foo) {
397 when (...) {
398 try {
399 ...
400 } catch {
401 warn $_; # will print $foo, not the error
402 warn $_[0]; # instead, get the error like this
403 }
404 }
405 }
406 Note that this behavior was changed once again in Perl5 version 18
408 <https://metacpan.org/module/perldelta#given-now-aliases-the-
409 global-_>. However, since the entirety of lexical $_ is now
410 considered experimental
411 <https://metacpan.org/module/perldelta#Lexical-_-is-now-
412 experimental>, it is unclear whether the new version 18 behavior is
413 final.
414
416 TryCatch
417 Much more feature complete, more convenient semantics, but at the
418 cost of implementation complexity.
419 autodie
421 Automatic error throwing for builtin functions and more. Also
422 designed to work well with "given"/"when".
423 Throwable
425 A lightweight role for rolling your own exception classes.
426 Error
428 Exception object implementation with a "try" statement. Does not
429 localize $@.
430 Exception::Class::TryCatch
432 Provides a "catch" statement, but properly calling "eval" is your
433 responsibility.
434 The "try" keyword pushes $@ onto an error stack, avoiding some of
436 the issues with $@, but you still need to localize to prevent
437 clobbering.
438
440 I gave a lightning talk about this module, you can see the slides
441 (Firefox only):
442 <http://web.archive.org/web/20100628040134/http://nothingmuch.woobling.org/talks/takahashi.xul>
444 Or read the source:
446 <http://web.archive.org/web/20100305133605/http://nothingmuch.woobling.org/talks/yapc_asia_2009/try_tiny.yml>
448
450 Bugs may be submitted through the RT bug tracker
451 <https://rt.cpan.org/Public/Dist/Display.html?Name=Try-Tiny> (or
452 bug-Try-Tiny@rt.cpan.org <mailto:bug-Try-Tiny@rt.cpan.org>).
453
455 · יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
456 · Jesse Luehrs <doy@tozt.net>
458
460 · Karen Etheridge <ether@cpan.org>
461 · Peter Rabbitson <ribasushi@cpan.org>
463 · Ricardo Signes <rjbs@cpan.org>
465 · Mark Fowler <mark@twoshortplanks.com>
467 · Graham Knop <haarg@haarg.org>
469 · Lukas Mai <l.mai@web.de>
471 · Aristotle Pagaltzis <pagaltzis@gmx.de>
473 · Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
475 · Paul Howarth <paul@city-fan.org>
477 · Rudolf Leermakers <rudolf@hatsuseno.org>
479 · anaxagoras <walkeraj@gmail.com>
481 · awalker <awalker@sourcefire.com>
483 · chromatic <chromatic@wgz.org>
485 · Alex <alex@koban.(none)>
487 · cm-perl <cm-perl@users.noreply.github.com>
489 · Andrew Yates <ayates@haddock.local>
491 · David Lowe <davidl@lokku.com>
493 · Glenn Fowler <cebjyre@cpan.org>
495 · Hans Dieter Pearcey <hdp@weftsoar.net>
497 · Jens Berthold <jens@jebecs.de>
499 · Jonathan Yu <JAWNSY@cpan.org>
501 · Marc Mims <marc@questright.com>
503 · Mark Stosberg <mark@stosberg.com>
505 · Pali <pali@cpan.org>
507
509 This software is Copyright (c) 2009 by יובל קוג'מן (Yuval Kogman).
510 This is free software, licensed under:
512 The MIT (X11) License
514perl v5.28.1 2017-12-21 Try::Tiny(3)