NAME

    Throwable::SugarFactory - build a library of syntax-sugared
    Throwable-based exceptions

VERSION

    version 0.213360

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
    https://github.com/wchristian/Throwable-SugarFactory/issues. 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.git

AUTHOR

    Christian Walde <walde.christian@gmail.com>

CONTRIBUTOR

    Christian Walde <walde.christian@googlemail.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.

