—

              
HideShow 182 lines of Pod
=encoding utf8
=head1 NAME
Locale::Unicode::Data::Exception - Locale Unicode Data Exception Class
=head1 SYNOPSIS
    my $ex = Locale::Unicode::Data::Exception->new({
        code => 400,
        type => $error_type,
        file => '/home/joe/some/lib/My/Module.pm',
        line => 120,
        message => 'Invalid property provided',
        package => 'My::Module',
        subroutine => 'customer_info',
    });
or, providing a list of string that will be concatenated:
    my $ex = Locale::Unicode::Data::Exception->new( "Some error", "has occurred:", $details );
=head1 VERSION
    v0.1.0
=head1 DESCRIPTION
This is an exception class for L<Locale::Unicode::Data>
When stringified, it provides the error message along with precise information about where the error occurred.
L<Locale::Unicode::Data::Exception> objects are created by L<Locale::Unicode::Data/"error"> method.
=head1 METHODS
=head2 new
It takes either an L<Locale::Unicode::Data::Exception> object or an hash reference of properties, or a list of arguments that will be concatanated to form the error message. The list of arguments can contain code reference such as reference to sub routines, who will be called and their returned value added to the error message string. For example :
    my $ex = Locale::Unicode::Data::Exception->new( "Invalid property. Value recieved are: ", sub{ Dumper( $hash ) } );
    # or
    my #ex = Locale::Unicode::Data::Exception->new({
        message => "Invalid property.",
        code => 400,
        type => 'customer',
    })
Possible properties that can be specified are:
=over 4
=item * C<code>
An error code
=item * C<file>
The location where the error occurred.
=item * C<line>
The line number in the file where the error occurred.
=item * C<message>
The error message. It can be provided as a list of arguments that will be concatenated, or as the I<message> property in an hash reference, or copied from another exception object passed as the sole argument.
=item * C<package>
The package name where the error occurred.
=item * C<retry_after>
An optional value to indicate in seconds how long to wait to retry.
=item * C<skip_frames>
This is used as a parameter to L<caller|perlfunc/caller> upon instantiation to instruct how many it should skip to start getting key values.
=item * C<type>
An optional error type
=back
It returns the exception object.
=head2 as_string
This returns a string representation of the Exception such as :
    Invalid property within package My::Module at line 120 in file /home/john/lib/My/Module.pm
=head2 code
Set or get the error code. It returns the current value.
=head2 file
Set or get the file path where the error originated. It returns the current value.
=head2 line
Set or get the line where the error originated. It returns the current value.
=head2 message
Set or get the error message. It returns the current value.
It takes a string, or a list of strings which will be concatenated.
For example :
    $ex->messsage( "I found some error:", $some_data );
=head2 package
Set or get the class/package name where the error originated. It returns the current value.
=head2 PROPAGATE
This method is called by perl when you call L<perlfunc/die> with no parameters and C<$@> is set to a L<Locale::Unicode::Data::Exception> object.
This returns a new exception object that perl will use to replace the value in C<$@>
=head2 rethrow
This rethrow (i.e. L<perlfunc/"die">) the original error. It must be called with the exception object or else it will return undef.
This is ok :
    $ex->rethrow;
But this is not :
    Locale::Unicode::Data::Exception->rethrow;
=head2 retry_after
Set or get the number of seconds to way before to retry whatever cause the error. It returns the current value.
=head2 throw
Provided with a message string, this will create a new L<Locale::Unicode::Data::Exception> object and call L<perlfunc/"die"> with it.
=head2 TO_JSON
Special method called by L<JSON> to transform this object into a string suitable to be added in a json data.
=head2 type
Set or get the error type. It returns the current value.
=head1 SERIALISATION
=for Pod::Coverage FREEZE
=for Pod::Coverage STORABLE_freeze
=for Pod::Coverage STORABLE_thaw
=for Pod::Coverage THAW
=for Pod::Coverage TO_JSON
Serialisation by L<CBOR|CBOR::XS>, L<Sereal> and L<Storable::Improved> (or the legacy L<Storable>) is supported by this package. To that effect, the following subroutines are implemented: C<FREEZE>, C<THAW>, C<STORABLE_freeze> and C<STORABLE_thaw>
=head1 AUTHOR
Jacques Deguest E<lt>F<jack@deguest.jp>E<gt>
=head1 COPYRIGHT & LICENSE
Copyright (c) 2024 DEGUEST Pte. Ltd.
You can use, copy, modify and redistribute this package and associated
files under the same terms as Perl itself.
=cut