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

NAME

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

SYNOPSIS

use PersonName::Format;

# Exceptions are created automatically by the error() method in various modules

# Exception object propagates through method chains
# When a method fails, it returns a PersonName::Format::NullObject in chaining
# (object) context so the chain does not die with "Can't call method on undef":

# pass_error: forwarding an existing exception
sub my_helper
{
    my $self = shift( @_ );
    my $fmt = PersonName::Format->new( $faulty_args ) ||
        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: turn warnings into exceptions
my $fmt2 = PersonName::Format->new( $some_args );
$fmt2->fatal(1);  # any subsequent error will die() instead of warn()

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.

file

Returns the source file associated with the exception.

line

Returns the line number associated with the exception.

message

Returns the error message string.

package

Returns the package name associated with the exception.

throw( %args | $message )

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

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.