DateTime::Format::ICalUser Contributed Perl DocumentaDateTime::Format::ICal(3)NAMEDateTime::Format::ICal - Parse and format iCal datetime and duration
strings
SYNOPSIS
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);
DESCRIPTION
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.
METHODS
This class offers the following methods.
· parse_datetime($string)
Given an iCal datetime string, this method will return a new
"DateTime" object.
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.
If given an improperly formatted string, this method may die.
· parse_period($string)
Given an iCal period string, this method will return a new
"DateTime::Span" object.
If given an improperly formatted string, this method may die.
· 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.
If given an improperly formatted string, this method may die.
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.
· 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.
· format_period($span)
Given a "DateTime::Span" object, this methods returns an iCal
period string, using the format "DateTime/DateTime".
· format_period_with_duration($span)
Given a "DateTime::Span" object, this methods returns an iCal
period string, using the format "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".
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.
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.
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.
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.
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.
SEE ALSO
datetime@perl.org mailing list
http://datetime.perl.org/
perl v5.14.1 2011-07-21 DateTime::Format::ICal(3)