X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FTry%2FTiny.pm;h=cf8f1f727898b2f39248419adfc4a6ba49e01301;hb=8447a3bf0e1b88bdd07fa584d83c81c64ad192cf;hp=5ab816083ee0add515614b13f388458f7fd752d6;hpb=6651956b20f3018a9faed6de7634870dbce07721;p=p5sagit%2FTry-Tiny.git diff --git a/lib/Try/Tiny.pm b/lib/Try/Tiny.pm index 5ab8160..cf8f1f7 100644 --- a/lib/Try/Tiny.pm +++ b/lib/Try/Tiny.pm @@ -1,147 +1,196 @@ package Try::Tiny; +use 5.006; +# ABSTRACT: minimal try/catch with proper preservation of $@ + +our $VERSION = '0.25'; use strict; -#use warnings; +use warnings; -use vars qw(@EXPORT @EXPORT_OK $VERSION @ISA); +use Exporter 5.57 'import'; +our @EXPORT = our @EXPORT_OK = qw(try catch finally); -BEGIN { - require Exporter; - @ISA = qw(Exporter); -} +use Carp; +$Carp::Internal{+__PACKAGE__}++; -$VERSION = "0.10"; +BEGIN { + my $su = $INC{'Sub/Util.pm'} && defined &Sub::Util::set_subname; + my $sn = $INC{'Sub/Name.pm'} && eval { Sub::Name->VERSION(0.08) }; + unless ($su || $sn) { + $su = eval { require Sub::Util; } && defined &Sub::Util::set_subname; + unless ($su) { + $sn = eval { require Sub::Name; Sub::Name->VERSION(0.08) }; + } + } -$VERSION = eval $VERSION; + *_subname = $su ? \&Sub::Util::set_subname + : $sn ? \&Sub::Name::subname + : sub { $_[1] }; + *_HAS_SUBNAME = ($su || $sn) ? sub(){1} : sub(){0}; +} -@EXPORT = @EXPORT_OK = qw(try catch finally); - -$Carp::Internal{+__PACKAGE__}++; +my @_finally_guards; # 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 = - 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 - # 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]; - } + 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) + if _HAS_SUBNAME; + + # set up scope guards to invoke the finally blocks at the end. + # this should really be a function scope lexical variable instead of + # file scope + local but that causes issues with perls < 5.20 due to + # perl rt#119311 + local $_finally_guards[0] = [ + map { Try::Tiny::ScopeGuard->_new($_) } + @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 $failed to false + }; + + # preserve the current error and reset the original value of $@ + $error = $@; + $@ = $prev_error; + + # at this point $failed contains a true value if the eval died, even if some + # destructor overwrote $@ as the eval was unwinding. + if ( $failed ) { + # pass $error to the finally blocks + push @$_, $error for @{$_finally_guards[0]}; + + # 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 + # 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, - ); + my $caller = caller; + _subname("${caller}::catch {...} " => $block) + if _HAS_SUBNAME; + 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; + + my $caller = caller; + _subname("${caller}::finally {...} " => $block) + if _HAS_SUBNAME; + return ( + bless(\$block, 'Try::Tiny::Finally'), + @rest, + ); } { package # hide from PAUSE Try::Tiny::ScopeGuard; + use constant UNSTABLE_DOLLARAT => ($] < '5.013002') ? 1 : 0; + sub _new { shift; bless [ @_ ]; } 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" + ; + } } } @@ -151,30 +200,26 @@ __END__ =pod -=head1 NAME - -Try::Tiny - minimal try/catch with proper localization of $@ - =head1 SYNOPSIS You can use Try::Tiny's C and C to expect and handle exceptional conditions, avoiding quirks in Perl and common mistakes: - # 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 stanalone C to catch and ignore any error +You can also use it like a standalone C 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 @@ -182,7 +227,7 @@ This module provides bare bones C/C/C statements that are d minimize common mistakes with eval blocks, and NOTHING else. This is unlike L which provides a nice syntax and avoids adding -another call stack layer, and supports calling C from the try block to +another call stack layer, and supports calling C from the C block to return from the parent subroutine. These extra features come at a cost of a few dependencies, namely L and L which are occasionally problematic, and the additional catch filtering uses L @@ -193,27 +238,36 @@ for those having a hard time installing L, but who still want to write correct C 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) and to be compatible with any style +pathological edge cases (see L) 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 in scalar -context or the empty list in list context. The following two examples both -assign C<"bar"> to C<$x>. +If the C block dies, it returns the value of the last statement executed in +the C block, if there is one. Otherwise, it returns C 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 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 blocks are always executed making them suitable for cleanup code +which cannot be handled using local. You can add as many C blocks to a +given C block as you like. + +Note that adding a C block without a preceding C block +suppresses any errors. This behaviour is consistent with using a standalone +C, but it is not consistent with C/C patterns found in +other programming languages, such as Java, Python, Javascript or C#. If you +learnt the C/C pattern from one of these languages, watch out for +this. =head1 EXPORTS @@ -226,7 +280,7 @@ L to get L's flexibility. =item try (&;@) -Takes one mandatory try subroutine, an optional catch subroutine & finally +Takes one mandatory C subroutine, an optional C subroutine and C subroutine. The mandatory subroutine is evaluated in the context of an C block. @@ -244,9 +298,9 @@ value it had before the C block was executed. Note that the error may be false, but if that happens the C 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 block, if given, will execute. -=item catch (&;$) +=item catch (&;@) Intended to be used in the second argument position of C. @@ -254,9 +308,9 @@ Returns a reference to the subroutine it was given but blessed as C 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 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, but it might be a good idea to preserve it in an error stack. @@ -264,9 +318,9 @@ idea to preserve it in an error stack. For code that captures C<$@> when throwing new errors (i.e. L), you'll need to do: - local $@ = $_; + local $@ = $_; -=item finally (&;$) +=item finally (&;@) try { ... } catch { ... } @@ -283,14 +337,14 @@ Or even finally { ... } catch { ... }; -Intended to be the second or third element of C. Finally blocks are always +Intended to be the second or third element of C. C blocks are always executed in the event of a successful C or if C is run. This allows you to locate cleanup code which cannot be done via C 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. (Note that the finally block does not -localize C<$_> with the error, since unlike in a catch block, there is no way +When invoked, the C block is passed the error that was caught. If no +error was caught, it is passed nothing. (Note that the C block does not +localize C<$_> with the error, since unlike in a C 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: @@ -306,10 +360,15 @@ the following code does just what you would expect: } }; -B. C will +B block>. C will not do anything about handling possible errors coming from code located in these blocks. +Furthermore B blocks are not trappable and are unable +to influence the execution of your program>. This is due to limitation of +C-based scope guards, which C is implemented on top of. This +may change in a future version of Try::Tiny. + In the same way C blesses the code reference this subroutine does the same except it bless them as C. @@ -321,7 +380,7 @@ There are a number of issues with C. =head2 Clobbering $@ -When you run an eval block and it succeeds, C<$@> will be cleared, potentially +When you run an C 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 @@ -334,39 +393,40 @@ More specifically, C<$@> is clobbered at the beginning of the C, which 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 will actually set C<$@> to its previous value (before -the localization) in the beginning of the C block. +For this reason C will actually set C<$@> to its previous value (the one +available before entering the C block) in the beginning of the C +block. =head2 Localizing $@ silently masks errors -Inside an eval block C behaves sort of like: +Inside an C block, C 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. @@ -375,19 +435,19 @@ that's asking for trouble anyway. 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 is not localizing C<$@> but still uses C, it will set C<$@> to C<"">. @@ -398,13 +458,13 @@ been cleared by C in the destructor. 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 was aborted due to an error: - my $failed = not eval { - ... + my $failed = not eval { + ... - return 1; - }; + return 1; + }; This is because an C that caught a C will always return a false value. @@ -413,6 +473,8 @@ value. Using Perl 5.10 you can use L. +=for stopwords topicalizer + The C block is invoked in a topicalizer context (like a C block), but note that you can't return a useful value from C using the C blocks without an explicit C. @@ -420,12 +482,12 @@ blocks without an explicit C. This is somewhat similar to Perl 6's C 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 @@ -434,21 +496,21 @@ concisely match errors: =item * C<@_> is not available within the C block, so you need to copy your -arglist. In case you want to work with argument values directly via C<@_> +argument list. 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 * @@ -456,30 +518,44 @@ C returns from the C block, not from the parent sub (note that this is also how C works, but not how L works): sub parent_sub { - try { - die; - } - catch { - return; - }; + try { + die; + } + catch { + return; + }; - say "this text WILL be displayed, even though an exception is thrown"; + say "this text WILL be displayed, even though an exception is thrown"; } Instead, you should capture the return value: sub parent_sub { - my $success = try { - die; - 1; - } - return unless $success; + 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!"; + say "This text WILL NEVER appear!"; } -Note that if you have a catch block, it must return undef for this to work, -since if a catch block exists, its return value is returned in place of undef +Note that if you have a C block, it must return C for this to work, +since if a C block exists, its return value is returned in place of C when an exception is thrown. =item * @@ -488,11 +564,13 @@ C introduces another caller stack frame. L is not used. L is used. This lack of magic is considered a feature. +=for stopwords unhygienically + =item * The value of C<$_> in the C block is not guaranteed to be the value of the exception thrown (C<$@>) in the C block. There is no safe way to -ensure this, since C may be used unhygenically in destructors. The only +ensure this, since C may be used unhygienically in destructors. The only guarantee is that the C will be called if an exception is thrown. =item * @@ -501,15 +579,15 @@ The return value of the C block is not ignored, so if testing the result of the expression for truth on success, be sure to return a false value from the C 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 * @@ -527,16 +605,22 @@ Lexical C<$_> may override the one set by C. For example Perl 5.10's C 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. +However, since the entirety of lexical C<$_> is now L, it +is unclear whether the new version 18 behavior is final. =back @@ -578,25 +662,15 @@ issues with C<$@>, but you still need to localize to prevent clobbering. I gave a lightning talk about this module, you can see the slides (Firefox only): -L +L Or read the source: -L +L =head1 VERSION CONTROL -L - -=head1 AUTHOR - -Yuval Kogman Enothingmuch@woobling.orgE - -=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 =cut