DateTime::Format::ICal - Parse and format iCal datetime and duration strings
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);
This module understands the ICal date/time and duration formats, as defined in RFC 2445. It can be used to parse these formats in order to create the appropriate objects.
This class offers the following methods.
parse_datetime($string)
Given an iCal datetime string, this method will return a new DateTime object.
DateTime
If given an improperly formatted string, this method may die.
parse_duration($string)
Given an iCal duration string, this method will return a new DateTime::Duration object.
DateTime::Duration
parse_period($string)
Given an iCal period string, this method will return a new DateTime::Span object.
DateTime::Span
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 given to this method beside "recurrence" will be passed directly to the DateTime::Event::ICal->recur method.
DateTime::Event::ICal
DateTime::Set
DateTime::Event::ICal->recur
This method accepts optional parameters "dtstart" and "dtend". These parameters must be DateTime objects.
The iCal spec requires that "dtstart" always be included in the recurrence set, unless this is an "exrule" statement. Since we don't know what kind of statement is being parsed, we do not include dtstart in the recurrence set.
dtstart
format_datetime($datetime)
Given a DateTime object, this methods 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".
format_duration($duration)
Given a DateTime::Duration object, this methods 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.
delta_months()
format_period($span)
Given a DateTime::Span object, this methods returns an iCal period string, using the format DateTime/DateTime.
DateTime/DateTime
format_period_with_duration($span)
Given a DateTime::Span object, this methods returns an iCal period string, using the format DateTime/Duration.
DateTime/Duration
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.
DateTime::SpanSet
ICal DATE values are not supported. Whenever a date value is found, a DATE-TIME is generated.
DATE
DATE-TIME
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.
DTSTART
DTEND
format_datetime()
format_recurrence()
If a union or complement of recurrences is being formatted, they are assumed to have the same DTSTART value.
union
complement
Only union and complement operations are supported for recurrences. This is a limitation of the ICal specification.
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:
DateTime::Set::ICal
$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 for this module is provided via the datetime@perl.org email list. See http://lists.perl.org/ for more details.
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.
Date::ICal
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.
datetime@perl.org mailing list
http://datetime.perl.org/
To install DateTime::Format::ICal, copy and paste the appropriate command in to your terminal.
cpanm
cpanm DateTime::Format::ICal
CPAN shell
perl -MCPAN -e shell install DateTime::Format::ICal
For more information on module installation, please visit the detailed CPAN module installation guide.