NAME

Data::Object::Try

ABSTRACT

Data-Object Try/Catch Class

SYNOPSIS

  use Data::Object::Try;

  my $try = Data::Object::Try->new;

  $try->call(fun (@args) {
    # try something

    return something
  });

  $try->catch($type, fun ($caught) {
    # caught an exception

    return $something;
  });

  $try->default(fun ($caught) {
    # catch the uncaught

    return $something;
  });

  $try->finally(fun (@args) {
    # always run after try/catch
  });

  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)

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

arguments

  arguments(ArrayRef)

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

on_try

  on_try(CodeRef)

The attribute is read-only, accepts (CodeRef) values, and is optional.

on_catch

  on_catch(ArrayRef[CodeRef])

The attribute is read-only, accepts (ArrayRef[CodeRef]) values, and is optional.

on_default

  on_default(CodeRef)

The attribute is read-only, accepts (CodeRef) values, and is optional.

on_finally

  on_finally(CodeRef)

The attribute is read-only, accepts (CodeRef) values, and is optional.

METHODS

This package implements the following methods.

call

  call(Str | CodeRef $method) : Object

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 example

  $try = $try->call($method);
  $try = $try->call(fun (@args) {
    # do something
  });

callback

  callback(Str | CodeRef) : 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.

callback example

  my $callback;

  $callback = $try->callback($method);
  $callback = $try->callback(fun (@args) {
    # do something
  });

catch

  catch(Str $isa, Str | CodeRef $callback) : Any

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.

catch example

  $try = $try->catch('Error::HTTP400', fun ($caught) {
    # do something
  });

  $try = $try->catch('Error::HTTP401', fun ($caught) {
    # do something
  });

default

  default(Str | CodeRef $callback) : Object

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

default example

  $try = $try->default(fun ($caught) {
    # do something
  });

execute

  execute(CodeRef $callback, 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.

execute example

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

finally

  finally(Str | CodeRef $callback) : Object

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 example

  $try = $try->finally(fun (@args) {
    # always do something
  });

no_catch

  no_catch() : Object

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

no_catch example

  $try = $try->no_catch;

no_default

  no_default() : Object

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

no_default example

  $try = $try->no_default;

no_finally

  no_finally() : Object

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

no_finally example

  $try = $try->no_finally;

no_try

  no_try() : Object

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

no_try example

  $try = $try->no_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.

result example

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

CREDITS

Al Newkirk, +296

Anthony Brummett, +10

José Joaquín Atria, +1

AUTHOR

Al Newkirk, awncorp@cpan.org

LICENSE

Copyright (C) 2011-2019, Al Newkirk, et al.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

PROJECT

GitHub

Projects

Milestones

Contributing

Issues

SEE ALSO

To get the most out of this distribution, consider reading the following:

Do

Data::Object

Data::Object::Class

Data::Object::ClassHas

Data::Object::Role

Data::Object::RoleHas

Data::Object::Library

cpanm Do

perl -MCPAN -e shell
install Do