1DateTime::Format::ICal(U3s)er Contributed Perl DocumentatDiaotneTime::Format::ICal(3)
2
3
4
6 DateTime::Format::ICal - Parse and format iCal datetime and duration
7 strings
8
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
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
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
155 Support for this module is provided via the datetime@perl.org email
156 list. See http://lists.perl.org/ for more details.
157
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
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
174 datetime@perl.org mailing list
175
176 http://datetime.perl.org/
177
178
179
180perl v5.34.0 2022-01-21 DateTime::Format::ICal(3)