NAME

Types::DateTime - type constraints and coercions for datetime objects

SYNOPSIS

   package FroobleGala;
   
   use Moose;
   use Types::DateTime -all;
   
   has start_date => (
      is      => 'ro',
      isa     => DateTimeUTC->plus_coercions( Format['ISO8601'] ),
      coerce  => 1,
   );

DESCRIPTION

Types::DateTime is a type constraint library suitable for use with Moo/Moose attributes, Kavorka sub signatures, and so forth.

Types

This module provides some type constraints broadly compatible with those provided by MooseX::Types::DateTime, plus a couple of extra type constraints.

DateTime

A class type for DateTime. Coercions from:

from Num

Uses "from_epoch" in DateTime. Floating values will be used for sub-second precision, see DateTime for details.

from HashRef

Calls "new" in DateTime or "from_epoch" in DateTime as appropriate, passing the hash as arguments.

from Now

Uses "now" in DateTime.

from InstanceOf['DateTime::Tiny']

Inflated using "DateTime" in DateTime::Tiny.

Duration

A class type for DateTime::Duration. Coercions from:

from Num

Uses "new" in DateTime::Duration and passes the number as the seconds argument.

from HashRef

Calls "new" in DateTime::Duration with the hash entries as arguments.

Locale

A class type for DateTime::Locale. Coercions from:

from Str

The string is treated as a language tag (e.g. en or he_IL) and given to "load" in DateTime::Locale.

from InstanceOf['Locale::Maketext']

The Locale::Maketext/language_tag attribute will be used with "load" in DateTime::Locale.

TimeZone

A class type for DateTime::TimeZone. Coercions from:

from Str

Treated as a time zone name or offset. See "USAGE" in DateTime::TimeZone for more details on the allowed values.

Delegates to "new" in DateTime::TimeZone with the string as the name argument.

Now

Type constraint with only one allowed value, the string "now".

This is exported for compatibility with MooseX::Types::DateTime, which exports such a constraint, even though it is not documented.

DateTimeWithZone

A subtype of DateTime for objects with a defined (non-floating) time zone.

This type constraint inherits its coercions from DateTime.

DateTimeWithZone[`a]

The DateTimeWithZone type constraint may be parameterized with a DateTime::TimeZone object, or a string that can be coerced into one.

   has start_date => (
      is      => 'ro',
      isa     => DateTimeWithZone['Europe/London'],
      coerce  => 1,
   );

This type constraint inherits its coercions from DateTime, and will additionally call "set_time_zone" in DateTime to shift objects into the correct timezone.

DateTimeUTC

Shortcut for DateTimeWithZone["UTC"].

Named Coercions

It is hoped that Type::Tiny will help avoid the proliferation of modules like MooseX::Types::DateTimeX, MooseX::Types::DateTime::ButMaintained, and MooseX::Types::DateTime::MoreCoercions. It makes it very easy to add coercions to a type constraint at the point of use:

   has start_date => (
      is      => 'ro',
      isa     => DateTime->plus_coercions(
         InstanceOf['MyApp::DT'] => sub { $_->to_DateTime }
      ),
      coerce  => 1,
   );

Even easier, this module exports some named coercions.

Format[`a]

May be passed an object providing a parse_datetime method, or a class name from the DateTime::Format:: namespace (upon which new will be called).

For example:

   DateTime->plus_coercions( Format['ISO8601'] )

Or:

   DateTimeUTC->plus_coercions(
      Format[
         DateTime::Format::Natural->new(lang => 'en')
      ]
   )

Strftime[`a]

A pattern for serializing a DateTime object into a string using "strftime" in DateTime.

   Str->plus_coercions( Strftime['%a %e %b %Y'] );

ToISO8601

A coercion for serializing a DateTime object into a string using "iso8601" in DateTime.

   Str->plus_coercions( ToISO8601 );

BUGS

Please report any bugs to http://rt.cpan.org/Dist/Display.html?Queue=Types-DateTime.

SEE ALSO

MooseX::Types::DateTime, Type::Tiny::Manual, DateTime, DateTime::Duration, DateTime::Locale, DateTime::TimeZone.

AUTHOR

Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE

This software is copyright (c) 2014, 2017 by Toby Inkster.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system 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.