Add warning to POD about try/finally

[p5sagit/Try-Tiny.git] / lib / Try / Tiny.pm

diff --git a/lib/Try/Tiny.pm b/lib/Try/Tiny.pm
index bf2a91e..91307b4 100644 (file)
--- a/lib/Try/Tiny.pm
+++ b/lib/Try/Tiny.pm
@@ -5,7 +5,7 @@ use 5.006;
 use strict;
 use warnings;
 
-use base 'Exporter';
+use Exporter 5.57 'import';
 our @EXPORT = our @EXPORT_OK = qw(try catch finally);
 
 use Carp;
@@ -24,7 +24,9 @@ sub try (&;@) {
   # to $failed
   my $wantarray = wantarray;
 
-  my ( $catch, @finally );
+  # 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.
@@ -51,7 +53,7 @@ sub try (&;@) {
 
   # name the blocks if we have Sub::Name installed
   my $caller = caller;
-  subname("${caller}::try {...}" => $try);
+  subname("${caller}::try {...} " => $try);
   subname("${caller}::catch {...} " => $catch) if $catch;
   subname("${caller}::finally {...} " => $_) foreach @finally;
 
@@ -230,6 +232,13 @@ 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
 
 All functions are exported by default using L<Exporter>.
@@ -493,7 +502,21 @@ Instead, you should capture the return value:
     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!";