The Perl Advent Calendar needs more articles for 2022. Submit your idea today!

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

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:

as

  as(Str $name) (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)

explain

  explain() (Str)

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(Int $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(Str $name) (Bool)

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(Str $name) (Bool)

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

throw

  throw(Any @data) (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(Int $offset, Int $limit) (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: (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!"
operation: (~~)

This package overloads the ~~ operator.

example 1

  # given: synopsis;

  my $result = $error ~~ 'Exception!';

  # 1