/ 
results-0.006
River stage zero No dependents
/ results::exceptions

NAME

results::exceptions - quickly create a bunch of exception classes

SYNOPSIS

use results;
use results::exceptions (
  'DatabaseConnection',
  'Unauthorized' => { has => [ 'username' ] },
  'BadSqlSyntax' => { has => [ 'query' ] },
);

...;

return err( Unauthorized->new( username => $user ) );

# or just:

return Unauthorized->err( username => $user );

# or if you prefer traditional exceptions:

return Unauthorized->throw( username => $user );

DESCRIPTION

This is a module to quickly manufacture a bunch of classes to use as exceptions/errors. There are many like it, but this one integrates nicely with results.

Each kind of exception you import is named by an "err kind", which is an UpperCamelCase string. This may be followed by a hashref of options.

After you have imported a kind of exception, this module will create a class called "$caller\::Exception::$err_kind" where $caller is your package and $err_kind is the err kind string. It will then create a constant called $err_kind in your namespace, so you don't have to use the full "$caller\::Exception::$err_kind" class name.

Options

Only two options are currently supported:

has

This may be an arrayref of attributes the exceptions should have. Think of Moose's has keyword, but much, much more limited.

If omitted, the exceptions will have no attributes, which is often fine.

to_string

This may be either a string which the object should stringify to, or a coderef which should be called to stringify the object.

If omitted, the exceptions will stringify to their err kind.

Class Methods

Exception classes provide the following class methods:

MyErrKind->new( %params )

Create a new exception object, but don't do anything with it.

MyErrKind->err( %params )

Create a new exception object, and wrap it in an err Result. You'd normally then return that Result to your caller. For example:

return MyErrKind->err();

MyErrKind->throw( %params )

Create a new exception object, and then die.

Object Methods

Exception objects provide these methods, plus read-only accessors for their attributes.

$exception->err_kind

Returns the err kind as a string.

$exception->to_string

Stringifies the exception. Exception objects also support string overloading.

Lexical exports

results::exceptions supports lexical exports:

use results::exceptions -lexical, (
  'DatabaseConnection',
  'Unauthorized' => { has => [ 'username' ] },
  'BadSqlSyntax' => { has => [ 'query' ] },
);

This feature requires Perl 5.37.2 or above, or Lexical::Sub on older versions of Perl.

BUGS

Please report any bugs to https://github.com/tobyink/p5-results/issues.

SEE ALSO

result, match() in Result::Trait.

AUTHOR

Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE

This software is copyright (c) 2022 by Toby Inkster.

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

DISCLAIMER OF WARRANTIES

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.