NAME

Venus::Error - Error Class

ABSTRACT

Error Class for Perl 5

SYNOPSIS

  package main;
  use Venus::Error;
  my $error = Venus::Error->new;
  # $error->throw;

DESCRIPTION

This package represents a context-aware error (exception object). The default for error verbosity can be controlled via the "VENUS_ERROR_VERBOSE" environment variable, e.g. a setting of 0 disables stack traces. The default trace-offset can be controlled via the "VENUS_ERROR_TRACE_OFFSET" environment variable, e.g. a setting of 0 indicates no offset.

ATTRIBUTES

This package has the following attributes:

name

  name(Str)

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

context

  context(Str)

This attribute is read-write, accepts "(Str)" values, is optional, and defaults to '(None)'.

message

  message(Str)

This attribute is read-write, accepts "(Str)" values, is optional, and defaults to 'Exception!'.

verbose

  verbose(Int)

This attribute is read-write, accepts "(Int)" values, is optional, and defaults to 1.

INHERITS

This package inherits behaviors from:

Venus::Kind::Utility

INTEGRATES

This package integrates behaviors from:

Venus::Role::Explainable

Venus::Role::Stashable

METHODS

This package provides the following methods:

arguments

  arguments(number $index) (any)

The arguments method returns the stashed arguments under "captured", or a specific argument if an index is provided.

Since 2.55

arguments example 1

  # given: synopsis
  my $arguments = $error->arguments;
  # undef

arguments example 2

  package main;
  use Venus::Throw;
  my $error = Venus::Throw->new->capture(1..4)->catch('error');
  my $arguments = $error->arguments;
  # [1..4]

arguments example 3

  package main;
  use Venus::Throw;
  my $error = Venus::Throw->new->capture(1..4)->catch('error');
  my $arguments = $error->arguments(0);
  # 1

as

  as(string $name) (Venus::Error)

The as method returns an error object using the return value(s) of the "as" method specified, which should be defined as "as_${name}", which will be called automatically by this method. If no "as_${name}" method exists, this method will set the "name" attribute to the value provided.

Since 1.02

as example 1

  package System::Error;
  use Venus::Class;
  base 'Venus::Error';
  sub as_auth_error {
    my ($self) = @_;
    return $self->do('message', 'auth_error');
  }
  sub as_role_error {
    my ($self) = @_;
    return $self->do('message', 'role_error');
  }
  sub is_auth_error {
    my ($self) = @_;
    return $self->message eq 'auth_error';
  }
  sub is_role_error {
    my ($self) = @_;
    return $self->message eq 'role_error';
  }
  package main;
  my $error = System::Error->new->as('auth_error');
  $error->throw;
  # Exception! (isa Venus::Error)

as example 2

  package System::Error;
  use Venus::Class;
  base 'Venus::Error';
  sub as_auth_error {
    my ($self) = @_;
    return $self->do('message', 'auth_error');
  }
  sub as_role_error {
    my ($self) = @_;
    return $self->do('message', 'role_error');
  }
  sub is_auth_error {
    my ($self) = @_;
    return $self->message eq 'auth_error';
  }
  sub is_role_error {
    my ($self) = @_;
    return $self->message eq 'role_error';
  }
  package main;
  my $error = System::Error->new->as('role_error');
  $error->throw;
  # Exception! (isa Venus::Error)

as example 3

  package Virtual::Error;
  use Venus::Class;
  base 'Venus::Error';
  package main;
  my $error = Virtual::Error->new->as('on_save_error');
  $error->throw;
  # name is "on_save_error"
  # Exception! (isa Venus::Error)

as example 4

  package Virtual::Error;
  use Venus::Class;
  base 'Venus::Error';
  package main;
  my $error = Virtual::Error->new->as('on.SAVE.error');
  $error->throw;
  # name is "on_save_error"
  # Exception! (isa Venus::Error)

callframe

  callframe(number $index) (any)

The callframe method returns the stashed callframe under "captured", or a specific argument if an index is provided.

Since 2.55

callframe example 1

  # given: synopsis
  my $callframe = $error->callframe;
  # undef

callframe example 2

  package main;
  use Venus::Throw;
  my $error = Venus::Throw->new->do('frame', 0)->capture->catch('error');
  my $callframe = $error->callframe;
  # [...]

callframe example 3

  package main;
  use Venus::Throw;
  my $error = Venus::Throw->new->do('frame', 0)->capture->catch('error');
  my $package = $error->callframe(0);
  # 'main'

captured

  captured() (hashref)

The captured method returns the value stashed as "captured".

Since 2.55

captured example 1

  # given: synopsis
  my $captured = $error->captured;
  # undef

explain

  explain() (string)

The explain method returns the error message and is used in stringification operations.

Since 0.01

explain example 1

  # given: synopsis;
  my $explain = $error->explain;
  # "Exception! in ...

frame

  frame(number $index) (hashref)

The frame method returns the data from "caller" on the frames captured, and returns a hashref where the keys map to the keys described by "caller" in perlfunc.

Since 1.11

frame example 1

  # given: synopsis;
  my $frame = $error->frame;
  # {
  #   'bitmask' => '...',
  #   'evaltext' => '...',
  #   'filename' => '...',
  #   'hasargs' => '...',
  #   'hinthash' => '...',
  #   'hints' => '...',
  #   'is_require' => '...',
  #   'line' => '...',
  #   'package' => '...',
  #   'subroutine' => '...',
  #   'wantarray' => '...',
  # }

frame example 2

  # given: synopsis;
  my $frame = $error->frame(1);
  # {
  #   'bitmask' => '...',
  #   'evaltext' => '...',
  #   'filename' => '...',
  #   'hasargs' => '...',
  #   'hinthash' => '...',
  #   'hints' => '...',
  #   'is_require' => '...',
  #   'line' => '...',
  #   'package' => '...',
  #   'subroutine' => '...',
  #   'wantarray' => '...',
  # }

frames

  frames() (arrayref)

The frames method returns the compiled and stashed stack trace data.

Since 0.01

frames example 1

  # given: synopsis;
  my $frames = $error->frames;
  # [
  #   ...
  #   [
  #     "main",
  #     "t/Venus_Error.t",
  #     ...
  #   ],
  # ]

is

  is(string $name) (boolean)

The is method returns truthy or falsy based on the return value(s) of the "is" method specified, which should be defined as "is_${name}", which will be called automatically by this method. If no "is_${name}" method exists, this method will check if the "name" attribute is equal to the value provided.

Since 1.02

is example 1

  package System::Error;
  use Venus::Class;
  base 'Venus::Error';
  sub as_auth_error {
    my ($self) = @_;
    return $self->do('message', 'auth_error');
  }
  sub as_role_error {
    my ($self) = @_;
    return $self->do('message', 'role_error');
  }
  sub is_auth_error {
    my ($self) = @_;
    return $self->message eq 'auth_error';
  }
  sub is_role_error {
    my ($self) = @_;
    return $self->message eq 'role_error';
  }
  package main;
  my $is = System::Error->new->as('auth_error')->is('auth_error');
  # 1

is example 2

  package System::Error;
  use Venus::Class;
  base 'Venus::Error';
  sub as_auth_error {
    my ($self) = @_;
    return $self->do('message', 'auth_error');
  }
  sub as_role_error {
    my ($self) = @_;
    return $self->do('message', 'role_error');
  }
  sub is_auth_error {
    my ($self) = @_;
    return $self->message eq 'auth_error';
  }
  sub is_role_error {
    my ($self) = @_;
    return $self->message eq 'role_error';
  }
  package main;
  my $is = System::Error->as('auth_error')->is('auth_error');
  # 1

is example 3

  package System::Error;
  use Venus::Class;
  base 'Venus::Error';
  sub as_auth_error {
    my ($self) = @_;
    return $self->do('message', 'auth_error');
  }
  sub as_role_error {
    my ($self) = @_;
    return $self->do('message', 'role_error');
  }
  sub is_auth_error {
    my ($self) = @_;
    return $self->message eq 'auth_error';
  }
  sub is_role_error {
    my ($self) = @_;
    return $self->message eq 'role_error';
  }
  package main;
  my $is = System::Error->as('auth_error')->is('role_error');
  # 0

is example 4

  package Virtual::Error;
  use Venus::Class;
  base 'Venus::Error';
  package main;
  my $is = Virtual::Error->new->as('on_save_error')->is('on_save_error');
  # 1

is example 5

  package Virtual::Error;
  use Venus::Class;
  base 'Venus::Error';
  package main;
  my $is = Virtual::Error->new->as('on.SAVE.error')->is('on_save_error');
  # 1

of

  of(string $name) (boolean)

The of method returns truthy or falsy based on the return value(s) of the "of" method specified, which should be defined as "of_${name}", which will be called automatically by this method. If no "of_${name}" method exists, this method will check if the "name" attribute contains the value provided.

Since 1.11

of example 1

  package System::Error;
  use Venus::Class;
  base 'Venus::Error';
  sub as_auth_error {
    my ($self) = @_;
    return $self->do('name', 'auth_error');
  }
  sub as_role_error {
    my ($self) = @_;
    return $self->do('name', 'role_error');
  }
  sub is_auth_error {
    my ($self) = @_;
    return $self->name eq 'auth_error';
  }
  sub is_role_error {
    my ($self) = @_;
    return $self->name eq 'role_error';
  }
  package main;
  my $of = System::Error->as('auth_error')->of('role');
  # 0

of example 2

  package System::Error;
  use Venus::Class;
  base 'Venus::Error';
  sub as_auth_error {
    my ($self) = @_;
    return $self->do('name', 'auth_error');
  }
  sub as_role_error {
    my ($self) = @_;
    return $self->do('name', 'role_error');
  }
  sub is_auth_error {
    my ($self) = @_;
    return $self->name eq 'auth_error';
  }
  sub is_role_error {
    my ($self) = @_;
    return $self->name eq 'role_error';
  }
  package main;
  my $of = System::Error->as('auth_error')->of('auth');
  # 1

of example 3

  package System::Error;
  use Venus::Class;
  base 'Venus::Error';
  sub as_auth_error {
    my ($self) = @_;
    return $self->do('name', 'auth_error');
  }
  sub as_role_error {
    my ($self) = @_;
    return $self->do('name', 'role_error');
  }
  sub is_auth_error {
    my ($self) = @_;
    return $self->name eq 'auth_error';
  }
  sub is_role_error {
    my ($self) = @_;
    return $self->name eq 'role_error';
  }
  package main;
  my $of = System::Error->as('auth_error')->of('role_error');
  # 0

of example 4

  package Virtual::Error;
  use Venus::Class;
  base 'Venus::Error';
  package main;
  my $of = Virtual::Error->new->as('on_save_error')->of('on.save');
  # 1

of example 5

  package Virtual::Error;
  use Venus::Class;
  base 'Venus::Error';
  package main;
  my $of = Virtual::Error->new->as('on.SAVE.error')->of('on.save');
  # 1

render

  render() (string)

The render method replaces tokens in the message with values from the stash and returns the formatted string. The token style and formatting operation is equivalent to the "render" in Venus::String operation.

Since 3.30

render example 1

  # given: synopsis
  package main;
  $error->message('Signal received: {{signal}}');
  $error->stash(signal => 'SIGKILL');
  my $render = $error->render;
  # "Signal received: SIGKILL"

throw

  throw(any @data) (Venus::Error)

The throw method throws an error if the invocant is an object, or creates an error object using the arguments provided and throws the created object.

Since 0.01

throw example 1

  # given: synopsis;
  my $throw = $error->throw;
  # bless({ ... }, 'Venus::Error')

trace

  trace(number $offset, number $limit) (Venus::Error)

The trace method compiles a stack trace and returns the object. By default it skips the first frame.

Since 0.01

trace example 1

  # given: synopsis;
  my $trace = $error->trace;
  # bless({ ... }, 'Venus::Error')

trace example 2

  # given: synopsis;
  my $trace = $error->trace(0, 1);
  # bless({ ... }, 'Venus::Error')

trace example 3

  # given: synopsis;
  my $trace = $error->trace(0, 2);
  # bless({ ... }, 'Venus::Error')

OPERATORS

This package overloads the following operators:

operation: "("")"

This package overloads the "" operator.

example 1

  # given: synopsis;
  my $result = "$error";
  # "Exception!"

operation: "(eq)"

This package overloads the "eq" operator.

example 1

  # given: synopsis;
  my $result = $error eq 'Exception!';
  # 1

operation: "(ne)"

This package overloads the "ne" operator.

example 1

  # given: synopsis;
  my $result = $error ne 'exception!';
  # 1

operation: "(qr)"

This package overloads the "qr" operator.

example 1

  # given: synopsis;
  my $test = 'Exception!' =~ qr/$error/;
  # 1

operation: "(~~)"

This package overloads the "~~" operator.

example 1

  # given: synopsis;
  my $result = $error ~~ 'Exception!';
  # 1

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.