/ 
DateTime-Format-Lite-v0.1.0
/ README.md

NAME

DateTime::Format::Lite - Parse and format datetimes with strptime patterns, returning DateTime::Lite objects

SYNOPSIS

use DateTime::Format::Lite;

my $fmt = DateTime::Format::Lite->new(
    pattern   => '%Y-%m-%dT%H:%M:%S',
    locale    => 'ja-JP',
    time_zone => 'Asia/Tokyo',
) || die( DateTime::Format::Lite->error );

my $dt  = $fmt->parse_datetime( '2026-04-14T09:00:00' );
my $str = $fmt->format_datetime( $dt );

# Exportable convenience functions
use DateTime::Format::Lite qw( strptime strftime );
my $dt2  = strptime( '%Y-%m-%d', '2026-04-14' );
my $str2 = strftime( '%Y-%m-%d', $dt2 );

VERSION

v0.1.0

DESCRIPTION

DateTime::Format::Lite parses and formats datetime strings using strptime-style patterns, returning DateTime::Lite objects.

It is a replacement for DateTime::Format::Strptime designed for the DateTime::Lite ecosystem, with the following key differences:

CONSTRUCTORS

new

my $fmt = DateTime::Format::Lite->new(
    pattern   => '%Y-%m-%d %H:%M:%S',
    locale    => 'fr-FR',
    time_zone => 'Europe/Paris',
    on_error  => 'undef',
    strict    => 0,
    zone_map  => { BST => 'Europe/London' },
) || die( DateTime::Format::Lite->error );

The pattern parameter is required. All others are optional.

METHODS

format_datetime

my $string = $fmt->format_datetime( $dt );

Formats a DateTime::Lite object using the configured pattern. Delegates directly to DateTime::Lite-strftime> without cloning.

Returns a string, or undef on error.

format_duration

my $string = $fmt->format_duration( $duration );

Formats a DateTime::Lite::Duration object as an ISO 8601 duration string such as P1Y2M3DT4H5M6S. A zero duration returns PT0S.

parse_datetime

my $dt = $fmt->parse_datetime( '2026-04-14 09:00:00' );

Parses $string against the configured pattern and returns a DateTime::Lite object on success, or undef on failure (with the error accessible via $fmt->error).

parse_duration

my $dur = $fmt->parse_duration( 'P1Y2M3DT4H5M6S' );

Parses an ISO 8601 duration string and returns a DateTime::Lite::Duration object.

ACCESSORS

debug

Boolean. When set to a true value, emits diagnostic warnings during pattern compilation and timezone resolution.

error

my $err = DateTime::Format::Lite->error;   # class-level last error
my $err = $fmt->error;                     # instance-level last error

Returns the last DateTime::Format::Lite::Exception object set by a failed operation, or undef if no error has occurred. When called as a class method it returns the last error set by any instance or constructor call. When called as an instance method it returns the last error set on that specific object.

fatal

Boolean. When true, any error calls die() immediately instead of returning undef. Equivalent to setting on_error => die at the instance level but applies globally when set as a class method.

locale

A BCP47 locale string (such as fr-FR or ja-JP), a DateTime::Locale::FromCLDR object, or a Locale::Unicode object. Defaults to en.

Controls the locale used for parsing and formatting locale-sensitive tokens such as %a, %A, %b, %B, and %p.

on_error

Error handling mode. One of:

pass_error

return( $self->pass_error );
return( $self->pass_error( $other_object ) );

Propagates the last error from $self (or from $other_object if provided) up the call stack. Returns undef in scalar context or an empty list in list context. Used internally to chain error propagation between methods.

pattern

The strptime pattern string, such as '%Y-%m-%dT%H:%M:%S'. Required at construction time; may be updated after construction.

strict

Boolean. When true, the generated regex is anchored with word boundaries (\b) at both ends. This prevents matching a date pattern embedded in a longer string such as 2016-03-31.log from matching if the surrounding characters would cause a word-boundary failure.

time_zone

A timezone name (Asia/Tokyo, UTC, floating) or a DateTime::Lite::TimeZone object. When set, this timezone is applied to every parsed object, overriding any timezone parsed from %z, %Z, or %O.

zone_map

A hash reference mapping timezone abbreviations to IANA names or numeric offset strings. Useful for resolving ambiguous abbreviations such as IST (which maps to India, Ireland, and Israel):

zone_map => { IST => 'Asia/Kolkata' }

Setting a key to undef marks the abbreviation as explicitly ambiguous (always an error if encountered during parsing).

TOKENS

%Y  Four-digit year
%y  Two-digit year (69-99 -> 19xx, 00-68 -> 20xx)
%C  Century (combined with %y)
%m  Month (01-12)
%d  Day of month (01-31)
%e  Day of month, space-padded
%H  Hour 24h (00-23)
%k  Hour 24h, space-padded
%I  Hour 12h (01-12)
%l  Hour 12h, space-padded
%M  Minute (00-59)
%S  Second (00-60)
%N  Nanoseconds (scaled to 9 digits; %3N -> milliseconds, etc.)
%p  AM/PM (locale-aware, case-insensitive)
%P  am/pm (alias for %p)
%a  Abbreviated weekday name (locale-aware)
%A  Full weekday name (locale-aware)
%b  Abbreviated month name (locale-aware)
%B  Full month name (locale-aware)
%h  Alias for %b
%j  Day of year (001-366)
%s  Unix epoch timestamp (positive or negative; pre-1970 dates use negative values)
%u  Day of week (1=Mon .. 7=Sun, ISO)
%w  Day of week (0=Sun .. 6=Sat)
%U  Week number, Sunday as first day (00-53)
%W  Week number, Monday as first day (00-53)
%G  ISO week year (4 digits)
%g  ISO week year (2 digits)
%z  Timezone offset: Z, +HH:MM, +HHMM, +HH
%Z  Timezone abbreviation such as JST or EDT
%O  Olson/IANA timezone name such as Asia/Tokyo
%D  Equivalent to %m/%d/%y
%F  Equivalent to %Y-%m-%d
%T  Equivalent to %H:%M:%S
%R  Equivalent to %H:%M
%r  Equivalent to %I:%M:%S %p
%c  Locale datetime format (fixed C-locale fallback: "%a %b %e %T %Y")
%x  Locale date format (fixed C-locale fallback: "%m/%d/%y")
%X  Locale time format (fixed C-locale fallback: "%T")
%n  Whitespace
%t  Whitespace
%%  Literal percent sign

EXPORTABLE FUNCTIONS

use DateTime::Format::Lite qw( strptime strftime );

my $dt  = strptime( '%Y-%m-%d', '2026-04-14' );
my $str = strftime( '%Y-%m-%d', $dt );

Both functions dies on error.

strptime

my $dt = strptime( $pattern, $string );

Convenience wrapper. Constructs a one-shot DateTime::Format::Lite with $pattern and calls parse_datetime( $string ). Dies on error (constructor or parse failure).

strftime

my $str = strftime( $pattern, $dt );

Convenience wrapper. Constructs a one-shot DateTime::Format::Lite with $pattern and calls format_datetime( $dt ). Dies on error.

ERROR HANDLING

On error, this class methods set an exception object, and return undef in scalar context, or an empty list in list context. The exception object is accessible via:

my $err = DateTime::Format::Lite->error;  # class method
my $err = $dt->error;                     # instance method

The exception object stringifies to a human-readable message including file and line number.

error detects the context is chaining, or object, and thus instead of returning undef, it will return a dummy instance of DateTime::Format::Lite::Null to avoid the typical perl error Can't call method '%s' on an undefined value.

So for example:

$fmt->parse_datetime( %bad_arguments )->iso8601;

If there was an error in parse_datetime, the chain will execute, but the last one, iso8601 in this example, will return undef, so you can and even should check the return value:

$fmt->parse_datetime( %bad_arguments )->iso8601 ||
    die( $fmt->error );

SERIALISATION

DateTime::Format::Lite supports serialisation via Storable, Sereal, CBOR::XS, and JSON serialisers.

The following methods are implemented:

SEE ALSO

DateTime::Lite, DateTime::Lite::TimeZone, DateTime::Format::Strptime, DateTime::Format::Unicode, DateTime::Locale::FromCLDR, Locale::Unicode, Locale::Unicode::Data

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.