/ 
PersonName-Format-v0.1.1
/ PersonName::Format::Exception

NAME

PersonName::Format::Exception - Exception object for PersonName::Format

SYNOPSIS

use PersonName::Format;

# Exceptions are created automatically by the error() method.

# When a method fails, it sets an exception and returns undef.
# In method-chaining context, it returns a NullObject so the chain
# does not die with "Can't call method on undef":
my $result = PersonName::Format->new( 'ja-JP' )->format(
    given   => 'Albert',
    surname => 'Einstein',
) || die( PersonName::Format->error );

# pass_error: forwarding an existing exception from a helper method
sub my_helper
{
    my $self = shift( @_ );
    my $fmt = PersonName::Format->new( 'en-US' ) ||
        return( $self->pass_error );  # re-raise PersonName::Format's error
    return( $fmt );
}

my $obj = My::Class->new->my_helper ||
    die( My::Class->error );

# Fatal mode: subsequent errors call die() instead of returning undef
my $fmt = PersonName::Format->new( 'en-US' );
$fmt->fatal(1);

VERSION

v0.1.0

DESCRIPTION

PersonName::Format::Exception is a lightweight exception class used internally by PersonName::Format. It is created automatically by the error() method and stored both on the object and in a package-level $ERROR variable.

PersonName::Format never calls die directly (except via throw()). Instead, error conditions set the exception and return undef in scalar context, or an empty list in list context.

CONSTRUCTOR

new( %args | $message )

Constructor. Accepts either a plain string message or a hash with the following keys:

message

The human-readable error message.

file

Source file where the error originated (auto-populated if omitted).

line

Line number (auto-populated if omitted).

package

Package name (auto-populated if omitted).

skip_frames

Number of additional call-stack frames to skip when auto-detecting location.

Default: 0.

METHODS

as_string

Returns the stringified form of the exception, including file and line information. This method is also invoked by the "" overload.

clone

Returns a cloned version of the current instance.

code

Sets or gets the exception code.

file

Sets or gets the source file associated with the exception.

line

Sets or gets the line number associated with the exception.

message

Sets or gets the error message string.

package

Sets or gets the package name associated with the exception.

rethrow

Triggers a die using the current instance.

retry_after

Sets or gets the exception property retry_after.

throw( %args | $message )

Creates a new exception object and immediately calls die() with it.

type

Sets or gets the exception property type.

SEE ALSO

PersonName::Format

AUTHOR

Jacques Deguest <jack@deguest.jp>

COPYRIGHT & LICENSE

Copyright(c) 2026 DEGUEST Pte. Ltd.

All rights reserved.

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