X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FTry%2FTiny.pm;h=91307b465bd7105d4fae21814641b9df89224293;hb=79039ae433128d824ddf3d930909434f9fe645d3;hp=795272ea0d1bcf0916a96716deecf4e237dc4c4b;hpb=a23583177076f06ceaf21f8a403cb8966aeb3802;p=p5sagit%2FTry-Tiny.git

diff --git a/lib/Try/Tiny.pm b/lib/Try/Tiny.pm
index 795272e..91307b4 100644
--- a/lib/Try/Tiny.pm
+++ b/lib/Try/Tiny.pm
@@ -1,147 +1,166 @@
 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.09";
-
-$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 # 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 +170,26 @@ __END__
 
 =pod
 
-=head1 NAME
-
-Try::Tiny - minimal try/catch with proper localization of $@
-
 =head1 SYNOPSIS
 
 You can use Try::Tiny's C<try> and C<catch> 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<eval> to catch and ignore any error
+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
 
@@ -182,7 +197,7 @@ This module provides bare bones C<try>/C<catch>/C<finally> statements that are d
 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>
@@ -193,27 +208,36 @@ for those having a hard time installing L<TryCatch>, but who still want to
 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
 
@@ -226,7 +250,7 @@ L<Sub::Import> to get L<Sub::Exporter>'s flexibility.
 
 =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.
@@ -244,9 +268,9 @@ value it had before the C<try> block was executed.
 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>.
 
@@ -254,9 +278,9 @@ Returns a reference to the subroutine it was given but blessed as
 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.
@@ -264,9 +288,9 @@ 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   { ... }
@@ -283,14 +307,16 @@ Or even
   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();
@@ -304,10 +330,15 @@ does just what you would expect:
     }
   };
 
-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>.
 
@@ -319,7 +350,7 @@ There are a number of issues with C<eval>.
 
 =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
@@ -332,39 +363,40 @@ More specifically, C<$@> is clobbered at the beginning of the C<eval>, 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<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.
 
@@ -373,19 +405,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<Object::DESTROY> is not localizing C<$@> but still uses
 C<eval>, it will set C<$@> to C<"">.
@@ -396,13 +428,13 @@ been cleared by C<eval> 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<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.
@@ -418,12 +450,12 @@ blocks without an explicit C<return>.
 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
 
@@ -435,30 +467,64 @@ C<@_> is not available within the C<try> block, so you need to copy your
 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 *
 
@@ -479,15 +545,15 @@ The return value of the C<catch> 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<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 *
 
@@ -505,16 +571,22 @@ Lexical C<$_> may override the one set by C<catch>.
 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
 
@@ -556,25 +628,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<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