NAME

Venus::Try - Try Class

ABSTRACT

Try Class for Perl 5

SYNOPSIS


            
              
              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);

DESCRIPTION

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

ATTRIBUTES

This package has the following attributes:

invocant


            
              
              invocant(Object)

This attribute is read-only, accepts (Object) values, and is optional.

arguments


            
              
              arguments(ArrayRef)

This attribute is read-only, accepts (ArrayRef) values, and is optional.

on_try


            
              
              on_try(CodeRef)

This attribute is read-write, accepts (CodeRef) values, and is optional.

on_catch


            
              
              on_catch(ArrayRef[CodeRef])

This attribute is read-write, accepts (ArrayRef[CodeRef]) values, is optional, and defaults to [].

on_default


            
              
              on_default(CodeRef)

This attribute is read-write, accepts (CodeRef) values, and is optional.

on_finally


            
              
              on_finally(CodeRef)

This attribute is read-write, accepts (CodeRef) values, and is optional.

INHERITS

This package inherits behaviors from:

Venus::Kind::Utility

METHODS

This package provides the following methods:

any


            
              
              any() (Venus::Try)

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

Since 2.32

any example 1


            
              
              package main;
use Venus::Try;
my $try = Venus::Try->new;
$try->call(sub {
  die 'Oops!';
});
my $any = $try->any;
# bless({ on_catch => ... }, "Venus::Try")

any example 2


            
              
              package main;
use Venus::Try;
my $try = Venus::Try->new;
$try->call(sub {
  die $try;
});
my $any = $try->any;
# bless({ on_catch => ... }, "Venus::Try")

call


            
              
              call(string | coderef $method) (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.

Since 0.01

call example 1


            
              
              package main;
use Venus::Try;
my $try = Venus::Try->new;
my $call = $try->call(sub {
  my (@args) = @_;
  return [@args];
});
# bless({ on_catch => ... }, "Venus::Try")

callback


            
              
              callback(string | coderef $method) (coderef)

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.

Since 0.01

callback example 1


            
              
              package main;
use Venus::Try;
my $try = Venus::Try->new;
my $callback = $try->callback(sub {
  my (@args) = @_;
  return [@args];
});
# sub { ... }

callback example 2


            
              
              package Example1;
sub new {
  bless {};
}
sub test {
  my (@args) = @_;
  return [@args];
}
package main;
use Venus::Try;
my $try = Venus::Try->new(
  invocant => Example1->new,
);
my $callback = $try->callback('test');
# sub { ... }

callback example 3


            
              
              package main;
use Venus::Try;
my $try = Venus::Try->new;
my $callback = $try->callback('missing_method');
# Exception! (isa Venus::Try::Error) (see error_on_callback)

catch


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

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.

Since 0.01

catch example 1


            
              
              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")

catch example 2


            
              
              package main;
use Venus::Try;
my $try = Venus::Try->new;
$try->call(sub {
  my (@args) = @_;
  $try->throw->error;
});
my $catch = $try->catch('Venus::Try::Error', sub {
  return (@_);
});
# bless({ on_catch => ... }, "Venus::Try")

catch example 3


            
              
              package main;
use Venus::Try;
my $try = Venus::Try->new;
$try->call(sub {
  $try->throw->error;
});
my $catch = $try->catch('Venus::Try::Error');
# bless({ on_catch => ... }, "Venus::Try")

default


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

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

Since 0.01

default example 1


            
              
              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")

error


            
              
              error(Ref $variable) (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.

Since 0.01

error example 1


            
              
              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")

error example 2


            
              
              package main;
use Venus::Try;
my $try = Venus::Try->new;
$try->call(sub {
  my (@args) = @_;
  $try->throw->error;
});
my $error = $try->error;
# bless({ on_catch => ... }, "Venus::Try")

execute


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

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.

Since 0.01

execute example 1


            
              
              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]

finally


            
              
              finally(string | coderef $method) (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.

Since 0.01

finally example 1


            
              
              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")

maybe


            
              
              maybe() (Venus::Try)

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

Since 0.01

maybe example 1


            
              
              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")

no_catch


            
              
              no_catch() (Venus::Try)

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

Since 0.01

no_catch example 1


            
              
              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")

no_default


            
              
              no_default() (Venus::Try)

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

Since 0.01

no_default example 1


            
              
              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")

no_finally


            
              
              no_finally() (Venus::Try)

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

Since 0.01

no_finally example 1


            
              
              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")

no_try


            
              
              no_try() (Venus::Try)

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

Since 0.01

no_try example 1


            
              
              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")

result


            
              
              result(any @args) (any)

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.

Since 0.01

result example 1


            
              
              package main;
use Venus::Try;
my $try = Venus::Try->new;
$try->call(sub {
  my (@args) = @_;
  return [@args];
});
my $result = $try->result;
# []

result example 2


            
              
              package main;
use Venus::Try;
my $try = Venus::Try->new;
$try->call(sub {
  my (@args) = @_;
  return [@args];
});
my $result = $try->result(1..5);
# [1..5]

result example 3


            
              
              package main;
use Venus::Try;
my $try = Venus::Try->new;
$try->call(sub {die});
my $result = $try->result;
# Exception! Venus::Error

ERRORS

This package may raise the following errors:

error: error_on_callback

This package may raise an error_on_callback exception.

example 1


            
              
              # given: synopsis;
my $input = {
  invocant => 'Example',
  callback => 'execute',
};
my $error = $try->throw('error_on_callback', $input)->catch('error');
# my $name = $error->name;
# "on_callback"
# my $message = $error->render;
# "Can't locate object method \"execute\" on package \"Example\""

AUTHORS

Awncorp, awncorp@cpan.org

LICENSE

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

To install Venus, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Venus

CPAN shell

perl -MCPAN -e shell
install Venus

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

ABSTRACT

SYNOPSIS

DESCRIPTION

ATTRIBUTES

invocant

arguments

on_try

on_catch

on_default

on_finally

INHERITS

METHODS

any

call

callback

catch

default

error

execute

finally

maybe

no_catch

no_default

no_finally

no_try

result

ERRORS

AUTHORS

LICENSE

Module Install Instructions