NAME
Throwable::SugarFactory - build a library of syntax-sugared Throwable-based exceptions
VERSION
version 0.152091
SYNOPSIS
Declare exception classes in a library that will export sugar.
package My::SugarLib;
use Throwable::SugarFactory;
exception PlainError => "a generic error without metadata";
exception DataError => "data description" =>
has => [ flub => ( is => 'ro' ) ];Use exception library to export sugar for exception object construction and class checking.
package My::Code;
use My::SugarLib;
use Try::Tiny;
try {
die plain_error;
}
catch {
die if !$_->isa( PlainError );
};
try {
die data_error flub => 'blarb';
}
catch {
die if !$_->isa( DataError );
die if $_->flub ne 'blarb';
};DESCRIPTION
This is an effort to create an exception library that is useful and pleases my aesthetics. The explicit goals were:
1. Declare exception classes at runtime to remove the need for multiple files.
2. Retain the use of the perl builtin die to throw the exception, to minimize the difference from common standard Perl code and thus increase reading speed.
3. Gain ability to construct the exception class with a short function call, to increase reading speed by removing the need to: Use the full class name; mention the constructor name at all; use cumbersome method call syntax and forced parens.
4. Gain ability to perform ISA checks with a short function call, also to increase reading speed by removing the need to use the full class name.
To build an exception library with this module, simply use the module in your package, which sets it up as a library to export the constructor and class name shortcuts you will be declaring with the exported keyword exception.
To use the exceptions in your code, use your exception library in the module where you wish to throw exceptions, whereupon it will export the shortcuts. You can then create the exception with the snake_cased constructor function and call die to throw it, and when its caught, can call ->isa with the CamelCased shortcut that returns the class name.
DECLARATION
To declare an exception in your library, you call exception with 3 arguments:
- A sugar spec, this is used by Constructor::Sugar to create the shortcuts. These will be two functions: One that creates a new exception object by passing its argument to the object's constructor, with its name generated by converting the error id to snake_case. And one function that will return the error's full class name with its name being exactly the error id given.
- An error description which will be found in the attribute description of every exception created with that id.
- A list of instructions, which will be used by MooX::BuildClass to construct the exception class. The exception's full class name will be the package name exception is called in, appended with :: and the id given in the spec. Note that the full range of Moo functions is available to declare your exception class, including the ability to compose roles into them, so this should provide a lot of freedom and even give the ability to modify the syntax of the constructor arguments somewhat.
Note: You CAN include :: in the spec, but the results may not be what you expect, and they may change in the future. As of now this is bat country. Consider yourself warned. Talk to me in #web-simple if you have ideas on this.
IMPORTING EXCEPTIONS
Your exception library will be a basic Exporter package, which operated like those usually do. A bare use will export all shortcuts for all exceptions in the library. When explicit shortcut names are used as parameters in the use, then only those will be exported.
Additionally there are a few tags you can use. :ctors will export only the constructor shortcuts, :ids will export only the class name shortcuts, and :$exception will export the constructor and class name shortcuts for that exception id only.
THROWING EXCEPTIONS
To throw your exceptions, you use the snake_cased constructor shortcut to create the exception object, giving the normal type of object constructor arguments; followed by calling die to actually throw the exception.
Note that right now the constructor function may actually die with the exception immediately, but that state is only temporary and will be changed in the near future. Calling die (or your favourite error function) is mandatory.
EXCEPTION METHODS
The exception objects constructed by this library come with a few methods implemented by default. These are as follows:
Throwable
The role Throwable is composed into each class, providing all methods provided by that role.
error
The error id you used to declare the exception class.
namespace
The package name this exception class was declared in.
description
The description string used to declare the exception class.
to_hash
Returns a hash reference containing the data of the exception. Useful for conversion to JSON.
SEE ALSO
Throwable, Throwable::Factory, Exception::Class, Exception::Base, Try::Tiny, Try::Tiny::ByClass
SUPPORT
Bugs / Feature Requests
Please report any bugs or feature requests through the issue tracker at http://rt.cpan.org/Public/Dist/Display.html?Name=Throwable-SugarFactory. You will be notified automatically of any progress on your issue.
Source Code
This is open source software. The code repository is available for public review and contribution under the terms of the license.
https://github.com/wchristian/Throwable-SugarFactory
git clone https://github.com/wchristian/Throwable-SugarFactory.gitAUTHOR
Christian Walde <walde.christian@gmail.com>
COPYRIGHT AND LICENSE
Christian Walde has dedicated the work to the Commons by waiving all of his or her rights to the work worldwide under copyright law and all related or neighboring legal rights he or she had in the work, to the extent allowable by law.
Works under CC0 do not require attribution. When citing the work, you should not imply endorsement by the author.