NAME
DBIO::Storage::DateTimeFormat - Strptime-backed datetime format base for driver format classes
VERSION
version 0.900005
SYNOPSIS
package DBIO::DriverName::DateTime::Format;
# ABSTRACT: DateTime parsing for DriverName
use base 'DBIO::Storage::DateTimeFormat';
__PACKAGE__->preferred_format_class('DateTime::Format::DriverName'); # optional
__PACKAGE__->datetime_parse_pattern('%Y-%m-%d %H:%M:%S.%3N');
__PACKAGE__->datetime_format_pattern('%Y-%m-%d %H:%M:%S.%3N');
__PACKAGE__->date_parse_pattern('%Y-%m-%d'); # optional, enables parse_date
__PACKAGE__->date_format_pattern('%Y-%m-%d');
1;Then point the storage at it:
__PACKAGE__->datetime_parser_type('DBIO::DriverName::DateTime::Format');See t/datetime_format.t for a runnable example.
DESCRIPTION
Base class for driver datetime format classes where no (maintained) CPAN DateTime::Format::* module exists. Subclasses declare strptime patterns as class data and may name a preferred CPAN format class: when that class is installed it handles all calls, otherwise the declared patterns are used via DateTime::Format::Strptime.
That module is only a recommends of the core distribution. It is loaded at the first parse or format, which throws when it is missing, so a driver distribution using the declared patterns lists it in its own prerequisites.
Patterns are read once per class and the resulting parser objects are cached — set the class data at load time, not dynamically.
ATTRIBUTES
preferred_format_class
Optional name of a CPAN format class (e.g. DateTime::Format::Sybase). Delegated to when loadable; declare it as suggests in the driver cpanfile. The fallback patterns MUST round-trip identically to the preferred class.
datetime_parse_pattern
datetime_format_pattern
Strptime patterns backing "parse_datetime" and "format_datetime".
date_parse_pattern
date_format_pattern
Optional strptime patterns backing "parse_date" and "format_date".
METHODS
_strptime_for
my $parser = $class->_strptime_for($slot, $accessor);Builds (and caches) the DateTime::Format::Strptime object that backs the public parse_* / format_* helpers. A driver format class calls it from a parse_<type> / format_<type> pair of its own, as in "Offering a type of its own".
The strptime dependency is loaded lazily, not at compile time: a bare DBIO install that never inflates a DateTime column carries no DateTime::Format::Strptime in %INC at all. Only a driver format class that actually parses/formats via the strptime patterns pulls it in — and only at the point of first use, so the missing-pattern guard above still fires without DateTime::Format::Strptime being present. The requires DateTime::Format::Strptime 1.2 entry in the core cpanfile is therefore recommends, not requires: the runtime cost lands exactly on the install that pays it.
parse_datetime
my $dt = $class->parse_datetime($string);Parses a datetime string from the database into a DateTime object, via the preferred format class when loadable, otherwise via datetime_parse_pattern.
format_datetime
my $string = $class->format_datetime($dt);Formats a DateTime object for the database, via the preferred format class when loadable, otherwise via datetime_format_pattern.
parse_date
my $dt = $class->parse_date($string);Like "parse_datetime" for plain dates. Delegates to the preferred format class only when it implements parse_date; otherwise requires date_parse_pattern to be set.
format_date
my $string = $class->format_date($dt);Like "format_datetime" for plain dates. Delegates to the preferred format class only when it implements format_date; otherwise requires date_format_pattern to be set.
Offering a type of its own
DBIO::InflateColumn::DateTime sends a column of type datetime2 to parse_datetime2 and format_datetime2 of the storage's parser when the parser has them (see "One channel per column type" in DBIO::InflateColumn::DateTime for how the type name is formed). A format class offers such a type by defining the two methods. They may read their strptime patterns from class data of their own, through the same helper the base class uses:
__PACKAGE__->mk_group_accessors('inherited' =>
qw/datetime2_parse_pattern datetime2_format_pattern/);
__PACKAGE__->datetime2_parse_pattern('%Y-%m-%d %H:%M:%S.%7N');
__PACKAGE__->datetime2_format_pattern('%Y-%m-%d %H:%M:%S.%7N');
sub parse_datetime2 {
my ($class, $value) = @_;
return $class->_strptime_for(datetime2_parse => 'datetime2_parse_pattern')
->parse_datetime($value);
}
sub format_datetime2 {
my ($class, $dt) = @_;
return $class->_strptime_for(datetime2_format => 'datetime2_format_pattern')
->format_datetime($dt);
}A time of day is offered the same way: parse_time and format_time serve a time and a time without time zone column, parse_timetz and format_timetz (or the pair of the type's own channel) a type with a time zone. Whatever date the parser returns, the inflating component stands the value on 1970-01-01; the pair needs to carry only the time (and the offset).
The base class does not create these methods or their pattern accessors; it only provides the pair for datetime and the pair for date. A class that defines parse_datetime2 without format_datetime2 is read on the datetime2 channel and written through format_datetime.
AUTHOR
DBIO & DBIx::Class Authors
COPYRIGHT AND LICENSE
Copyright (C) 2026 DBIO Authors Portions Copyright (C) 2005-2025 DBIx::Class Authors Based on DBIx::Class, heavily modified.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.