From: Marc Mims <marc@questright.com>
Date: Thu, 17 Dec 2009 14:15:02 +0000 (-0800)
Subject: Document implicit return value from catch
X-Git-Tag: Try-Tiny-0.03~4
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=a5cd5f73bc9c20976bb6f20c4b2491aab3f0d9d6;p=p5sagit%2FTry-Tiny.git

Document implicit return value from catch

Signed-off-by: Yuval Kogman <nothingmuch@woobling.org>
---

diff --git a/lib/Try/Tiny.pm b/lib/Try/Tiny.pm
index d8d006a..953d4b2 100644
--- a/lib/Try/Tiny.pm
+++ b/lib/Try/Tiny.pm
@@ -132,6 +132,15 @@ 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
 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>.
+
+	my $x = try { die "foo" } catch { "bar" };
+
+	my $x = eval { die "foo" } || "bar";
+
 =head1 EXPORTS
 
 All functions are exported by default using L<Exporter>.
@@ -324,6 +333,22 @@ The value of C<$_> in the C<catch> block is not guaranteed to be preserved,
 there is no safe way to ensure this if C<eval> is used unhygenically in
 destructors. It's only guaranteed that the C<catch> will be called.
 
+=item *
+
+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 {
+		...
+
+		return; # avoid returning a true value;
+	};
+
+	return unless $obj;
+
 =back
 
 =head1 SEE ALSO