NAME

Venus::Role::Catchable - Catchable Role

ABSTRACT

Catchable Role for Perl 5

SYNOPSIS

package Example;

use Venus::Class;

use Venus 'error';

with 'Venus::Role::Tryable';
with 'Venus::Role::Catchable';

sub pass {
  true;
}

sub fail {
  error;
}

package main;

my $example = Example->new;

# my $error = $example->catch('fail');

DESCRIPTION

This package modifies the consuming package and provides methods for trapping errors thrown from dispatched method calls.

METHODS

This package provides the following methods:

catch

catch(string $method, any @args) (any)

The catch method traps any errors raised by executing the dispatched method call and returns the error string or error object. This method can return a list of values in list-context. This method supports dispatching, i.e. providing a method name and arguments whose return value will be acted on by this method.

Since 0.01

catch example 1

package main;

my $example = Example->new;

my $catch = $example->catch('fail');

# bless({...}, "Venus::Error")

catch example 2

package main;

my $example = Example->new;

my $catch = $example->catch('pass');

# undef

catch example 3

package main;

my $example = Example->new;

my ($catch, $result) = $example->catch('pass');

# (undef, 1)

catch example 4

package main;

my $example = Example->new;

my ($catch, $result) = $example->catch('fail');

# (bless({...}, "Venus::Error"), undef)

caught

caught(object $error, string | tuple[string, string] $identity, coderef $block) (any)

The caught method evaluates the value provided and validates its identity and name (if provided) then executes the code block (if provided) returning the result of the callback. If no callback is provided this function returns the exception object on success and undef on failure.

Since 4.15

caught example 1

package main;

my $example = Example->new;

my $catch = $example->catch('fail');

my $result = $example->caught($catch);

# bless(..., 'Venus::Error')

caught example 2

package main;

my $example = Example->new;

my $catch = $example->catch('fail');

my $result = $example->caught($catch, 'Venus::Error');

# bless(..., 'Venus::Error')

caught example 3

package main;

my $example = Example->new;

my $catch = $example->catch('fail');

my $result = $example->caught($catch, 'Venus::Error', sub{
  $example->{caught} = $_;
});

($example, $result)

# (bless(..., 'Example'), bless(..., 'Venus::Error'))

caught example 4

package main;

my $example = Example->new;

my $catch = $example->catch('fail');

$catch->name('on.issue');

my $result = $example->caught($catch, ['Venus::Error', 'on.issue']);

# bless(..., 'Venus::Error')

caught example 5

package main;

my $example = Example->new;

my $catch = $example->catch('fail');

$catch->name('on.issue');

my $result = $example->caught($catch, ['Venus::Error', 'on.issue'], sub{
  $example->{caught} = $_;
});

($example, $result)

# (bless(..., 'Example'), bless(..., 'Venus::Error'))

caught example 6

package main;

my $example = Example->new;

my $catch = $example->catch('fail');

my $result = $example->caught($catch, ['Venus::Error', 'on.issue']);

# undef

caught example 7

package main;

my $example = Example->new;

my $catch;

my $result = $example->caught($catch);

# undef

maybe

maybe(string $method, any @args) (any)

The maybe method traps any errors raised by executing the dispatched method call and returns undefined on error, effectively supressing the error. This method can return a list of values in list-context. This method supports dispatching, i.e. providing a method name and arguments whose return value will be acted on by this method.

Since 2.91

maybe example 1

package main;

my $example = Example->new;

my $maybe = $example->maybe('fail');

# undef

maybe example 2

package main;

my $example = Example->new;

my $maybe = $example->maybe('pass');

# true

maybe example 3

package main;

my $example = Example->new;

my (@maybe) = $example->maybe(sub {1..4});

# (1..4)

AUTHORS

Awncorp, awncorp@cpan.org

LICENSE

Copyright (C) 2022, Awncorp, awncorp@cpan.org.

This program is free software, you can redistribute it and/or modify it under the terms of the Apache license version 2.0.

cpanm Venus

perl -MCPAN -e shell
install Venus