class Failure

Delayed exception

class Failure { }

A Failure is a soft or unthrown exception, usually generated by calling &fail. It acts as a wrapper around an Exception object.

Sink (void) context causes a Failure to throw, i.e. turn into a normal exception.

Checking a Failure for truth (with the Bool method) or definedness (with the defined method) marks the failure as handled, and causes it not to throw in sink context anymore.

You can call the 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 Failure, in Rakudo it causes the failure to throw.

Methods

method new

Defined as:

method new(Failure:D: $payload --> Failure)

Returns a new Failure instance with the given payload. The latter can be either an Exception or a payload for an Exception. A typical payload would be a Str with an error message. A list of payloads is also accepted.

my $e = Failure.new(now.DateTime'WELP‼');
say $e;
CATCH{ default { say .^name''.Str } }
# OUTPUT: «X::AdHoc: 2017-09-10T11:56:05.477237ZWELP‼␤» 

method handled

Defined as:

method handled(Failure:D: --> Bool:D)

Returns True for handled failures, False otherwise.

sub f() { fail }my $v = fsay $v.handled# OUTPUT: «False␤» 

The handled method is an lvalue, which means you can also use it to set the handled state:

sub f() { fail }
my $v = f;
$v.handled = True;
say $v.handled# OUTPUT: «True␤» 

method exception

Defined as:

method exception(Failure:D: --> Exception)

Returns the Exception object that the failure wraps.

sub failer() { fail };
my $failure = failer;
my $ex = $failure.exception;
put "$ex.^name(): $ex";
# OUTPUT: «X::AdHoc: Failed␤» 

method self

Defined as:

method self(Failure:D: --> Failure:D)

If the invocant is a handled Failure, returns it as is. If not handled, throws its Exception. Since Mu type provides .self for every class, calling this method is a handy way to explosively filter out Failures:

my $num1 = ''.Int;
# $num1 now contains a Failure object, which may not be desirable 
 
my $num2 = ''.Int.self;
# .self method call on Failure causes an exception to be thrown 
 
my $num3 = '42'.Int.self;
# Int type has a .self method, so here $num3 has `42` in it 
 
(my $stuff = ''.Int).so;
say $stuff.self# OUTPUT: «(HANDLED) Cannot convert string to number…» 
# Here, Failure is handled, so .self just returns it as is 

method Bool

Defined as:

multi method Bool(Failure:D: --> Bool:D)

Returns False, and marks the failure as handled.

sub f() { fail }my $v = fsay $v.handled$v.Boolsay $v.handled;
# OUTPUT: «False␤ 
# True␤» 

method Capture

Defined as:

method Capture()

Throws X::Cannot::Capture if the invocant is a type object or a handled Failure. Otherwise, throws the invocant's exception.

method defined

Defined as:

multi method defined(Failure:D: --> Bool:D)

Returns False (failures are officially undefined), and marks the failure as handled.

sub f() { fail }my $v = fsay $v.defined# OUTPUT: «False␤» 

Type Graph

Type relations for Failure
perl6-type-graph Failure Failure Any Any Failure->Any Mu Mu Any->Mu

Expand above chart