Permalink
Browse files

document Failure

  • Loading branch information...
1 parent b7cae64 commit 91e7c16f15956c53ffaafa445e4d473acdbec0ca @moritz moritz committed Aug 10, 2012
Showing with 50 additions and 0 deletions.
  1. +50 −0 lib/Failure.pod
View
@@ -0,0 +1,50 @@
+=begin pod
+
+=TITLE class Failure
+
+ class Failure { }
+
+A C<Failure> is a I<soft> or I<unthrown> exception, usually generated by
+calling C<&fail>. It acts as a wrapper around an L<Exception> object.
+
+Sink (void) context causes a Failure to throw, i.e. turn into a normal
+exception.
+
+Checking a Failure for truth (with the C<Bool> method) or definedness (with
+the C<defined> method) marks the failure as handled, and causes it not to
+throw in sink context anymore.
+
+You can call the C<handled> method to check if a failure has been handled.
+
+Calling methods on unhandled failures propagates the failure. The
+specification says the result is another C<Failure>, in Rakudo it causes the
+failure to throw.
+
+=head1 Methods
+
+=head2 handled
+
+ method handled(Failure:D:) returns Bool:D
+
+Returns C<True> for handled failures, C<False> otherwise.
+
+=head2 exception
+
+ method handled(Failure:D:) returns Exception
+
+Returns the L<Exception> object that the failure wraps.
+
+=head2 Bool
+
+ multi method Bool(Failure:D:) returns Bool:D
+
+Returns C<False>, and marks the failure as handled.
+
+=head2 defined
+
+ multi method defined(Failure:D:) returns Bool:D
+
+Returns C<False> (failures are officially undefined), and marks
+the failure as handled.
+
+=end pod

0 comments on commit 91e7c16

Please sign in to comment.