6 use vars qw(@EXPORT @EXPORT_OK $VERSION @ISA);
15 $VERSION = eval $VERSION;
17 @EXPORT = @EXPORT_OK = qw(try catch);
20 my ( $try, $catch ) = @_;
22 # we need to save this here, the eval block will be in scalar context due
24 my $wantarray = wantarray;
26 my ( @ret, $error, $failed );
28 # FIXME consider using local $SIG{__DIE__} to accumilate all errors. It's
29 # not perfect, but we could provide a list of additional errors for
33 # localize $@ to prevent clobbering of previous value by a successful
37 # failed will be true if the eval dies, because 1 will not be returned
41 # evaluate the try block in the correct context
44 } elsif ( defined $wantarray ) {
50 return 1; # properly set $fail to false
53 # copy $@ to $error, when we leave this scope local $@ will revert $@
54 # back to its previous value
58 # at this point $failed contains a true value if the eval died even if some
59 # destructor overwrite $@ as the eval was unwinding.
61 # if we got an error, invoke the catch block.
63 # This works like given($error), but is backwards compatible and
64 # sets $_ in the dynamic scope for the body of C<$catch>
66 return $catch->($error);
69 # in case when() was used without an explicit return, the C<for>
70 # loop will be aborted and there's no useful return value
75 # no failure, $@ is back to what it was, everything is fine
76 return $wantarray ? @ret : $ret[0];
93 Try::Tiny - minimal try/catch with proper localization of $@
97 # handle errors with a catch handler
101 warn "caught error: $_";
104 # just silence errors
111 This module provides bare bones C<try>/C<catch> statements that are designed to
112 minimize common mistakes done with eval blocks (for instance assuming that
113 C<$@> is set to a true value on error, or clobbering previous values of C<$@>),
116 This is unlike L<TryCatch> which provides a nice syntax and avoids adding
117 another call stack layer, and supports calling C<return> from the try block to
118 return from the parent subroutine. These extra features come at a cost of a few
119 dependencies, namely L<Devel::Declare> and L<Scope::Upper> which are
120 occasionally problematic, and the additional catch filtering using L<Moose>
121 type constraints may not be desirable either.
123 The main focus of this module is to provide reliable but simple error handling
124 for those having a hard time installing L<TryCatch>, but who still want to
125 write correct C<eval> blocks without 5 lines of boilerplate each time.
127 It's designed to work as correctly as possible in light of the various
128 pathological edge cases (see L<BACKGROUND>) and to be compatible with any style
129 of error values (simple strings, references, objects, overloaded objects, etc).
133 All are exported by default using L<Exporter>.
135 In the future L<Sub::ExporteR> may be used to allow the keywords to be renamed,
136 but this technically does not satisfy Adam Kennedy's definition of "Tiny".
142 Takes one mandatory and one optional catch subroutine.
144 The mandatory subroutine is evaluated in the context of an C<eval> block.
146 If no error occured the value from the first block is returned.
148 If there was an error and the second subroutine was given it will be invoked
149 with the error in C<$_> (localized) and as that block's first and only
152 Note that the error may be false
156 Just retuns the subroutine it was given.
164 Intended to be used in the second argument position of C<try>.
170 There are a number of issues with C<eval>.
174 When you run an eval block and it succeeds, C<$@> will be cleared, potentially
175 cloberring an error that is currently being caught.
177 C<$@> must be properly localized before invoking C<eval> in order to avoid this issue.
179 =head2 Localizing $@ silently masks errors
181 Inside an eval block C<die> behaves sort of like:
185 return_undef_from_eval();
188 This means that if you were polite and localized C<$@> you can't die in that
189 scope while propagating your error.
191 The workaround is very ugly:
202 =head2 $@ might not be a true value
210 because due to the previous caveats it may have been unset. $@ could also an
211 overloaded error object that evaluates to false, but that's asking for trouble
214 The classic failure mode is:
216 sub Object::DESTROY {
221 my $obj = Object->new;
230 In this case since C<Object::DESTROY> is not localizing C<$@> but using eval it
231 will set C<$@> to C<"">.
233 The destructor is only fired after C<die> sets C<$@> to
234 C<"foo at Foo.pm line 42\n">, so by the time C<if ( $@ )> is evaluated it has
237 The workaround for this is even uglier. Even though we can't save the value of
238 C<$@> from code that doesn't localize it but uses C<eval> in destructors, we
239 can at least be sure there was an error:
241 my $failed = not eval {
247 This is because an C<eval> that caught a C<die> will always behave like
248 C<return> with no arguments.
252 Using Perl 5.10 you can enable the C<given>/C<when> construct. The C<catch>
253 block is invoked in a topicalizer context (like a C<given> block).
255 Note that you can't return a useful value from C<catch> using the C<when>
256 blocks without an explicit C<return>.
258 This is somewhat similar to Perl 6's C<CATCH> blocks. You can use it to
259 concisely match errors:
264 when (qr/^Can't locate .*?\.pm in \@INC/) { } # ignore
274 Introduces another caller stack frame. L<Sub::Uplevel> is not used. L<Carp>
275 will report this when using full stack traces. This is considered a feature.
279 The value of C<$_> in the C<catch> block is not guaranteed to be preserved,
280 there is no safe way to ensure this if C<eval> is used unhygenically in
281 destructors. It is guaranteed that C<catch> will be called, though.
291 Much more feature complete, more convenient semantics, but at the cost of
292 implementation complexity.
296 Exception object implementation with a C<try> statement. Does not localize
299 =item L<Exception::Class::TryCatch>
301 Provides a C<catch> statement, but properly calling C<eval> is your
304 The C<try> keyword pushes C<$@> onto an error stack, avoiding some of the
305 issues with C<$@> but you still need to localize to prevent clobbering.
309 =head1 VERSION CONTROL
311 L<http://github.com/nothingmuch/try-tiny/>
315 Yuval Kogman E<lt>nothingmuch@woobling.orgE<gt>
319 Copyright (c) 2009 Yuval Kogman. All rights reserved.
320 This program is free software; you can redistribute
321 it and/or modify it under the terms of the MIT license.