NAME

Venus::Role::Throwable - Throwable Role

ABSTRACT

Throwable Role for Perl 5

SYNOPSIS

  package Example;
  use Venus::Class;
  with 'Venus::Role::Throwable';
  package main;
  my $example = Example->new;
  # $example->throw;

DESCRIPTION

This package modifies the consuming package and provides a mechanism for throwing context-aware errors (exceptions).

METHODS

This package provides the following methods:

error

  error(hashref $data) (any)

The error method dispatches to the "throw" method, excepts a hashref of options to be provided to the "throw" method, and returns the result unless an exception is raised automatically. If the "throw" option is provided it is excepted to be the name of a method used as a callback to provide arguments to the thrower.

Since 3.40

error example 1

  package main;
  my $example = Example->new;
  my $throw = $example->error;
  # bless({ "package" => "Example::Error", ..., }, "Venus::Throw")
  # $throw->error;

error example 2

  package main;
  my $example = Example->new;
  my $throw = $example->error({package => 'Example::Error::Unknown'});
  # bless({ "package" => "Example::Error::Unknown", ..., }, "Venus::Throw")
  # $throw->error;

error example 3

  package main;
  my $example = Example->new;
  my $throw = $example->error({
    name => 'on.example',
    capture => [$example],
    stash => {
      time => time,
    },
  });
  # bless({ "package" => "Example::Error", ..., }, "Venus::Throw")
  # $throw->error;

error example 4

  # given: synopsis
  package Example;
  # ...
  sub error_on_example {
    my ($self) = @_;
    return {
      name => 'on.example',
      capture => [$example],
      stash => {
        time => time,
      },
    };
  }
  package main;
  my $throw = $example->error({throw => 'error_on_example'});
  # bless({ "package" => "Example::Error", ..., }, "Venus::Throw")
  # $throw->error;

error example 5

  # given: synopsis
  package Example;
  # ...
  sub error_on_example {
    my ($self) = @_;
    return {
      name => 'on.example',
      capture => [$example],
      stash => {
        time => time,
      },
      raise => 1,
    };
  }
  package main;
  my $throw = $example->error({throw => 'error_on_example'});
  # Exception! (isa Example::Error)

throw

  throw(maybe[string | hashref] $data, any @args) (any)

The throw method builds a Venus::Throw object, which can raise errors (exceptions). If passed a string representing a package name, the throw object will be configured to throw an exception using that package name. If passed a string representing a method name, the throw object will call that method expecting a hashref to be returned which will be provided to Venus::Throw as arguments to configure the thrower. If passed a hashref, the keys and values are expected to be method names and arguments which will be called to configure the Venus::Throw object returned. If passed additional arguments, assuming they are preceeded by a string representing a method name, the additional arguments will be supplied to the method when called. If the "raise" argument is provided (or returned from the callback), the thrower will automatically throw the exception.

Since 0.01

throw example 1

  package main;
  my $example = Example->new;
  my $throw = $example->throw;
  # bless({ "package" => "Example::Error", ..., }, "Venus::Throw")
  # $throw->error;

throw example 2

  package main;
  my $example = Example->new;
  my $throw = $example->throw('Example::Error::Unknown');
  # bless({ "package" => "Example::Error::Unknown", ..., }, "Venus::Throw")
  # $throw->error;

throw example 3

  package main;
  my $example = Example->new;
  my $throw = $example->throw({
    name => 'on.example',
    capture => [$example],
    stash => {
      time => time,
    },
  });
  # bless({ "package" => "Example::Error", ..., }, "Venus::Throw")
  # $throw->error;

throw example 4

  # given: synopsis
  package Example;
  # ...
  sub error_on_example {
    my ($self) = @_;
    return {
      name => 'on.example',
      capture => [$example],
      stash => {
        time => time,
      },
    };
  }
  package main;
  my $throw = $example->throw('error_on_example');
  # bless({ "package" => "Example::Error", ..., }, "Venus::Throw")
  # $throw->error;

throw example 5

  # given: synopsis
  package Example;
  # ...
  sub error_on_example {
    my ($self) = @_;
    return {
      name => 'on.example',
      capture => [$example],
      stash => {
        time => time,
      },
      raise => 1,
    };
  }
  package main;
  my $throw = $example->throw('error_on_example');
  # Exception! (isa Example::Error)

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.