results::exceptions - quickly create a bunch of exception classes
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 );
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.
"$caller\::Exception::$err_kind"
$caller
$err_kind
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.
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.
die
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.
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.
Please report any bugs to https://github.com/tobyink/p5-results/issues.
result, match() in Result::Trait.
match()
Toby Inkster <tobyink@cpan.org>.
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.
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.
To install results, copy and paste the appropriate command in to your terminal.
cpanm
cpanm results
CPAN shell
perl -MCPAN -e shell install results
For more information on module installation, please visit the detailed CPAN module installation guide.