package Try::Tiny;
+use 5.006;
+# ABSTRACT: minimal try/catch with proper preservation of $@
use strict;
-#use warnings;
+use warnings;
-use vars qw(@EXPORT @EXPORT_OK $VERSION @ISA);
-
-BEGIN {
- require Exporter;
- @ISA = qw(Exporter);
-}
-
-$VERSION = "0.06";
-
-$VERSION = eval $VERSION;
-
-@EXPORT = @EXPORT_OK = qw(try catch finally);
+use Exporter 5.57 'import';
+our @EXPORT = our @EXPORT_OK = qw(try catch finally);
+use Carp;
$Carp::Internal{+__PACKAGE__}++;
+BEGIN { eval "use Sub::Name; 1" or *{subname} = sub {1} }
+
# Need to prototype as @ not $$ because of the way Perl evaluates the prototype.
# Keeping it at $$ means you only ever get 1 sub because we need to eval in a list
# context & not a scalar one
sub try (&;@) {
- my ( $try, @code_refs ) = @_;
-
- # we need to save this here, the eval block will be in scalar context due
- # to $failed
- my $wantarray = wantarray;
-
- my ( $catch, @finally );
-
- # find labeled blocks in the argument list.
- # catch and finally tag the blocks by blessing a scalar reference to them.
- foreach my $code_ref (@code_refs) {
- next unless $code_ref;
-
- my $ref = ref($code_ref);
-
- if ( $ref eq 'Try::Tiny::Catch' ) {
- $catch = ${$code_ref};
- } elsif ( $ref eq 'Try::Tiny::Finally' ) {
- push @finally, ${$code_ref};
- } else {
- use Carp;
- confess("Unknown code ref type given '${ref}'. Check your usage & try again");
- }
- }
-
- # save the value of $@ so we can set $@ back to it in the beginning of the eval
- my $prev_error = $@;
-
- my ( @ret, $error, $failed );
-
- # FIXME consider using local $SIG{__DIE__} to accumulate all errors. It's
- # not perfect, but we could provide a list of additional errors for
- # $catch->();
-
- {
- # localize $@ to prevent clobbering of previous value by a successful
- # eval.
- local $@;
-
- # failed will be true if the eval dies, because 1 will not be returned
- # from the eval body
- $failed = not eval {
- $@ = $prev_error;
-
- # evaluate the try block in the correct context
- if ( $wantarray ) {
- @ret = $try->();
- } elsif ( defined $wantarray ) {
- $ret[0] = $try->();
- } else {
- $try->();
- };
-
- return 1; # properly set $fail to false
- };
-
- # copy $@ to $error; when we leave this scope, local $@ will revert $@
- # back to its previous value
- $error = $@;
- }
-
- # set up a scope guard to invoke the finally block at the end
- my @guards =
+ my ( $try, @code_refs ) = @_;
+
+ # we need to save this here, the eval block will be in scalar context due
+ # to $failed
+ my $wantarray = wantarray;
+
+ # work around perl bug by explicitly initializing these, due to the likelyhood
+ # this will be used in global destruction (perl rt#119311)
+ my ( $catch, @finally ) = ();
+
+ # find labeled blocks in the argument list.
+ # catch and finally tag the blocks by blessing a scalar reference to them.
+ foreach my $code_ref (@code_refs) {
+
+ if ( ref($code_ref) eq 'Try::Tiny::Catch' ) {
+ croak 'A try() may not be followed by multiple catch() blocks'
+ if $catch;
+ $catch = ${$code_ref};
+ } elsif ( ref($code_ref) eq 'Try::Tiny::Finally' ) {
+ push @finally, ${$code_ref};
+ } else {
+ croak(
+ 'try() encountered an unexpected argument ('
+ . ( defined $code_ref ? $code_ref : 'undef' )
+ . ') - perhaps a missing semi-colon before or'
+ );
+ }
+ }
+
+ # FIXME consider using local $SIG{__DIE__} to accumulate all errors. It's
+ # not perfect, but we could provide a list of additional errors for
+ # $catch->();
+
+ # name the blocks if we have Sub::Name installed
+ my $caller = caller;
+ subname("${caller}::try {...} " => $try);
+ subname("${caller}::catch {...} " => $catch) if $catch;
+ subname("${caller}::finally {...} " => $_) foreach @finally;
+
+ # save the value of $@ so we can set $@ back to it in the beginning of the eval
+ # and restore $@ after the eval finishes
+ my $prev_error = $@;
+
+ my ( @ret, $error );
+
+ # failed will be true if the eval dies, because 1 will not be returned
+ # from the eval body
+ my $failed = not eval {
+ $@ = $prev_error;
+
+ # evaluate the try block in the correct context
+ if ( $wantarray ) {
+ @ret = $try->();
+ } elsif ( defined $wantarray ) {
+ $ret[0] = $try->();
+ } else {
+ $try->();
+ };
+
+ return 1; # properly set $fail to false
+ };
+
+ # preserve the current error and reset the original value of $@
+ $error = $@;
+ $@ = $prev_error;
+
+ # set up a scope guard to invoke the finally block at the end
+ my @guards =
map { Try::Tiny::ScopeGuard->_new($_, $failed ? $error : ()) }
@finally;
- # at this point $failed contains a true value if the eval died, even if some
- # destructor overwrote $@ as the eval was unwinding.
- if ( $failed ) {
- # if we got an error, invoke the catch block.
- if ( $catch ) {
- # This works like given($error), but is backwards compatible and
- # sets $_ in the dynamic scope for the body of C<$catch>
- for ($error) {
- return $catch->($error);
- }
-
- # in case when() was used without an explicit return, the C<for>
- # loop will be aborted and there's no useful return value
- }
-
- return;
- } else {
- # no failure, $@ is back to what it was, everything is fine
- return $wantarray ? @ret : $ret[0];
- }
+ # at this point $failed contains a true value if the eval died, even if some
+ # destructor overwrote $@ as the eval was unwinding.
+ if ( $failed ) {
+ # if we got an error, invoke the catch block.
+ if ( $catch ) {
+ # This works like given($error), but is backwards compatible and
+ # sets $_ in the dynamic scope for the body of C<$catch>
+ for ($error) {
+ return $catch->($error);
+ }
+
+ # in case when() was used without an explicit return, the C<for>
+ # loop will be aborted and there's no useful return value
+ }
+
+ return;
+ } else {
+ # no failure, $@ is back to what it was, everything is fine
+ return $wantarray ? @ret : $ret[0];
+ }
}
sub catch (&;@) {
- my ( $block, @rest ) = @_;
+ my ( $block, @rest ) = @_;
+
+ croak 'Useless bare catch()' unless wantarray;
- return (
- bless(\$block, 'Try::Tiny::Catch'),
- @rest,
- );
+ return (
+ bless(\$block, 'Try::Tiny::Catch'),
+ @rest,
+ );
}
sub finally (&;@) {
- my ( $block, @rest ) = @_;
+ my ( $block, @rest ) = @_;
- return (
- bless(\$block, 'Try::Tiny::Finally'),
- @rest,
- );
+ croak 'Useless bare finally()' unless wantarray;
+
+ return (
+ bless(\$block, 'Try::Tiny::Finally'),
+ @rest,
+ );
}
{
- package Try::Tiny::ScopeGuard;
+ package # hide from PAUSE
+ Try::Tiny::ScopeGuard;
+
+ use constant UNSTABLE_DOLLARAT => ($] < '5.013002') ? 1 : 0;
sub _new {
shift;
}
sub DESTROY {
- my @guts = @{ shift() };
- my $code = shift @guts;
- $code->(@guts);
+ my ($code, @args) = @{ $_[0] };
+
+ local $@ if UNSTABLE_DOLLARAT;
+ eval {
+ $code->(@args);
+ 1;
+ } or do {
+ warn
+ "Execution of finally() block $code resulted in an exception, which "
+ . '*CAN NOT BE PROPAGATED* due to fundamental limitations of Perl. '
+ . 'Your program will continue as if this event never took place. '
+ . "Original exception text follows:\n\n"
+ . (defined $@ ? $@ : '$@ left undefined...')
+ . "\n"
+ ;
+ }
}
}
=pod
-=head1 NAME
+=head1 SYNOPSIS
-Try::Tiny - minimal try/catch with proper localization of $@
+You can use Try::Tiny's C<try> and C<catch> to expect and handle exceptional
+conditions, avoiding quirks in Perl and common mistakes:
-=head1 SYNOPSIS
+ # handle errors with a catch handler
+ try {
+ die "foo";
+ } catch {
+ warn "caught error: $_"; # not $@
+ };
- # handle errors with a catch handler
- try {
- die "foo";
- } catch {
- warn "caught error: $_"; # not $@
- };
+You can also use it like a standalone C<eval> to catch and ignore any error
+conditions. Obviously, this is an extreme measure not to be undertaken
+lightly:
- # just silence errors
- try {
- die "foo";
- };
+ # just silence errors
+ try {
+ die "foo";
+ };
=head1 DESCRIPTION
minimize common mistakes with eval blocks, and NOTHING else.
This is unlike L<TryCatch> which provides a nice syntax and avoids adding
-another call stack layer, and supports calling C<return> from the try block to
+another call stack layer, and supports calling C<return> from the C<try> block to
return from the parent subroutine. These extra features come at a cost of a few
dependencies, namely L<Devel::Declare> and L<Scope::Upper> which are
occasionally problematic, and the additional catch filtering uses L<Moose>
write correct C<eval> blocks without 5 lines of boilerplate each time.
It's designed to work as correctly as possible in light of the various
-pathological edge cases (see L<BACKGROUND>) and to be compatible with any style
+pathological edge cases (see L</BACKGROUND>) and to be compatible with any style
of error values (simple strings, references, objects, overloaded objects, etc).
-If the try block dies, it returns the value of the last statement executed in
-the catch block, if there is one. Otherwise, it returns C<undef> in scalar
-context or the empty list in list context. The following two examples both
-assign C<"bar"> to C<$x>.
+If the C<try> block dies, it returns the value of the last statement executed in
+the C<catch> block, if there is one. Otherwise, it returns C<undef> in scalar
+context or the empty list in list context. The following examples all
+assign C<"bar"> to C<$x>:
- my $x = try { die "foo" } catch { "bar" };
+ my $x = try { die "foo" } catch { "bar" };
+ my $x = try { die "foo" } || { "bar" };
+ my $x = (try { die "foo" }) // { "bar" };
- my $x = eval { die "foo" } || "bar";
+ my $x = eval { die "foo" } || "bar";
-You can add finally blocks making the following true.
+You can add C<finally> blocks, yielding the following:
- my $x;
- try { die 'foo' } finally { $x = 'bar' };
- try { die 'foo' } catch { warn "Got a die: $_" } finally { $x = 'bar' };
+ my $x;
+ try { die 'foo' } finally { $x = 'bar' };
+ try { die 'foo' } catch { warn "Got a die: $_" } finally { $x = 'bar' };
-Finally blocks are always executed making them suitable for cleanup code
-which cannot be handled using local. You can add as many finally blocks to a
-given try block as you like.
+C<finally> blocks are always executed making them suitable for cleanup code
+which cannot be handled using local. You can add as many C<finally> blocks to a
+given C<try> block as you like.
+
+Note that adding a C<finally> block without a preceding C<catch> block
+suppresses any errors. This behaviour is consistent with using a standalone
+C<eval>, but it is not consistent with C<try>/C<finally> patterns found in
+other programming languages, such as Java, Python, Javascript or C#. If you
+learnt the C<try>/C<finally> pattern from one of these languages, watch out for
+this.
=head1 EXPORTS
=item try (&;@)
-Takes one mandatory try subroutine, an optional catch subroutine & finally
+Takes one mandatory C<try> subroutine, an optional C<catch> subroutine and C<finally>
subroutine.
The mandatory subroutine is evaluated in the context of an C<eval> block.
Note that the error may be false, but if that happens the C<catch> block will
still be invoked.
-Once all execution is finished then the finally block if given will execute.
+Once all execution is finished then the C<finally> block, if given, will execute.
-=item catch (&;$)
+=item catch (&;@)
Intended to be used in the second argument position of C<try>.
C<Try::Tiny::Catch> which allows try to decode correctly what to do
with this code reference.
- catch { ... }
+ catch { ... }
-Inside the catch block the caught error is stored in C<$_>, while previous
+Inside the C<catch> block the caught error is stored in C<$_>, while previous
value of C<$@> is still available for use. This value may or may not be
meaningful depending on what happened before the C<try>, but it might be a good
idea to preserve it in an error stack.
For code that captures C<$@> when throwing new errors (i.e.
L<Class::Throwable>), you'll need to do:
- local $@ = $_;
+ local $@ = $_;
-=item finally (&;$)
+=item finally (&;@)
try { ... }
catch { ... }
finally { ... }
catch { ... };
-Intended to be the second or third element of C<try>. Finally blocks are always
+Intended to be the second or third element of C<try>. C<finally> blocks are always
executed in the event of a successful C<try> or if C<catch> is run. This allows
you to locate cleanup code which cannot be done via C<local()> e.g. closing a file
handle.
-When invoked, the finally block is passed the error that was caught. If no
-error was caught, it is passed nothing. In other words, the following code
-does just what you would expect:
+When invoked, the C<finally> block is passed the error that was caught. If no
+error was caught, it is passed nothing. (Note that the C<finally> block does not
+localize C<$_> with the error, since unlike in a C<catch> block, there is no way
+to know if C<$_ == undef> implies that there were no errors.) In other words,
+the following code does just what you would expect:
try {
die_sometimes();
}
};
-B<You must always do your own error handling in the finally block>. C<Try::Tiny> will
+B<You must always do your own error handling in the C<finally> block>. C<Try::Tiny> will
not do anything about handling possible errors coming from code located in these
blocks.
+Furthermore B<exceptions in C<finally> blocks are not trappable and are unable
+to influence the execution of your program>. This is due to limitation of
+C<DESTROY>-based scope guards, which C<finally> is implemented on top of. This
+may change in a future version of Try::Tiny.
+
In the same way C<catch()> blesses the code reference this subroutine does the same
except it bless them as C<Try::Tiny::Finally>.
=head2 Clobbering $@
-When you run an eval block and it succeeds, C<$@> will be cleared, potentially
+When you run an C<eval> block and it succeeds, C<$@> will be cleared, potentially
clobbering an error that is currently being caught.
This causes action at a distance, clearing previous errors your caller may have
also makes it impossible to capture the previous error before you die (for
instance when making exception objects with error stacks).
-For this reason C<try> will actually set C<$@> to its previous value (before
-the localization) in the beginning of the C<eval> block.
+For this reason C<try> will actually set C<$@> to its previous value (the one
+available before entering the C<try> block) in the beginning of the C<eval>
+block.
=head2 Localizing $@ silently masks errors
-Inside an eval block C<die> behaves sort of like:
+Inside an C<eval> block, C<die> behaves sort of like:
- sub die {
- $@ = $_[0];
- return_undef_from_eval();
- }
+ sub die {
+ $@ = $_[0];
+ return_undef_from_eval();
+ }
This means that if you were polite and localized C<$@> you can't die in that
scope, or your error will be discarded (printing "Something's wrong" instead).
The workaround is very ugly:
- my $error = do {
- local $@;
- eval { ... };
- $@;
- };
+ my $error = do {
+ local $@;
+ eval { ... };
+ $@;
+ };
- ...
- die $error;
+ ...
+ die $error;
=head2 $@ might not be a true value
This code is wrong:
- if ( $@ ) {
- ...
- }
+ if ( $@ ) {
+ ...
+ }
because due to the previous caveats it may have been unset.
The classic failure mode is:
- sub Object::DESTROY {
- eval { ... }
- }
+ sub Object::DESTROY {
+ eval { ... }
+ }
- eval {
- my $obj = Object->new;
+ eval {
+ my $obj = Object->new;
- die "foo";
- };
+ die "foo";
+ };
- if ( $@ ) {
+ if ( $@ ) {
- }
+ }
In this case since C<Object::DESTROY> is not localizing C<$@> but still uses
C<eval>, it will set C<$@> to C<"">.
The workaround for this is even uglier than the previous ones. Even though we
can't save the value of C<$@> from code that doesn't localize, we can at least
-be sure the eval was aborted due to an error:
+be sure the C<eval> was aborted due to an error:
- my $failed = not eval {
- ...
+ my $failed = not eval {
+ ...
- return 1;
- };
+ return 1;
+ };
This is because an C<eval> that caught a C<die> will always return a false
value.
This is somewhat similar to Perl 6's C<CATCH> blocks. You can use it to
concisely match errors:
- try {
- require Foo;
- } catch {
- when (/^Can't locate .*?\.pm in \@INC/) { } # ignore
- default { die $_ }
- };
+ try {
+ require Foo;
+ } catch {
+ when (/^Can't locate .*?\.pm in \@INC/) { } # ignore
+ default { die $_ }
+ };
=head1 CAVEATS
arglist. In case you want to work with argument values directly via C<@_>
aliasing (i.e. allow C<$_[1] = "foo">), you need to pass C<@_> by reference:
- sub foo {
- my ( $self, @args ) = @_;
- try { $self->bar(@args) }
- }
+ sub foo {
+ my ( $self, @args ) = @_;
+ try { $self->bar(@args) }
+ }
or
- sub bar_in_place {
- my $self = shift;
- my $args = \@_;
- try { $_ = $self->bar($_) for @$args }
- }
+ sub bar_in_place {
+ my $self = shift;
+ my $args = \@_;
+ try { $_ = $self->bar($_) for @$args }
+ }
=item *
C<return> returns from the C<try> block, not from the parent sub (note that
this is also how C<eval> works, but not how L<TryCatch> works):
- sub bar {
- try { return "foo" };
- return "baz";
- }
+ sub parent_sub {
+ try {
+ die;
+ }
+ catch {
+ return;
+ };
+
+ say "this text WILL be displayed, even though an exception is thrown";
+ }
- say bar(); # "baz"
+Instead, you should capture the return value:
+
+ sub parent_sub {
+ my $success = try {
+ die;
+ 1;
+ };
+ return unless $success;
+
+ say "This text WILL NEVER appear!";
+ }
+ # OR
+ sub parent_sub_with_catch {
+ my $success = try {
+ die;
+ 1;
+ }
+ catch {
+ # do something with $_
+ return undef; #see note
+ };
+ return unless $success;
+
+ say "This text WILL NEVER appear!";
+ }
+
+Note that if you have a C<catch> block, it must return C<undef> for this to work,
+since if a C<catch> block exists, its return value is returned in place of C<undef>
+when an exception is thrown.
=item *
of the expression for truth on success, be sure to return a false value from
the C<catch> block:
- my $obj = try {
- MightFail->new;
- } catch {
- ...
+ my $obj = try {
+ MightFail->new;
+ } catch {
+ ...
- return; # avoid returning a true value;
- };
+ return; # avoid returning a true value;
+ };
- return unless $obj;
+ return unless $obj;
=item *
For example Perl 5.10's C<given> form uses a lexical C<$_>, creating some
confusing behavior:
- given ($foo) {
- when (...) {
- try {
- ...
- } catch {
- warn $_; # will print $foo, not the error
- warn $_[0]; # instead, get the error like this
- }
- }
- }
+ given ($foo) {
+ when (...) {
+ try {
+ ...
+ } catch {
+ warn $_; # will print $foo, not the error
+ warn $_[0]; # instead, get the error like this
+ }
+ }
+ }
+
+Note that this behavior was changed once again in L<Perl5 version 18
+|https://metacpan.org/module/perldelta#given-now-aliases-the-global-_>.
+However, since the entirety of lexical C<$_> is now L<considired experimental
+|https://metacpan.org/module/perldelta#Lexical-_-is-now-experimental>, it
+is unclear whether the new version 18 behavior is final.
=back
I gave a lightning talk about this module, you can see the slides (Firefox
only):
-L<http://nothingmuch.woobling.org/talks/takahashi.xul?data=yapc_asia_2009/try_tiny.txt>
+L<http://web.archive.org/web/20100628040134/http://nothingmuch.woobling.org/talks/takahashi.xul>
Or read the source:
-L<http://nothingmuch.woobling.org/talks/yapc_asia_2009/try_tiny.yml>
+L<http://web.archive.org/web/20100305133605/http://nothingmuch.woobling.org/talks/yapc_asia_2009/try_tiny.yml>
=head1 VERSION CONTROL
-L<http://github.com/nothingmuch/try-tiny/>
-
-=head1 AUTHOR
-
-Yuval Kogman E<lt>nothingmuch@woobling.orgE<gt>
-
-=head1 COPYRIGHT
-
- Copyright (c) 2009 Yuval Kogman. All rights reserved.
- This program is free software; you can redistribute
- it and/or modify it under the terms of the MIT license.
+L<http://github.com/doy/try-tiny/>
=cut
projects / p5sagit/Try-Tiny.git / blobdiff