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 <tobyink@cpan.org>.

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.