Types::DateTime(3pm)

📦
version 0.002 · 8 versions
, in debian bookworm, ubuntu noble

💖 Types::DateTime 💖

okay bestie, so this is Types::DateTime — it lives in the User Contributed Perl Documentation section of your man pages, and it is literally the type-constraint-and-coercion glow-up for datetime objects. it's giving "your Moose attributes finally got taste" ✨

🌸 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 ✨

okay so Types::DateTime is a type constraint library, and it's built for use with Moo/Moose attributes, Kavorka sub signatures, and so forth. she's versatile, she's booked, she's everywhere 🦋

🌈 Types

this module provides some type constraints that are broadly compatible with the ones MooseX::Types::DateTime hands out, plus a couple of extra type constraints. bonus content, no cap.

DateTime

a class type for DateTime. and she coerces from:

  • from Num — uses from_epoch in DateTime. floating values will be used for sub-second precision, see DateTime for the details. yes, sub-second. we're precise here 💅
  • 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. coerces 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. coerces 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. coerces 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. 🙈 (yes bestie, undocumented. we're just being polite about it.)

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. moving you to London, metaphorically 🦋

DateTimeUTC

shortcut for DateTimeWithZone["UTC"]. that's it. that's the whole vibe. ✨

💜 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. (we do not need a hundred of those, bestie, we need ✨one✨.) 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>. bestie if something's broken, tell the internet, not me 😭

👀 SEE ALSO 👀

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

🫶 AUTHOR 🫶

Toby Inkster <tobyink@cpan.org>. an icon, an absolute legend 👑

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.

okay so this is the part where we all pretend we're chill about it: no warranties, periodt. merchantability? fitness for a particular purpose? not promised, bestie. it's giving "you get what you get and you don't get upset." 💅

and that's the whole page!! 💖 this lil doc was rendered from perl v5.34.0 and dated 2022-06-28 — so if you're reading this from the future, hiii, hope the datetime types still slay. bye bestie!! 🎀🦋✨

📦 where this page comes from