/ 
DBIO-0.900004
/ DBIO::Storage::DateTimeFormat

NAME

DBIO::Storage::DateTimeFormat - Strptime-backed datetime format base for driver format classes

VERSION

version 0.900004

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);

Internal: builds (and caches) the DateTime::Format::Strptime object that backs the public parse_* / format_* helpers.

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.

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.