DateTime::Format::ICal(3pm)

1DateTime::Format::ICal(U3s)er Contributed Perl DocumentatDiaotneTime::Format::ICal(3)
2
3
4

NAME

6       DateTime::Format::ICal - Parse and format iCal datetime and duration
7       strings
8

SYNOPSIS

10         use DateTime::Format::ICal;
11
12         my $dt = DateTime::Format::ICal->parse_datetime( '20030117T032900Z' );
13
14         my $dur = DateTime::Format::ICal->parse_duration( '+P3WT4H55S' );
15
16         # 20030117T032900Z
17         DateTime::Format::ICal->format_datetime($dt);
18
19         # +P3WT4H55S
20         DateTime::Format::ICal->format_duration($dur);
21

DESCRIPTION

23       This module understands the ICal date/time and duration formats, as
24       defined in RFC 2445.  It can be used to parse these formats in order to
25       create the appropriate objects.
26

METHODS

28       This class offers the following methods.
29
30       * parse_datetime($string)
31           Given an iCal datetime string, this method will return a new "Date‐
32           Time" object.
33
34           If given an improperly formatted string, this method may die.
35
36       * parse_duration($string)
37           Given an iCal duration string, this method will return a new "Date‐
38           Time::Duration" object.
39
40           If given an improperly formatted string, this method may die.
41
42       * parse_period($string)
43           Given an iCal period string, this method will return a new "Date‐
44           Time::Span" object.
45
46           If given an improperly formatted string, this method may die.
47
48       * parse_recurrence( recurrence => $string, ... )
49           Given an iCal recurrence description, this method uses "Date‐
50           Time::Event::ICal" to create a "DateTime::Set" object representing
51           that recurrence.  Any parameters given to this method beside
52           "recurrence" and "until" will be passed directly to the "Date‐
53           Time::Event::ICal->recur" method.  If "until" is given as an iCal
54           format datetime, it will be parsed and turned into an object first.
55
56           If given an improperly formatted string, this method may die.
57
58           This method accepts optional parameters "dtstart" and "dtend".
59           These parameters must be "DateTime" objects.
60
61           The iCal spec requires that "dtstart" always be included in the
62           recurrence set, unless this is an "exrule" statement.  Since we
63           don't know what kind of statement is being parsed, we do not
64           include "dtstart" in the recurrence set.
65
66       * format_datetime($datetime)
67           Given a "DateTime" object, this methods returns an iCal datetime
68           string.
69
70           The iCal spec requires that datetimes be formatted either as float‐
71           ing times (no time zone), UTC (with a 'Z' suffix) or with a time
72           zone id at the beginning ('TZID=America/Chicago;...').  If this
73           method is asked to format a "DateTime" object that has an offset-
74           only time zone, then the object will be converted to the UTC time
75           zone internally before formatting.
76
77           For example, this code:
78
79               my $dt = DateTime->new( year => 1900, hour => 15, time_zone => '-0100' );
80
81               print $ical->format_datetime($dt);
82
83           will print the string "19000101T160000Z".
84
85       * format_duration($duration)
86           Given a "DateTime::Duration" object, this methods returns an iCal
87           duration string.
88
89           The iCal standard does not allow for months or years in a duration,
90           so if a duration for which "delta_months()" is not zero is given,
91           then this method will die.
92
93       * format_period($span)
94           Given a "DateTime::Span" object, this methods returns an iCal
95           period string, using the format "DateTime/DateTime".
96
97       * format_period_with_duration($span)
98           Given a "DateTime::Span" object, this methods returns an iCal
99           period string, using the format "DateTime/Duration".
100
101       * format_recurrence($arg [,$arg...] )
102           This method returns a list of strings containing ICal statements.
103
104           The argument can be a "DateTime" list, a "DateTime::Span" list, a
105           "DateTime::Set", or a "DateTime::SpanSet".
106
107           ICal "DATE" values are not supported. Whenever a date value is
108           found, a "DATE-TIME" is generated.
109
110           If a recurrence has an associated "DTSTART" or "DTEND", those val‐
111           ues must be formatted using "format_datetime()".  The "for‐
112           mat_recurrence()" method will not do this for you.
113
114           If a "union" or "complement" of recurrences is being formatted,
115           they are assumed to have the same "DTSTART" value.
116
117           Only "union" and "complement" operations are supported for recur‐
118           rences.  This is a limitation of the ICal specification.
119
120           If given a set it cannot format, this method may die.
121
122           Only "DateTime::Set::ICal" objects are formattable.  A set may
123           change class after some set operations:
124
125               $recurrence = $recurrence->union( $dt_set );
126               # Ok - $recurrence still is a DT::Set::ICal
127
128               $recurrence = $dt_set->union( $recurrence );
129               # Not Ok! - $recurrence is a DT::Set now
130
131           The only unbounded recurrences currently supported are the ones
132           generated by the "DateTime::Event::ICal" module.
133
134           You can add ICal formatting support to a custom recurrence by using
135           the "DateTime::Set::ICal" module:
136
137               $custom_recurrence =
138                   DateTime::Set::ICal->from_recurrence
139                       ( recurrence =>
140                         sub { $_[0]->truncate( to => 'month' )->add( months => 1 ) }
141                       );
142               $custom_recurrence->set_ical( include => [ 'FREQ=MONTHLY' ] );
143

SUPPORT

145       Support for this module is provided via the datetime@perl.org email
146       list.  See http://lists.perl.org/ for more details.
147

AUTHORS

149       Dave Rolsky <autarch@urth.org> and Flavio Soibelmann Glock
150       <fglock@pucrs.br>
151
152       Some of the code in this module comes from Rich Bowen's "Date::ICal"
153       module.
154

COPYRIGHT

156       Copyright (c) 2003 David Rolsky.  All rights reserved.  This program is
157       free software; you can redistribute it and/or modify it under the same
158       terms as Perl itself.
159
160       The full text of the license can be found in the LICENSE file included
161       with this module.
162