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.