NAME

DateTime::Format::Lite::Exception - Exception object for DateTime::Format::Lite

SYNOPSIS

use DateTime::Format::Lite;

# Exceptions are created automatically by the error() method in various modules
my $dt = DateTime::Format::Lite->new( year => 2025, month => 13 );
if( !defined( $dt ) )
{
    my $err = DateTime::Format::Lite->error;  # DateTime::Format::Lite::Exception object

    # Stringify (overloaded): "Invalid month value (13) at Foo.pm line 5."
    warn "$err";


    printf( "Error: %s\n", $err->message );
    printf( "  at %s line %d\n", $err->file, $err->line );

    # Individual fields:
    printf "Message : %s", $err->message;  # "Invalid month value (13)"
    printf "File    : %s", $err->file;     # "Foo.pm"
    printf "Line    : %d", $err->line;     # 5
    printf "Code    : %s", $err->code // 'n/a';  # optional error code
}

# Exception object propagates through method chains
# When a method fails, it returns a NullObject in chaining (object) context
# so the chain does not die with "Can't call method on undef":
my $result = DateTime::Format::Lite->new( %bad_args )->clone->add( days => 1 ) ||
    die( DateTime::Format::Lite->error );

# pass_error: forwarding an existing exception
sub my_helper
{
    my $self = shift( @_ );
    my $tz = DateTime::Format::Lite::TimeZone->new( name => 'Invalid/Zone' ) ||
        return( $self->pass_error );  # re-raise TimeZone's error
    return( $tz );
}

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

# Fatal mode: turn warnings into exceptions
my $dt2 = DateTime::Format::Lite->new( year => 2026 );
$dt2->fatal(1);  # any subsequent error will die() instead of warn()

VERSION

v0.1.0

DESCRIPTION

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

Unlike DateTime, DateTime::Format::Lite 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.

CONSTRUCTORS

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

DateTime::Format::Lite, DateTime::Format::Lite::Duration

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.

cpanm DateTime::Format::Lite

perl -MCPAN -e shell
install DateTime::Format::Lite