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

SUPPORT

155       Support for this module is provided via the datetime@perl.org email
156       list.  See http://lists.perl.org/ for more details.
157

AUTHORS

159       Dave Rolsky <autarch@urth.org> and Flavio Soibelmann Glock
160       <fglock@pucrs.br>
161
162       Some of the code in this module comes from Rich Bowen's "Date::ICal"
163       module.
164

COPYRIGHT

166       Copyright (c) 2003 David Rolsky.  All rights reserved.  This program is
167       free software; you can redistribute it and/or modify it under the same
168       terms as Perl itself.
169
170       The full text of the license can be found in the LICENSE file included
171       with this module.
172