Venus::Try

Try Class

Try Class for Perl 5

method: any method: call method: callback method: catch method: default method: error method: execute method: fault method: finally method: maybe method: new method: no_catch method: no_default method: no_finally method: no_try method: result

package main;

use Venus::Try;

my $try = Venus::Try->new;

$try->call(sub {
  my (@args) = @_;

  # try something

  return time;
});

$try->catch('Example::Error', sub {
  my ($caught) = @_;

  # caught an error (exception)

  return;
});

$try->default(sub {
  my ($caught) = @_;

  # catch the uncaught

  return;
});

$try->finally(sub {
  my (@args) = @_;

  # always run after try/catch

  return;
});

my @args;

my $result = $try->result(@args);

This package provides an object-oriented interface for performing complex try/catch operations.

Venus::Kind::Utility

invocant: ro, opt, Object arguments: ro, opt, ArrayRef on_try: rw, opt, CodeRef on_catch: rw, opt, ArrayRef[CodeRef], [] on_default: rw, opt, CodeRef on_finally: rw, opt, CodeRef

The any method registers a default catch condition that returns whatever value was encoutered on error and returns it as a result.

any() (Venus::Try)

{ since => '2.32', }

=example-1 any

package main;

use Venus::Try;

my $try = Venus::Try->new;

$try->call(sub {
  die 'Oops!';
});

my $any = $try->any;

# bless({ on_catch => ... }, "Venus::Try")

The call method takes a method name or coderef, registers it as the tryable routine, and returns the object. When invoked, the callback will received an invocant if one was provided to the constructor, the default arguments if any were provided to the constructor, and whatever arguments were provided by the invocant.

call(string | coderef $method) (Venus::Try)

{ since => '0.01', }

=example-1 call

package main;

use Venus::Try;

my $try = Venus::Try->new;

my $call = $try->call(sub {
  my (@args) = @_;

  return [@args];
});

# bless({ on_catch => ... }, "Venus::Try")

The callback method takes a method name or coderef, and returns a coderef for registration. If a coderef is provided this method is mostly a passthrough.

callback(string | coderef $method) (coderef)

{ since => '0.01', }

=example-1 callback

package main;

use Venus::Try;

my $try = Venus::Try->new;

my $callback = $try->callback(sub {
  my (@args) = @_;

  return [@args];
});

# sub { ... }

The catch method takes a package or ref name, and when triggered checks whether the captured exception is of the type specified and if so executes the given callback. If no callback is provided the exception is captured in a "default" operation and returned as a result.

catch(string $isa, string | coderef $method) (Venus::Try)

{ since => '0.01', }

=example-1 catch

package main;

use Venus::Try;

my $try = Venus::Try->new;

$try->call(sub {
  my (@args) = @_;

  die $try;
});

my $catch = $try->catch('Venus::Try', sub {
  my (@args) = @_;

  return [@args];
});

# bless({ on_catch => ... }, "Venus::Try")

The default method takes a method name or coderef and is triggered if no catch conditions match the exception thrown.

default(string | coderef $method) (Venus::Try)

{ since => '0.01', }

=example-1 default

package main;

use Venus::Try;

my $try = Venus::Try->new;

$try->call(sub {
  my (@args) = @_;

  die $try;
});

my $default = $try->default(sub {
  my (@args) = @_;

  return [@args];
});

# bless({ on_catch => ... }, "Venus::Try")

The error method takes a scalar reference and assigns any uncaught exceptions to it during execution. If no variable is provided a "catch" operation will be registered to capture all Venus::Error exceptions.

error(Ref $variable) (Venus::Try)

{ since => '0.01', }

=example-1 error

package main;

use Venus::Try;

my $try = Venus::Try->new;

$try->call(sub {
  my (@args) = @_;

  die $try;
});

my $error = $try->error(\my $object);

# bless({ on_catch => ... }, "Venus::Try")

The execute method takes a coderef and executes it with any given arguments. When invoked, the callback will received an invocant if one was provided to the constructor, the default arguments if any were provided to the constructor, and whatever arguments were passed directly to this method. This method can return a list of values in list-context.

execute(coderef $code, any @args) (any)

{ since => '0.01', }

=example-1 execute

package Example2;

sub new {
  bless {};
}

package main;

use Venus::Try;

my $try = Venus::Try->new(
  invocant => Example2->new,
  arguments => [1,2,3],
);

my $execute = $try->execute(sub {
  my (@args) = @_;

  return [@args];
});

# [bless({}, "Example2"), 1, 2, 3]

The fault method takes a scalar reference and assigns any uncaught exceptions to it during execution. If no variable is provided a "catch" operation will be registered to capture all Venus::Fault exceptions.

fault(Ref $variable) (Venus::Try)

{ since => '4.15', }

=example-1 fault

package main;

use Venus 'fault';

use Venus::Try;

my $try = Venus::Try->new;

$try->call(sub {
  my (@args) = @_;

  fault;
});

my $fault = $try->fault(\my $object);

# bless({ on_catch => ... }, "Venus::Try")

The finally method takes a package or ref name and always executes the callback after a try/catch operation. The return value is ignored. When invoked, the callback will received an invocant if one was provided to the constructor, the default arguments if any were provided to the constructor, and whatever arguments were provided by the invocant.

finally(string | coderef $method) (Venus::Try)

{ since => '0.01', }

=example-1 finally

package Example3;

sub new {
  bless {};
}

package main;

use Venus::Try;

my $try = Venus::Try->new(
  invocant => Example3->new,
  arguments => [1,2,3],
);

$try->call(sub {
  my (@args) = @_;

  return $try;
});

my $finally = $try->finally(sub {
  my (@args) = @_;

  $try->{args} = [@args];
});

# bless({ on_catch => ... }, "Venus::Try")

The maybe method registers a default catch condition that returns falsy, i.e. an undefined value, if an exception is encountered.

maybe() (Venus::Try)

{ since => '0.01', }

=example-1 maybe

package main;

use Venus::Try;

my $try = Venus::Try->new;

$try->call(sub {
  my (@args) = @_;

  die $try;
});

my $maybe = $try->maybe;

# bless({ on_catch => ... }, "Venus::Try")

The new method constructs an instance of the package.

new(any @args) (Venus::Try)

{ since => '4.15', }

The no_catch method removes any configured catch conditions and returns the object.

no_catch() (Venus::Try)

{ since => '0.01', }

=example-1 no_catch

package main;

use Venus::Try;

my $try = Venus::Try->new;

$try->call(sub {
  my (@args) = @_;

  die $try;
});

$try->catch('Venus::Try', sub {
  my (@args) = @_;

  return [@args];
});


my $no_catch = $try->no_catch;

# bless({ on_catch => ... }, "Venus::Try")

The no_default method removes any configured default condition and returns the object.

no_default() (Venus::Try)

{ since => '0.01', }

=example-1 no_default

package main;

use Venus::Try;

my $try = Venus::Try->new;

$try->call(sub {
  my (@args) = @_;

  die $try;
});

my $default = $try->default(sub {
  my (@args) = @_;

  return [@args];
});

my $no_default = $try->no_default;

# bless({ on_catch => ... }, "Venus::Try")

The no_finally method removes any configured finally condition and returns the object.

no_finally() (Venus::Try)

{ since => '0.01', }

=example-1 no_finally

package Example4;

sub new {
  bless {};
}

package main;

use Venus::Try;

my $try = Venus::Try->new(
  invocant => Example4->new,
  arguments => [1,2,3],
);

$try->call(sub {
  my (@args) = @_;

  return $try;
});

$try->finally(sub {
  my (@args) = @_;

  $try->{args} = [@args];
});

my $no_finally = $try->no_finally;

# bless({ on_catch => ... }, "Venus::Try")

The no_try method removes any configured try operation and returns the object.

no_try() (Venus::Try)

{ since => '0.01', }

=example-1 no_try

package main;

use Venus::Try;

my $try = Venus::Try->new;

$try->call(sub {
  my (@args) = @_;

  return [@args];
});

my $no_try = $try->no_try;

# bless({ on_catch => ... }, "Venus::Try")

The result method executes the try/catch/default/finally logic and returns either 1) the return value from the successfully tried operation 2) the return value from the successfully matched catch condition if an exception was thrown 3) the return value from the default catch condition if an exception was thrown and no catch condition matched. When invoked, the try and finally callbacks will received an invocant if one was provided to the constructor, the default arguments if any were provided to the constructor, and whatever arguments were passed directly to this method. This method can return a list of values in list-context.

result(any @args) (any)

{ since => '0.01', }

=example-1 result

package main;

use Venus::Try;

my $try = Venus::Try->new;

$try->call(sub {
  my (@args) = @_;

  return [@args];
});

my $result = $try->result;

# []

package main;

use Venus::Try;

my $try = Venus::Try->new;

$try->call('execute')->result;

# Error! (on.callback)

t/Venus.t: present: authors t/Venus.t: present: license

cpanm Venus

perl -MCPAN -e shell
install Venus