1# PAUSE doesn't seem to case about this in t/lib, but just in case ... 2package # Hide from PAUSE 3 Try::Tiny; 4 5use strict; 6#use warnings; 7 8use vars qw(@EXPORT @EXPORT_OK $VERSION @ISA); 9 10BEGIN { 11 require Exporter; 12 @ISA = qw(Exporter); 13} 14 15$VERSION = "0.09"; 16 17$VERSION = eval $VERSION; 18 19@EXPORT = @EXPORT_OK = qw(try catch finally); 20 21$Carp::Internal{+__PACKAGE__}++; 22 23# Need to prototype as @ not $$ because of the way Perl evaluates the prototype. 24# Keeping it at $$ means you only ever get 1 sub because we need to eval in a list 25# context & not a scalar one 26 27sub try (&;@) { 28 my ( $try, @code_refs ) = @_; 29 30 # we need to save this here, the eval block will be in scalar context due 31 # to $failed 32 my $wantarray = wantarray; 33 34 my ( $catch, @finally ); 35 36 # find labeled blocks in the argument list. 37 # catch and finally tag the blocks by blessing a scalar reference to them. 38 foreach my $code_ref (@code_refs) { 39 next unless $code_ref; 40 41 my $ref = ref($code_ref); 42 43 if ( $ref eq 'Try::Tiny::Catch' ) { 44 $catch = ${$code_ref}; 45 } elsif ( $ref eq 'Try::Tiny::Finally' ) { 46 push @finally, ${$code_ref}; 47 } else { 48 use Carp; 49 confess("Unknown code ref type given '${ref}'. Check your usage & try again"); 50 } 51 } 52 53 # save the value of $@ so we can set $@ back to it in the beginning of the eval 54 my $prev_error = $@; 55 56 my ( @ret, $error, $failed ); 57 58 # FIXME consider using local $SIG{__DIE__} to accumulate all errors. It's 59 # not perfect, but we could provide a list of additional errors for 60 # $catch->(); 61 62 { 63 # localize $@ to prevent clobbering of previous value by a successful 64 # eval. 65 local $@; 66 67 # failed will be true if the eval dies, because 1 will not be returned 68 # from the eval body 69 $failed = not eval { 70 $@ = $prev_error; 71 72 # evaluate the try block in the correct context 73 if ( $wantarray ) { 74 @ret = $try->(); 75 } elsif ( defined $wantarray ) { 76 $ret[0] = $try->(); 77 } else { 78 $try->(); 79 }; 80 81 return 1; # properly set $fail to false 82 }; 83 84 # copy $@ to $error; when we leave this scope, local $@ will revert $@ 85 # back to its previous value 86 $error = $@; 87 } 88 89 # set up a scope guard to invoke the finally block at the end 90 my @guards = 91 map { Try::Tiny::ScopeGuard->_new($_, $failed ? $error : ()) } 92 @finally; 93 94 # at this point $failed contains a true value if the eval died, even if some 95 # destructor overwrote $@ as the eval was unwinding. 96 if ( $failed ) { 97 # if we got an error, invoke the catch block. 98 if ( $catch ) { 99 # This works like given($error), but is backwards compatible and 100 # sets $_ in the dynamic scope for the body of C<$catch> 101 for ($error) { 102 return $catch->($error); 103 } 104 105 # in case when() was used without an explicit return, the C<for> 106 # loop will be aborted and there's no useful return value 107 } 108 109 return; 110 } else { 111 # no failure, $@ is back to what it was, everything is fine 112 return $wantarray ? @ret : $ret[0]; 113 } 114} 115 116sub catch (&;@) { 117 my ( $block, @rest ) = @_; 118 119 return ( 120 bless(\$block, 'Try::Tiny::Catch'), 121 @rest, 122 ); 123} 124 125sub finally (&;@) { 126 my ( $block, @rest ) = @_; 127 128 return ( 129 bless(\$block, 'Try::Tiny::Finally'), 130 @rest, 131 ); 132} 133 134{ 135 package # hide from PAUSE 136 Try::Tiny::ScopeGuard; 137 138 sub _new { 139 shift; 140 bless [ @_ ]; 141 } 142 143 sub DESTROY { 144 my @guts = @{ shift() }; 145 my $code = shift @guts; 146 $code->(@guts); 147 } 148} 149 150__PACKAGE__ 151 152__END__ 153 154=pod 155 156=head1 NAME 157 158Try::Tiny - minimal try/catch with proper localization of $@ 159 160=head1 SYNOPSIS 161 162 # handle errors with a catch handler 163 try { 164 die "foo"; 165 } catch { 166 warn "caught error: $_"; # not $@ 167 }; 168 169 # just silence errors 170 try { 171 die "foo"; 172 }; 173 174=head1 DESCRIPTION 175 176This module provides bare bones C<try>/C<catch>/C<finally> statements that are designed to 177minimize common mistakes with eval blocks, and NOTHING else. 178 179This is unlike L<TryCatch> which provides a nice syntax and avoids adding 180another call stack layer, and supports calling C<return> from the try block to 181return from the parent subroutine. These extra features come at a cost of a few 182dependencies, namely L<Devel::Declare> and L<Scope::Upper> which are 183occasionally problematic, and the additional catch filtering uses L<Moose> 184type constraints which may not be desirable either. 185 186The main focus of this module is to provide simple and reliable error handling 187for those having a hard time installing L<TryCatch>, but who still want to 188write correct C<eval> blocks without 5 lines of boilerplate each time. 189 190It's designed to work as correctly as possible in light of the various 191pathological edge cases (see L<BACKGROUND>) and to be compatible with any style 192of error values (simple strings, references, objects, overloaded objects, etc). 193 194If the try block dies, it returns the value of the last statement executed in 195the catch block, if there is one. Otherwise, it returns C<undef> in scalar 196context or the empty list in list context. The following two examples both 197assign C<"bar"> to C<$x>. 198 199 my $x = try { die "foo" } catch { "bar" }; 200 201 my $x = eval { die "foo" } || "bar"; 202 203You can add finally blocks making the following true. 204 205 my $x; 206 try { die 'foo' } finally { $x = 'bar' }; 207 try { die 'foo' } catch { warn "Got a die: $_" } finally { $x = 'bar' }; 208 209Finally blocks are always executed making them suitable for cleanup code 210which cannot be handled using local. You can add as many finally blocks to a 211given try block as you like. 212 213=head1 EXPORTS 214 215All functions are exported by default using L<Exporter>. 216 217If you need to rename the C<try>, C<catch> or C<finally> keyword consider using 218L<Sub::Import> to get L<Sub::Exporter>'s flexibility. 219 220=over 4 221 222=item try (&;@) 223 224Takes one mandatory try subroutine, an optional catch subroutine & finally 225subroutine. 226 227The mandatory subroutine is evaluated in the context of an C<eval> block. 228 229If no error occurred the value from the first block is returned, preserving 230list/scalar context. 231 232If there was an error and the second subroutine was given it will be invoked 233with the error in C<$_> (localized) and as that block's first and only 234argument. 235 236C<$@> does B<not> contain the error. Inside the C<catch> block it has the same 237value it had before the C<try> block was executed. 238 239Note that the error may be false, but if that happens the C<catch> block will 240still be invoked. 241 242Once all execution is finished then the finally block if given will execute. 243 244=item catch (&;$) 245 246Intended to be used in the second argument position of C<try>. 247 248Returns a reference to the subroutine it was given but blessed as 249C<Try::Tiny::Catch> which allows try to decode correctly what to do 250with this code reference. 251 252 catch { ... } 253 254Inside the catch block the caught error is stored in C<$_>, while previous 255value of C<$@> is still available for use. This value may or may not be 256meaningful depending on what happened before the C<try>, but it might be a good 257idea to preserve it in an error stack. 258 259For code that captures C<$@> when throwing new errors (i.e. 260L<Class::Throwable>), you'll need to do: 261 262 local $@ = $_; 263 264=item finally (&;$) 265 266 try { ... } 267 catch { ... } 268 finally { ... }; 269 270Or 271 272 try { ... } 273 finally { ... }; 274 275Or even 276 277 try { ... } 278 finally { ... } 279 catch { ... }; 280 281Intended to be the second or third element of C<try>. Finally blocks are always 282executed in the event of a successful C<try> or if C<catch> is run. This allows 283you to locate cleanup code which cannot be done via C<local()> e.g. closing a file 284handle. 285 286When invoked, the finally block is passed the error that was caught. If no 287error was caught, it is passed nothing. In other words, the following code 288does just what you would expect: 289 290 try { 291 die_sometimes(); 292 } catch { 293 # ...code run in case of error 294 } finally { 295 if (@_) { 296 print "The try block died with: @_\n"; 297 } else { 298 print "The try block ran without error.\n"; 299 } 300 }; 301 302B<You must always do your own error handling in the finally block>. C<Try::Tiny> will 303not do anything about handling possible errors coming from code located in these 304blocks. 305 306In the same way C<catch()> blesses the code reference this subroutine does the same 307except it bless them as C<Try::Tiny::Finally>. 308 309=back 310 311=head1 BACKGROUND 312 313There are a number of issues with C<eval>. 314 315=head2 Clobbering $@ 316 317When you run an eval block and it succeeds, C<$@> will be cleared, potentially 318clobbering an error that is currently being caught. 319 320This causes action at a distance, clearing previous errors your caller may have 321not yet handled. 322 323C<$@> must be properly localized before invoking C<eval> in order to avoid this 324issue. 325 326More specifically, C<$@> is clobbered at the beginning of the C<eval>, which 327also makes it impossible to capture the previous error before you die (for 328instance when making exception objects with error stacks). 329 330For this reason C<try> will actually set C<$@> to its previous value (before 331the localization) in the beginning of the C<eval> block. 332 333=head2 Localizing $@ silently masks errors 334 335Inside an eval block C<die> behaves sort of like: 336 337 sub die { 338 $@ = $_[0]; 339 return_undef_from_eval(); 340 } 341 342This means that if you were polite and localized C<$@> you can't die in that 343scope, or your error will be discarded (printing "Something's wrong" instead). 344 345The workaround is very ugly: 346 347 my $error = do { 348 local $@; 349 eval { ... }; 350 $@; 351 }; 352 353 ... 354 die $error; 355 356=head2 $@ might not be a true value 357 358This code is wrong: 359 360 if ( $@ ) { 361 ... 362 } 363 364because due to the previous caveats it may have been unset. 365 366C<$@> could also be an overloaded error object that evaluates to false, but 367that's asking for trouble anyway. 368 369The classic failure mode is: 370 371 sub Object::DESTROY { 372 eval { ... } 373 } 374 375 eval { 376 my $obj = Object->new; 377 378 die "foo"; 379 }; 380 381 if ( $@ ) { 382 383 } 384 385In this case since C<Object::DESTROY> is not localizing C<$@> but still uses 386C<eval>, it will set C<$@> to C<"">. 387 388The destructor is called when the stack is unwound, after C<die> sets C<$@> to 389C<"foo at Foo.pm line 42\n">, so by the time C<if ( $@ )> is evaluated it has 390been cleared by C<eval> in the destructor. 391 392The workaround for this is even uglier than the previous ones. Even though we 393can't save the value of C<$@> from code that doesn't localize, we can at least 394be sure the eval was aborted due to an error: 395 396 my $failed = not eval { 397 ... 398 399 return 1; 400 }; 401 402This is because an C<eval> that caught a C<die> will always return a false 403value. 404 405=head1 SHINY SYNTAX 406 407Using Perl 5.10 you can use L<perlsyn/"Switch statements">. 408 409The C<catch> block is invoked in a topicalizer context (like a C<given> block), 410but note that you can't return a useful value from C<catch> using the C<when> 411blocks without an explicit C<return>. 412 413This is somewhat similar to Perl 6's C<CATCH> blocks. You can use it to 414concisely match errors: 415 416 try { 417 require Foo; 418 } catch { 419 when (/^Can't locate .*?\.pm in \@INC/) { } # ignore 420 default { die $_ } 421 }; 422 423=head1 CAVEATS 424 425=over 4 426 427=item * 428 429C<@_> is not available within the C<try> block, so you need to copy your 430arglist. In case you want to work with argument values directly via C<@_> 431aliasing (i.e. allow C<$_[1] = "foo">), you need to pass C<@_> by reference: 432 433 sub foo { 434 my ( $self, @args ) = @_; 435 try { $self->bar(@args) } 436 } 437 438or 439 440 sub bar_in_place { 441 my $self = shift; 442 my $args = \@_; 443 try { $_ = $self->bar($_) for @$args } 444 } 445 446=item * 447 448C<return> returns from the C<try> block, not from the parent sub (note that 449this is also how C<eval> works, but not how L<TryCatch> works): 450 451 sub bar { 452 try { return "foo" }; 453 return "baz"; 454 } 455 456 say bar(); # "baz" 457 458=item * 459 460C<try> introduces another caller stack frame. L<Sub::Uplevel> is not used. L<Carp> 461will not report this when using full stack traces, though, because 462C<%Carp::Internal> is used. This lack of magic is considered a feature. 463 464=item * 465 466The value of C<$_> in the C<catch> block is not guaranteed to be the value of 467the exception thrown (C<$@>) in the C<try> block. There is no safe way to 468ensure this, since C<eval> may be used unhygenically in destructors. The only 469guarantee is that the C<catch> will be called if an exception is thrown. 470 471=item * 472 473The return value of the C<catch> block is not ignored, so if testing the result 474of the expression for truth on success, be sure to return a false value from 475the C<catch> block: 476 477 my $obj = try { 478 MightFail->new; 479 } catch { 480 ... 481 482 return; # avoid returning a true value; 483 }; 484 485 return unless $obj; 486 487=item * 488 489C<$SIG{__DIE__}> is still in effect. 490 491Though it can be argued that C<$SIG{__DIE__}> should be disabled inside of 492C<eval> blocks, since it isn't people have grown to rely on it. Therefore in 493the interests of compatibility, C<try> does not disable C<$SIG{__DIE__}> for 494the scope of the error throwing code. 495 496=item * 497 498Lexical C<$_> may override the one set by C<catch>. 499 500For example Perl 5.10's C<given> form uses a lexical C<$_>, creating some 501confusing behavior: 502 503 given ($foo) { 504 when (...) { 505 try { 506 ... 507 } catch { 508 warn $_; # will print $foo, not the error 509 warn $_[0]; # instead, get the error like this 510 } 511 } 512 } 513 514=back 515 516=head1 SEE ALSO 517 518=over 4 519 520=item L<TryCatch> 521 522Much more feature complete, more convenient semantics, but at the cost of 523implementation complexity. 524 525=item L<autodie> 526 527Automatic error throwing for builtin functions and more. Also designed to 528work well with C<given>/C<when>. 529 530=item L<Throwable> 531 532A lightweight role for rolling your own exception classes. 533 534=item L<Error> 535 536Exception object implementation with a C<try> statement. Does not localize 537C<$@>. 538 539=item L<Exception::Class::TryCatch> 540 541Provides a C<catch> statement, but properly calling C<eval> is your 542responsibility. 543 544The C<try> keyword pushes C<$@> onto an error stack, avoiding some of the 545issues with C<$@>, but you still need to localize to prevent clobbering. 546 547=back 548 549=head1 LIGHTNING TALK 550 551I gave a lightning talk about this module, you can see the slides (Firefox 552only): 553 554L<http://nothingmuch.woobling.org/talks/takahashi.xul?data=yapc_asia_2009/try_tiny.txt> 555 556Or read the source: 557 558L<http://nothingmuch.woobling.org/talks/yapc_asia_2009/try_tiny.yml> 559 560=head1 VERSION CONTROL 561 562L<http://github.com/nothingmuch/try-tiny/> 563 564=head1 AUTHOR 565 566Yuval Kogman E<lt>nothingmuch@woobling.orgE<gt> 567 568=head1 COPYRIGHT 569 570 Copyright (c) 2009 Yuval Kogman. All rights reserved. 571 This program is free software; you can redistribute 572 it and/or modify it under the terms of the MIT license. 573 574=cut 575 576