README.pod

   1 =pod
   2
   3 =encoding UTF-8
   4
   5 =head1 NAME
   6
   7 Try::Tiny - Minimal try/catch with proper preservation of $@
   8
   9 =head1 VERSION
  10
  11 version 0.31
  12
  13 =head1 SYNOPSIS
  14
  15 You can use Try::Tiny's C<try> and C<catch> to expect and handle exceptional
  16 conditions, avoiding quirks in Perl and common mistakes:
  17
  18   # handle errors with a catch handler
  19   try {
  20     die "foo";
  21   } catch {
  22     warn "caught error: $_"; # not $@
  23   };
  24
  25 You can also use it like a standalone C<eval> to catch and ignore any error
  26 conditions.  Obviously, this is an extreme measure not to be undertaken
  27 lightly:
  28
  29   # just silence errors
  30   try {
  31     die "foo";
  32   };
  33
  34 =head1 DESCRIPTION
  35
  36 This module provides bare bones C<try>/C<catch>/C<finally> statements that are designed to
  37 minimize common mistakes with eval blocks, and NOTHING else.
  38
  39 This is unlike L<TryCatch> which provides a nice syntax and avoids adding
  40 another call stack layer, and supports calling C<return> from the C<try> block to
  41 return from the parent subroutine. These extra features come at a cost of a few
  42 dependencies, namely L<Devel::Declare> and L<Scope::Upper> which are
  43 occasionally problematic, and the additional catch filtering uses L<Moose>
  44 type constraints which may not be desirable either.
  45
  46 The main focus of this module is to provide simple and reliable error handling
  47 for those having a hard time installing L<TryCatch>, but who still want to
  48 write correct C<eval> blocks without 5 lines of boilerplate each time.
  49
  50 It's designed to work as correctly as possible in light of the various
  51 pathological edge cases (see L</BACKGROUND>) and to be compatible with any style
  52 of error values (simple strings, references, objects, overloaded objects, etc).
  53
  54 If the C<try> block dies, it returns the value of the last statement executed in
  55 the C<catch> block, if there is one. Otherwise, it returns C<undef> in scalar
  56 context or the empty list in list context. The following examples all
  57 assign C<"bar"> to C<$x>:
  58
  59   my $x = try { die "foo" } catch { "bar" };
  60   my $x = try { die "foo" } || "bar";
  61   my $x = (try { die "foo" }) // "bar";
  62
  63   my $x = eval { die "foo" } || "bar";
  64
  65 You can add C<finally> blocks, yielding the following:
  66
  67   my $x;
  68   try { die 'foo' } finally { $x = 'bar' };
  69   try { die 'foo' } catch { warn "Got a die: $_" } finally { $x = 'bar' };
  70
  71 C<finally> blocks are always executed making them suitable for cleanup code
  72 which cannot be handled using local.  You can add as many C<finally> blocks to a
  73 given C<try> block as you like.
  74
  75 Note that adding a C<finally> block without a preceding C<catch> block
  76 suppresses any errors. This behaviour is consistent with using a standalone
  77 C<eval>, but it is not consistent with C<try>/C<finally> patterns found in
  78 other programming languages, such as Java, Python, Javascript or C#. If you
  79 learned the C<try>/C<finally> pattern from one of these languages, watch out for
  80 this.
  81
  82 =head1 EXPORTS
  83
  84 All functions are exported by default using L<Exporter>.
  85
  86 If you need to rename the C<try>, C<catch> or C<finally> keyword consider using
  87 L<Sub::Import> to get L<Sub::Exporter>'s flexibility.
  88
  89 =over 4
  90
  91 =item try (&;@)
  92
  93 Takes one mandatory C<try> subroutine, an optional C<catch> subroutine and C<finally>
  94 subroutine.
  95
  96 The mandatory subroutine is evaluated in the context of an C<eval> block.
  97
  98 If no error occurred the value from the first block is returned, preserving
  99 list/scalar context.
 100
 101 If there was an error and the second subroutine was given it will be invoked
 102 with the error in C<$_> (localized) and as that block's first and only
 103 argument.
 104
 105 C<$@> does B<not> contain the error. Inside the C<catch> block it has the same
 106 value it had before the C<try> block was executed.
 107
 108 Note that the error may be false, but if that happens the C<catch> block will
 109 still be invoked.
 110
 111 Once all execution is finished then the C<finally> block, if given, will execute.
 112
 113 =item catch (&;@)
 114
 115 Intended to be used in the second argument position of C<try>.
 116
 117 Returns a reference to the subroutine it was given but blessed as
 118 C<Try::Tiny::Catch> which allows try to decode correctly what to do
 119 with this code reference.
 120
 121   catch { ... }
 122
 123 Inside the C<catch> block the caught error is stored in C<$_>, while previous
 124 value of C<$@> is still available for use.  This value may or may not be
 125 meaningful depending on what happened before the C<try>, but it might be a good
 126 idea to preserve it in an error stack.
 127
 128 For code that captures C<$@> when throwing new errors (i.e.
 129 L<Class::Throwable>), you'll need to do:
 130
 131   local $@ = $_;
 132
 133 =item finally (&;@)
 134
 135   try     { ... }
 136   catch   { ... }
 137   finally { ... };
 138
 139 Or
 140
 141   try     { ... }
 142   finally { ... };
 143
 144 Or even
 145
 146   try     { ... }
 147   finally { ... }
 148   catch   { ... };
 149
 150 Intended to be the second or third element of C<try>. C<finally> blocks are always
 151 executed in the event of a successful C<try> or if C<catch> is run. This allows
 152 you to locate cleanup code which cannot be done via C<local()> e.g. closing a file
 153 handle.
 154
 155 When invoked, the C<finally> block is passed the error that was caught.  If no
 156 error was caught, it is passed nothing.  (Note that the C<finally> block does not
 157 localize C<$_> with the error, since unlike in a C<catch> block, there is no way
 158 to know if C<$_ == undef> implies that there were no errors.) In other words,
 159 the following code does just what you would expect:
 160
 161   try {
 162     die_sometimes();
 163   } catch {
 164     # ...code run in case of error
 165   } finally {
 166     if (@_) {
 167       print "The try block died with: @_\n";
 168     } else {
 169       print "The try block ran without error.\n";
 170     }
 171   };
 172
 173 B<You must always do your own error handling in the C<finally> block>. C<Try::Tiny> will
 174 not do anything about handling possible errors coming from code located in these
 175 blocks.
 176
 177 Furthermore B<exceptions in C<finally> blocks are not trappable and are unable
 178 to influence the execution of your program>. This is due to limitation of
 179 C<DESTROY>-based scope guards, which C<finally> is implemented on top of. This
 180 may change in a future version of Try::Tiny.
 181
 182 In the same way C<catch()> blesses the code reference this subroutine does the same
 183 except it bless them as C<Try::Tiny::Finally>.
 184
 185 =back
 186
 187 =head1 BACKGROUND
 188
 189 There are a number of issues with C<eval>.
 190
 191 =head2 Clobbering $@
 192
 193 When you run an C<eval> block and it succeeds, C<$@> will be cleared, potentially
 194 clobbering an error that is currently being caught.
 195
 196 This causes action at a distance, clearing previous errors your caller may have
 197 not yet handled.
 198
 199 C<$@> must be properly localized before invoking C<eval> in order to avoid this
 200 issue.
 201
 202 More specifically,
 203 L<before Perl version 5.14.0|perl5140delta/"Exception Handling">
 204 C<$@> was clobbered at the beginning of the C<eval>, which
 205 also made it impossible to capture the previous error before you die (for
 206 instance when making exception objects with error stacks).
 207
 208 For this reason C<try> will actually set C<$@> to its previous value (the one
 209 available before entering the C<try> block) in the beginning of the C<eval>
 210 block.
 211
 212 =head2 Localizing $@ silently masks errors
 213
 214 Inside an C<eval> block, C<die> behaves sort of like:
 215
 216   sub die {
 217     $@ = $_[0];
 218     return_undef_from_eval();
 219   }
 220
 221 This means that if you were polite and localized C<$@> you can't die in that
 222 scope, or your error will be discarded (printing "Something's wrong" instead).
 223
 224 The workaround is very ugly:
 225
 226   my $error = do {
 227     local $@;
 228     eval { ... };
 229     $@;
 230   };
 231
 232   ...
 233   die $error;
 234
 235 =head2 $@ might not be a true value
 236
 237 This code is wrong:
 238
 239   if ( $@ ) {
 240     ...
 241   }
 242
 243 because due to the previous caveats it may have been unset.
 244
 245 C<$@> could also be an overloaded error object that evaluates to false, but
 246 that's asking for trouble anyway.
 247
 248 The classic failure mode (fixed in L<Perl 5.14.0|perl5140delta/"Exception Handling">) is:
 249
 250   sub Object::DESTROY {
 251     eval { ... }
 252   }
 253
 254   eval {
 255     my $obj = Object->new;
 256
 257     die "foo";
 258   };
 259
 260   if ( $@ ) {
 261
 262   }
 263
 264 In this case since C<Object::DESTROY> is not localizing C<$@> but still uses
 265 C<eval>, it will set C<$@> to C<"">.
 266
 267 The destructor is called when the stack is unwound, after C<die> sets C<$@> to
 268 C<"foo at Foo.pm line 42\n">, so by the time C<if ( $@ )> is evaluated it has
 269 been cleared by C<eval> in the destructor.
 270
 271 The workaround for this is even uglier than the previous ones. Even though we
 272 can't save the value of C<$@> from code that doesn't localize, we can at least
 273 be sure the C<eval> was aborted due to an error:
 274
 275   my $failed = not eval {
 276     ...
 277
 278     return 1;
 279   };
 280
 281 This is because an C<eval> that caught a C<die> will always return a false
 282 value.
 283
 284 =head1 ALTERNATE SYNTAX
 285
 286 Using Perl 5.10 you can use L<perlsyn/"Switch statements"> (but please don't,
 287 because that syntax has since been deprecated because there was too much
 288 unexpected magical behaviour).
 289
 290 =for stopwords topicalizer
 291
 292 The C<catch> block is invoked in a topicalizer context (like a C<given> block),
 293 but note that you can't return a useful value from C<catch> using the C<when>
 294 blocks without an explicit C<return>.
 295
 296 This is somewhat similar to Perl 6's C<CATCH> blocks. You can use it to
 297 concisely match errors:
 298
 299   try {
 300     require Foo;
 301   } catch {
 302     when (/^Can't locate .*?\.pm in \@INC/) { } # ignore
 303     default { die $_ }
 304   };
 305
 306 =head1 CAVEATS
 307
 308 =over 4
 309
 310 =item *
 311
 312 C<@_> is not available within the C<try> block, so you need to copy your
 313 argument list. In case you want to work with argument values directly via C<@_>
 314 aliasing (i.e. allow C<$_[1] = "foo">), you need to pass C<@_> by reference:
 315
 316   sub foo {
 317     my ( $self, @args ) = @_;
 318     try { $self->bar(@args) }
 319   }
 320
 321 or
 322
 323   sub bar_in_place {
 324     my $self = shift;
 325     my $args = \@_;
 326     try { $_ = $self->bar($_) for @$args }
 327   }
 328
 329 =item *
 330
 331 C<return> returns from the C<try> block, not from the parent sub (note that
 332 this is also how C<eval> works, but not how L<TryCatch> works):
 333
 334   sub parent_sub {
 335     try {
 336       die;
 337     }
 338     catch {
 339       return;
 340     };
 341
 342     say "this text WILL be displayed, even though an exception is thrown";
 343   }
 344
 345 Instead, you should capture the return value:
 346
 347   sub parent_sub {
 348     my $success = try {
 349       die;
 350       1;
 351     };
 352     return unless $success;
 353
 354     say "This text WILL NEVER appear!";
 355   }
 356   # OR
 357   sub parent_sub_with_catch {
 358     my $success = try {
 359       die;
 360       1;
 361     }
 362     catch {
 363       # do something with $_
 364       return undef; #see note
 365     };
 366     return unless $success;
 367
 368     say "This text WILL NEVER appear!";
 369   }
 370
 371 Note that if you have a C<catch> block, it must return C<undef> for this to work,
 372 since if a C<catch> block exists, its return value is returned in place of C<undef>
 373 when an exception is thrown.
 374
 375 =item *
 376
 377 C<try> introduces another caller stack frame. L<Sub::Uplevel> is not used. L<Carp>
 378 will not report this when using full stack traces, though, because
 379 C<%Carp::Internal> is used. This lack of magic is considered a feature.
 380
 381 =for stopwords unhygienically
 382
 383 =item *
 384
 385 The value of C<$_> in the C<catch> block is not guaranteed to be the value of
 386 the exception thrown (C<$@>) in the C<try> block.  There is no safe way to
 387 ensure this, since C<eval> may be used unhygienically in destructors.  The only
 388 guarantee is that the C<catch> will be called if an exception is thrown.
 389
 390 =item *
 391
 392 The return value of the C<catch> block is not ignored, so if testing the result
 393 of the expression for truth on success, be sure to return a false value from
 394 the C<catch> block:
 395
 396   my $obj = try {
 397     MightFail->new;
 398   } catch {
 399     ...
 400
 401     return; # avoid returning a true value;
 402   };
 403
 404   return unless $obj;
 405
 406 =item *
 407
 408 C<$SIG{__DIE__}> is still in effect.
 409
 410 Though it can be argued that C<$SIG{__DIE__}> should be disabled inside of
 411 C<eval> blocks, since it isn't people have grown to rely on it. Therefore in
 412 the interests of compatibility, C<try> does not disable C<$SIG{__DIE__}> for
 413 the scope of the error throwing code.
 414
 415 =item *
 416
 417 Lexical C<$_> may override the one set by C<catch>.
 418
 419 For example Perl 5.10's C<given> form uses a lexical C<$_>, creating some
 420 confusing behavior:
 421
 422   given ($foo) {
 423     when (...) {
 424       try {
 425         ...
 426       } catch {
 427         warn $_; # will print $foo, not the error
 428         warn $_[0]; # instead, get the error like this
 429       }
 430     }
 431   }
 432
 433 Note that this behavior was changed once again in
 434 L<Perl5 version 18|https://metacpan.org/module/perldelta#given-now-aliases-the-global-_>.
 435 However, since the entirety of lexical C<$_> is now L<considered experimental
 436 |https://metacpan.org/module/perldelta#Lexical-_-is-now-experimental>, it
 437 is unclear whether the new version 18 behavior is final.
 438
 439 =back
 440
 441 =head1 SEE ALSO
 442
 443 =over 4
 444
 445 =item L<Syntax::Keyword::Try>
 446
 447 Only available on perls >= 5.14, with a slightly different syntax (e.g. no trailing C<;> because
 448 it's actually a keyword, not a sub, but this means you can C<return> and C<next> within it). Use
 449 L<Feature::Compat::Try> to automatically switch to the native C<try> syntax in newer perls (when
 450 available). See also L<Try Catch Exception Handling|perlsyn/Try-Catch-Exception-Handling>.
 451
 452 =item L<TryCatch>
 453
 454 Much more feature complete, more convenient semantics, but at the cost of
 455 implementation complexity.
 456
 457 =item L<autodie>
 458
 459 Automatic error throwing for builtin functions and more. Also designed to
 460 work well with C<given>/C<when>.
 461
 462 =item L<Throwable>
 463
 464 A lightweight role for rolling your own exception classes.
 465
 466 =item L<Error>
 467
 468 Exception object implementation with a C<try> statement. Does not localize
 469 C<$@>.
 470
 471 =item L<Exception::Class::TryCatch>
 472
 473 Provides a C<catch> statement, but properly calling C<eval> is your
 474 responsibility.
 475
 476 The C<try> keyword pushes C<$@> onto an error stack, avoiding some of the
 477 issues with C<$@>, but you still need to localize to prevent clobbering.
 478
 479 =back
 480
 481 =head1 LIGHTNING TALK
 482
 483 I gave a lightning talk about this module, you can see the slides (Firefox
 484 only):
 485
 486 L<http://web.archive.org/web/20100628040134/http://nothingmuch.woobling.org/talks/takahashi.xul>
 487
 488 Or read the source:
 489
 490 L<http://web.archive.org/web/20100305133605/http://nothingmuch.woobling.org/talks/yapc_asia_2009/try_tiny.yml>
 491
 492 =head1 SUPPORT
 493
 494 Bugs may be submitted through L<the RT bug tracker|https://rt.cpan.org/Public/Dist/Display.html?Name=Try-Tiny>
 495 (or L<bug-Try-Tiny@rt.cpan.org|mailto:bug-Try-Tiny@rt.cpan.org>).
 496
 497 =head1 AUTHORS
 498
 499 =over 4
 500
 501 =item *
 502
 503 יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
 504
 505 =item *
 506
 507 Jesse Luehrs <doy@tozt.net>
 508
 509 =back
 510
 511 =head1 CONTRIBUTORS
 512
 513 =for stopwords Karen Etheridge Peter Rabbitson Ricardo Signes Mark Fowler Graham Knop Aristotle Pagaltzis Dagfinn Ilmari Mannsåker Lukas Mai Alex anaxagoras Andrew Yates awalker chromatic cm-perl David Lowe Glenn Hans Dieter Pearcey Jens Berthold Jonathan Yu Marc Mims Stosberg Pali Paul Howarth Rudolf Leermakers
 514
 515 =over 4
 516
 517 =item *
 518
 519 Karen Etheridge <ether@cpan.org>
 520
 521 =item *
 522
 523 Peter Rabbitson <ribasushi@cpan.org>
 524
 525 =item *
 526
 527 Ricardo Signes <rjbs@cpan.org>
 528
 529 =item *
 530
 531 Mark Fowler <mark@twoshortplanks.com>
 532
 533 =item *
 534
 535 Graham Knop <haarg@haarg.org>
 536
 537 =item *
 538
 539 Aristotle Pagaltzis <pagaltzis@gmx.de>
 540
 541 =item *
 542
 543 Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
 544
 545 =item *
 546
 547 Lukas Mai <l.mai@web.de>
 548
 549 =item *
 550
 551 Alex <alex@koban.(none)>
 552
 553 =item *
 554
 555 anaxagoras <walkeraj@gmail.com>
 556
 557 =item *
 558
 559 Andrew Yates <ayates@haddock.local>
 560
 561 =item *
 562
 563 awalker <awalker@sourcefire.com>
 564
 565 =item *
 566
 567 chromatic <chromatic@wgz.org>
 568
 569 =item *
 570
 571 cm-perl <cm-perl@users.noreply.github.com>
 572
 573 =item *
 574
 575 David Lowe <davidl@lokku.com>
 576
 577 =item *
 578
 579 Glenn Fowler <cebjyre@cpan.org>
 580
 581 =item *
 582
 583 Hans Dieter Pearcey <hdp@weftsoar.net>
 584
 585 =item *
 586
 587 Jens Berthold <jens@jebecs.de>
 588
 589 =item *
 590
 591 Jonathan Yu <JAWNSY@cpan.org>
 592
 593 =item *
 594
 595 Marc Mims <marc@questright.com>
 596
 597 =item *
 598
 599 Mark Stosberg <mark@stosberg.com>
 600
 601 =item *
 602
 603 Pali <pali@cpan.org>
 604
 605 =item *
 606
 607 Paul Howarth <paul@city-fan.org>
 608
 609 =item *
 610
 611 Rudolf Leermakers <rudolf@hatsuseno.org>
 612
 613 =back
 614
 615 =head1 COPYRIGHT AND LICENCE
 616
 617 This software is Copyright (c) 2009 by יובל קוג'מן (Yuval Kogman).
 618
 619 This is free software, licensed under:
 620
 621   The MIT (X11) License
 622
 623 =cut