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: No heavy dependencies No "Params::ValidationCompiler", "Specio", or "Try::Tiny". Validation follows the same lightweight philosophy as "DateTime::Lite" itself. Returns "DateTime::Lite" objects "parse_datetime" returns DateTime::Lite objects rather than DateTime objects. Dynamic timezone abbreviation resolution Rather than a static hardcoded table of ~300 entries, timezone abbreviations are resolved live against the IANA data in the SQLite database bundled with "DateTime::Lite::TimeZone", via "resolve_abbreviation" in DateTime::Lite::TimeZone. The resolution is automatically up to date with each tzdata release. XS-accelerated hot paths When a C compiler is available at install time, "_match_and_extract" and "format_datetime" are implemented in XS for reduced per-call overhead. A pure-Perl fallback is used automatically otherwise. Error handling via "error()" Errors set an error object accessible via "$fmt->error" and return "undef", consistent with "DateTime::Lite". Fatal mode is available via "on_error => 'croak'". 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. "pattern" A strptime-style format string. See "TOKENS". "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". "time_zone" An IANA timezone name string (such as "Asia/Tokyo") or a DateTime::Lite::TimeZone object. When provided, it is applied to the parsed object after construction. If omitted, the parsed object uses the floating timezone unless the pattern itself contains %z, %Z, or %O. "on_error" Error handling mode: 'undef' (default - returns "undef" on error), 'croak' (dies with the error message), or a code reference invoked as "$coderef->( $fmt_object, $message )". "strict" If true, wraps the compiled regex with word-boundary anchors, requiring the input datetime to be delimited from surrounding text. "zone_map" A hash reference of abbreviation overrides. Keys are abbreviation strings; values are IANA timezone names or numeric offset strings. Set a key to "undef" to mark an abbreviation as explicitly ambiguous (always errors if encountered during parsing). 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: "undef" (default) Returns "undef" on error and stores the exception in "$fmt->error". "die" Calls "die()" with the exception object. "coderef" Calls "$coderef->( $fmt, $message )". The coderef receives the formatter object and the error message string. 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: "FREEZE" / "THAW" Used by Sereal (v4+) and CBOR::XS. The object is reduced to its public configuration state (pattern, locale, time_zone, on_error, strict, debug, zone_map). Internal caches are not serialised and are rebuilt on demand after thawing. "STORABLE_freeze" / "STORABLE_thaw" Used by Storable. The state is encoded as a compact pipe-delimited string. The zone_map is JSON-encoded when non-empty. "TO_JSON" Returns the public configuration state as a plain hashref, suitable for serialisation by JSON::XS, Cpanel::JSON::XS, or similar. The returned hashref contains: "pattern", "locale" (BCP47 string), "time_zone" (IANA name string or "undef"), "on_error", "strict", "debug", and "zone_map". Note that if "on_error" was set to a code reference, it cannot be serialised. 'undef' is stored as a fallback and a warning is issued if the "DateTime::Format::Lite" warning category is enabled. SEE ALSO DateTime::Lite, DateTime::Lite::TimeZone, DateTime::Format::Strptime, DateTime::Format::Unicode, DateTime::Locale::FromCLDR, Locale::Unicode, Locale::Unicode::Data AUTHOR Jacques Deguest 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.