/ 
Unexpected-1.0.1
River stage two • 10 direct dependents • 11 total dependents
/ Unexpected::TraitFor::ExceptionClasses

Name

Unexpected::TraitFor::ExceptionClasses - Define an exception class hierarchy

Synopsis

package YourExceptionClass;

use Moo;

extends 'Unexpected';
with    'Unexpected::ExceptionClasses';

__PACKAGE__->add_exception( 'A' );
__PACKAGE__->add_exception( 'B', { parents => 'A' } );
__PACKAGE__->add_exception( 'C', 'A' ); # same but shorter
__PACKAGE__->add_exception( 'D', [ 'B', 'C' ] ); # diamond pattern

# Then elsewhere
__PACKAGE__->throw( 'error message', { class => 'C' } );

# Elsewhere still
my $e = __PACKAGE__->caught;

$e->class eq 'C'; # true
$e->instance_of( 'A' ); # true
$e->instance_of( 'B' ); # false
$e->instance_of( 'C' ); # true
$e->instance_of( 'D' ); # false

Description

Allows for the creation of an exception class hierarchy. Exception classes inherit from one or more existing classes, ultimately all classes inherit from the Unexpected exception class

Configuration and Environment

Defines the following attributes;

class

Defaults to Unexpected. Can be used to differentiate different classes of error. Non default values for this attribute must have been defined with a call to "add_exception" otherwise an exception will be thrown. Oh the irony

Defines the Unspecified exception class with a default error message. Once the exception class is defined the the following;

use Unexpected::Functions qw( Unspecified );

will import a subroutine that when called returns it's own name. This is a suitable value for the class attribute

YourExceptionClass->throw( class => Unspecified, args => [ 'param name' ] );

Subroutines/Methods

BUILDARGS

Applies the default error message if one exists and the attributes for the soon to be constructed exception lacks one

add_exception

YourExceptionClass->add_exception( 'new_classname', [ 'parent1', 'parent2']);

Defines a new exception class. Parent classes must already exist. Default parent class is Unexpected;

$class->add_exception( 'new_classname' => {
   parents => [ 'parent1' ], error => 'Default error message [_1]' } );

Sets the default error message for the exception class

When defining your own exception class import and call has_exception which will call this class method. The functions subroutine signature is like that of has in Moo

instance_of

$bool = $exception_obj->instance_of( 'exception_classname' );

Is the exception object an instance of the exception class. Can also pass a code reference like the exported exception class functions

is_exception

$bool = YourExceptionClass->is_exception( 'exception_classname' );

Returns true if the exception class exists as a result of a call to "add_exception"

Diagnostics

None

Dependencies

Moo::Role

Incompatibilities

There are no known incompatibilities in this module

Bugs and Limitations

There are no known bugs in this module. Please report problems to http://rt.cpan.org/NoAuth/Bugs.html?Dist=Unexpected. Patches are welcome

Acknowledgements

Larry Wall - For the Perl programming language

Author

Peter Flanigan, <pjfl@cpan.org>

License and Copyright

Copyright (c) 2017 Peter Flanigan. All rights reserved

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic

This program is distributed in the hope that it will be useful, but WITHOUT WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE