DateTi...::ICal(3pm)

💖 DateTime::Format::ICal — the 3pm manual, but make it cute ✨

okay bestie, so this is DateTime::Format::ICal, and she is the queen of parsing and formatting iCal datetime and duration strings. no cap. if you've ever stared at 20030117T032900Z and felt something, this module is for you 🫶

---

🌸 SYNOPSIS 🌸

here's the whole vibe in five lines, literally:

use DateTime::Format::ICal;

my $dt = DateTime::Format::ICal->parse_datetime( '20030117T032900Z' );

my $dur = DateTime::Format::ICal->parse_duration( '+P3WT4H55S' );

# 20030117T032900Z
DateTime::Format::ICal->format_datetime($dt);

# +P3WT4H55S
DateTime::Format::ICal->format_duration($dur);

see how it goes both ways?? parse in, format out. it's giving versatility 💅

---

🦋 DESCRIPTION 🦋

so this module understands the ICal date/time and duration formats, as defined in RFC 2445. that's the whole personality. it can be used to parse these formats in order to create the appropriate objects. iconic behavior, honestly. ⭐

---

✨ METHODS ✨

this class offers the following methods. one bullet per method, no skips, we don't do that here:

• parse_datetime($string) — give her an iCal datetime string and she hands you back a brand new DateTime object. 💖 if the string is improperly formatted, this method may die. dramatic? yes. avoidable? also yes.
• parse_duration($string) — hand her an iCal duration string, get a new DateTime::Duration object back. if the string is improperly formatted, this method may die. same energy. 💀
• parse_period($string) — give her an iCal period string, receive a new DateTime::Span object. if the string is improperly formatted, this method may die. (noticing a pattern? 🎀)
• parse_recurrence( recurrence => $string, ... ) — given an iCal recurrence description, this method uses DateTime::Event::ICal to create a DateTime::Set object representing that recurrence. any parameters you pass beside recurrence get passed directly to the DateTime::Event::ICal->recur method. if the string is improperly formatted, this method may die. 😭

this method accepts the optional parameters dtstart and dtend. those parameters must be DateTime objects.

the iCal spec requires that dtstart always be included in the recurrence set, unless this is an exrule statement. but since we don't know what kind of statement is being parsed, we do not include dtstart in the recurrence set. it's a whole thing, iykyk.

• format_datetime($datetime) — give her a DateTime object, she returns an iCal datetime string. 🌈

the iCal spec requires that datetimes be formatted either as floating times (no time zone), UTC (with a 'Z' suffix) or with a time zone id at the beginning ('TZID=America/Chicago;...'). if this method is asked to format a DateTime object that has an offset-only time zone, then the object will be converted to the UTC time zone internally before formatting. ✨

for example, this code:

my $dt = DateTime->new( year => 1900, hour => 15, time_zone => '-0100' );

print $ical->format_datetime($dt);

will print the string "19000101T160000Z". math is mathing. 🧚

• format_duration($duration) — give her a DateTime::Duration object, she returns an iCal duration string.

the iCal standard does not allow for months or years in a duration, so if a duration for which delta_months() is not zero is given, then this method will die. periodt. 💀

• format_period($span) — give her a DateTime::Span object, she returns an iCal period string, using the format DateTime/DateTime. 🔥
• format_period_with_duration($span) — give her a DateTime::Span object, she returns an iCal period string, using the format DateTime/Duration. same but with duration energy. 💜
• format_recurrence($arg [,$arg...] ) — this method returns a list of strings containing ICal statements. in scalar context it returns a single string which may contain embedded newlines.

the argument can be a DateTime list, a DateTime::Span list, a DateTime::Set, or a DateTime::SpanSet.

ICal DATE values are not supported. whenever a date value is found, a DATE-TIME is generated. 🙈

if a recurrence has an associated DTSTART or DTEND, those values must be formatted using format_datetime(). the format_recurrence() method will not do this for you. you're on your own for that one bestie.

if a union or complement of recurrences is being formatted, they are assumed to have the same DTSTART value.

only union and complement operations are supported for recurrences. this is a limitation of the ICal specification. not us, it's the spec. 💅

if given a set it cannot format, this method may die.

only DateTime::Set::ICal objects are formattable. a set may change class after some set operations:

$recurrence = $recurrence->union( $dt_set );
# Ok - $recurrence still is a DT::Set::ICal

$recurrence = $dt_set->union( $recurrence );
# Not Ok! - $recurrence is a DT::Set now

the only unbounded recurrences currently supported are the ones generated by the DateTime::Event::ICal module.

you can add ICal formatting support to a custom recurrence by using the DateTime::Set::ICal module:

$custom_recurrence =
    DateTime::Set::ICal->from_recurrence
        ( recurrence =>
          sub { $_[0]->truncate( to => 'month' )->add( months => 1 ) }
        );
$custom_recurrence->set_ical( include => [ 'FREQ=MONTHLY' ] );

---

🫶 SUPPORT 🫶

support for this module is provided via the datetime@perl.org email list. see http://lists.perl.org/ for more details. go say hi, they're nice 💖

---

👑 AUTHORS 👑

Dave Rolsky <autarch@urth.org> and Flavio Soibelmann Glock <fglock@pucrs.br>

some of the code in this module comes from Rich Bowen's Date::ICal module. shoutout to Rich, legendary. 🌟

---

💜 COPYRIGHT 💜

Copyright (c) 2003 David Rolsky. All rights reserved. this program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

the full text of the license can be found in the LICENSE file included with this module. read it, bestie, it's short and it loves you. 🎀

---

🌈 SEE ALSO 🌈

• datetime@perl.org mailing list
• http://datetime.perl.org/

---

💅 that's the whole page, no skips, no lies, every single detail accounted for. you're welcome.

okay and finally, the cute lil' sign-off: this was rendered from perl v5.34.0, dated 2022-06-13, and it's the DateTime::Format::ICal(3pm) page. mwah 💋 go format something gorgeous. ✨🦋💖