NAME
DateTimeX::Auto - use DateTime without needing to call constructors
SYNOPSIS
use DateTimeX::Auto -auto;
my $ga_start = '2000-04-06' + 'P10Y';
printf("%s %s\n", $ga_start, ref $ga_start); # 2010-04-06 DateTime
{
no DateTimeX::Auto;
my $string = '2000-04-06';
printf( "%s\n", ref($string) ? 'Ref' : 'NoRef' ); # NoRef
}
DESCRIPTION
DateTime is awesome, but constructing `DateTime` objects can be annoying.
You often need to use one of the formatter modules, or call
`DateTime->new()` with a bunch of values. If you've got a bunch of
constant dates in your code, then `DateTimeX::Auto` makes all this a bit
simpler.
It uses overload to overload the `q()` operator, automatically turning all
string constants that match particular regular expressions into `DateTime`
objects. It also overloads stringification to make sure that `DateTime`
objects get stringified back to exactly the format they were given in.
The date formats supported are:
yyyy-mm-dd
yyyy-mm-ddZ
yyyy-mm-ddThh:mm:ss
yyyy-mm-ddThh:mm:ssZ
The optional trailing 'Z' puts the datetime into the UTC timezone.
Otherwise the datetime will be in DateTime's default (floating) timezone.
Fractional seconds are also supported, to an arbitrary number of decimal
places. However, as `DateTime` only supports nanosecond precision, any
digits after the ninth will be zeroed out.
my $dt ='1234-12-12T12:34:56.123456789123456789';
print "$dt\n"; # 1234-12-12T12:34:56.123456789000000000
Objects are blessed into the `DateTimeX::Auto::DateTime` class which
inherits from `DateTime`. They use UNIVERSAL::ref to masquerade as plain
`DateTime` objects.
print ref('2000-01-01')."\n"; # DateTime
Additionally, ISO 8601 durations are supported:
my $dt = '2000-01-01';
say( $dt + 'P4Y2M12D' ); # 2004-03-13
Durations are possibly not quite as clever at preserving the incoming
string formatting.
The `d` and `dt` Functions
As an alternative `DateTimeX::Auto` can export a function called `d`. This
might be useful if you'd prefer not to have every string constant in your
code turned into a `DateTime`.
use DateTimeX::Auto 'd';
my $dt = d('2000-01-01');
If `d` is called with a string that is in an unrecognised format, it
croaks. If called with no arguments, returns a `DateTime` representing the
current time.
An alias `dt` is also available. They're exactly the same.
The `dur` Function
Called with an ISO 8601 duration string, returns a
DateTimeX::Auto::Duration object.
Object-Oriented Interface
This somewhat negates the purpose of the module, but it's also possible to
use it without exporting anything, in the usual normal Perl
object-oriented fashion:
use DateTimeX::Auto;
my $dt1 = DateTimeX::Auto::DateTime->new('2000-01-01T12:00:00.1234');
# Traditional DateTime style
my $dt2 = DateTimeX::Auto::DateTime->new(
year => 2000,
month => 2,
day => 3,
);
Called in the traditional DateTime style, throws an exception if the date
isn't valid. Called in the DateTimeX::Auto::DateTime stringy style,
returns undef if the date isn't in a recognised format, but throws if it's
otherwise invalid (e.g. 30th of February).
There is similarly a DateTimeX::Auto::Duration class which is a similar
thin wrapper around DateTime::Duration.
EXAMPLES
use DateTimeX::Auto ':auto';
my $date = '2000-01-01';
while ($date < '2000-02-01')
{
print "$date\n";
$date += 'P1D'; # add one day
}
use DateTimeX::Auto 'd';
my $date = d('2000-01-01');
while ($date < d('2000-02-01'))
{
print "$date\n";
$date += dur('P1D'); # add one day
}
SEE ALSO
DateTime, DateTime::Duration, DateTimeX::Easy.
AUTHOR
Toby Inkster <
[email protected]>.
COPYRIGHT
Copyright 2011-2012, 2014 Toby Inkster
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
DISCLAIMER OF WARRANTIES
THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
