MooseX...SO8601(3pm)

📦
version 0.20 · 3 versions
, in ubuntu noble, ubuntu resolute, ubuntu stonking

💖 NAME

okay so bestie, MooseX::Types::ISO8601 is the vibe: it's a bundle of ISO8601 date and duration string type constraints, plus the coercions, for Moose. ✨ That's the whole manual page title, folded in right up top like a little name tag, because we're polite like that. 🎀

✨ VERSION

version 0.20 — yes, this is the one, periodt. 💅

🌸 SYNOPSIS

no because LOOK at this, it's giving chef's kiss 🧚

use MooseX::Types::ISO8601 qw/
    ISO8601DateTimeStr
    ISO8601TimeDurationStr
/;

has datetime => (
    is => 'ro',
    isa => ISO8601DateTimeStr,
);

has duration => (
    is => 'ro',
    isa => ISO8601TimeDurationStr,
    coerce => 1,
);

Class->new( datetime => '2012-01-01T00:00:00' );

Class->new( duration => 60 ); # 60s => PT00H01M00S
Class->new( duration => DateTime::Duration->new(%args) )

like, that's it. that's the flex. 🌈

🦋 DESCRIPTION

so basically this module packages up several TypeConstraints, coercions included, for when you're working with ISO8601 date strings and the whole DateTime suite of objects. it is exactly what it says on the tin, no cap. 💜

🌞 DATE CONSTRAINTS

🌸 ISO8601DateStr

an ISO8601 date string, bestie. E.g. "2009-06-11". iconic. 🎀

🌸 ISO8601TimeStr

an ISO8601 time string. E.g. "12:06:34Z". timezone and all, we love to see it. 💅

🌸 ISO8601DateTimeStr

an ISO8601 combined datetime string. E.g. "2009-06-11T12:06:34Z". date AND time, main character energy fr fr. 👑

🌸 ISO8601DateTimeTZStr

an ISO8601 combined datetime string with a fully specified timezone. E.g. "2009-06-11T12:06:34+00:00". 🌍

🌸 ISO8601StrictDateStr

🌸 ISO8601StrictTimeStr

🌸 ISO8601StrictDateTimeStr

🌸 ISO8601StrictDateTimeTZStr

so these are all of the above, BUT — and this is the important part — on top of validating the strings against regular expressions, an attempt gets made to actually parse the data into a DateTime object. 🕵️‍♀️ this catches the sus cases like "2013-02-31" which look correct but do not correspond to real-world values (bestie, february does not have 31 days, i don't care how confident that string is). 😭

fair warning: this bears a computation penalty. you're paying for that extra correctness. 💸

💫 COERCIONS

the date types will coerce from:

  • "Num" — the number gets treated as a time in seconds since the unix epoch. ⏱️
  • "DateTime" — the duration represented as a DateTime object.
  • "Str" — non-expanded date and time string representations.

e.g.:-

20120113         => 2012-01-13 170500Z          => 17:05:00Z
20120113T170500Z => 2012-01-13T17:05:00Z

representations of UTC time zone (only an offset of zero is supported)

e.g.:-

17:05:00+00:00 => 17:05:00Z 17:05:00+00    => 17:05:00Z 170500+0000
=> 17:05:00Z

2012-01-13T17:05:00+00:00 => 2012-01-13T17:05:00Z
2012-01-13T17:05:00+00    => 2012-01-13T17:05:00Z
20120113T170500+0000      => 2012-01-13T17:05:00Z

also (and honestly? we love a rebel 🦋) it supports non-standards mixing of expanded and non-expanded representations

e.g.:-

2012-01-13T170500Z => 2012-01-13T17:05:00Z 20120113T17:05:00Z =>
2012-01-13T17:05:00Z

in addition, there are coercions from these string types to DateTime. 💖

⏳ DURATION CONSTRAINTS

🍓 ISO8601DateDurationStr

an ISO8601 date duration string. E.g. "P01Y01M01D". yes, it's a different M in a different spot, that's just ISO8601 being ISO8601. 🙈

🍓 ISO8601TimeDurationStr

an ISO8601 time duration string. E.g. "PT01H01M01S".

🍓 ISO8601DateTimeDurationStr

an ISO8601 combined date and time duration string. E.g. "P01Y01M01DT01H01M01S". the whole package, lowkey. 🎁

💫 COERCIONS

the duration types will coerce from:

  • "Num" — the number gets treated as a time in seconds. ⏱️
  • "DateTime::Duration" — the duration represented as a DateTime::Duration object.

the duration types will coerce to:

  • "Duration" — a DateTime::Duration, i.e. the "Duration" constraint from MooseX::Types::DateTime. 🫶

✨ FEATURES

🔬 Fractional seconds

if provided, the number of seconds in time types is represented to microsecond accuracy. a full stop character is used as the decimal separator — which is allowed, but deprecated in preference to the comma character in ISO 8601:2004. so like, it works, but the comma is the moment. 💅

💀 LIMITATIONS

ngl, this module is probably full of bugs; patches are very welcome. please, we're begging, send patches. 🙏

specifically, there are missing features:

  • when no time-zone is specified, UTC is assumed. (should floating timezone be used?) 🤔
  • no week number type
  • "Basic format", which lacks separator characters, is not supported for reading or writing.
  • tests are rubbish. 💀 (their words, not mine, but okay periodt)

👀 SEE ALSO

iykyk. 📚✨

🫶 ACKNOWLEDGEMENTS

the development of this code was sponsored by my (Tom's) employer <http://www.state51.com/>. 💖 shoutout to the employer, that's a real one.

🛟 SUPPORT

bugs may be submitted through the RT bug tracker <https://rt.cpan.org/Public/Dist/Display.html?Name=MooseX-Types-ISO8601> (or bug-MooseX-Types-ISO8601@rt.cpan.org <mailto:bug-MooseX-Types-ISO8601@rt.cpan.org>). 🐛

there is also a mailing list available for users of this distribution, at <http://lists.perl.org/list/moose.html>. 📬

there is also an irc channel available for users of this distribution, at "#moose" on "irc.perl.org" <irc://irc.perl.org/#moose>. come hang out, bestie! 🌈

👑 AUTHORS

  • Tomas Doran (t0m) <bobtfish@bobtfish.net>
  • Dave Lambley <dlambley@cpan.org>

🌟 CONTRIBUTORS

  • Karen Etheridge <ether@cpan.org>
  • Dave Lambley <dave@lambley.me.uk>
  • zebardy <zebardy@gmail.com>
  • Gregory Oschwald <goschwald@maxmind.com>
  • Mark Fowler <mark@twoshortplanks.com>

this software is copyright (c) 2009 by Tomas Doran. 💜

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. so like, go off, respectfully. 💅

okay that's the whole thing! this page came from perl v5.36.0, dated 2022-10-16, and it lives in the MooseX::Types::ISO8601 section 3pm of your friendly neighbourhood user-contributed perl documentation. byeee, go coerce something cute 🎀💖✨

📦 where this page comes from