Data::ICal::DateTime(3pm)

1Data::ICal::DateTime(3)User Contributed Perl DocumentatioDnata::ICal::DateTime(3)
2
3
4

NAME

6       Data::ICal::DateTime - convenience methods for using Data::ICal with
7       DateTime
8

SYNPOSIS

10           # performs mixin voodoo
11           use Data::ICal::DateTime;
12           my $cal = Data::ICal->new( filename => 'example.ics');
13
14
15           my $date1 = DateTime->new( year => 2005, month => 7, day => 01 );
16           my $date2 = DateTime->new( year => 2005, month => 7, day => 07 );
17           my $span  = DateTime::Span->from_datetimes( start => $date1, end => $date2 );
18
19           my @events = $cal->events();           # all VEVENTS
20           my @week   = $cal->events($span);      # just in that week
21           my @week   = $cal->events($span,'day');# explode long events into days
22
23           my $event = Data::ICal::Entry::Event->new();
24
25           $event->start($start);                 # $start is a DateTime object
26           $event->end($end);                     # so is $end
27
28           $event->all_day                        # is this an all day event
29
30           $event->duration($duration);           # $duration is DateTime::Duration
31           $event->recurrence($recurrence);       # $reccurence is a DateTime list,
32                                                  # a DateTime::Span list,
33                                                  # a DateTime::Set,
34                                                  # or a DateTime::SpanSet
35
36           $event->start;                         # returns a DateTime object
37           $event->end;                           # ditto
38           $event->duration;                      # returns a DateTime::Duration
39           $event->recurrence;                    # returns a DateTime::Set
40           $event->period;                        # returns a DateTime::Span object
41           $event->rdate;                         # returns a DateTime::Set
42           $event->exrule;                        # returns a DateTime::Set
43           $event->exdate;                        # returns a DateTime::Set
44           $event->explode($span);                # returns an array of sub events
45                                                  # (if this is recurring);
46           $event->explode($span,'week');         # if any events are longer than a
47                                                  # week then split them up
48           $event->is_in($span);                  # whether this event falls within a
49                                                  # Set, Span, or SetSpan
50
51
52           $cal->add_entry($event);
53
54       methods
55

DESCRIPTION

METHODS

58   events [span] [period]
59       Provides a Data::ICal object with a method to return all events.
60
61       If a DateTime::Set, DateTime::Span or DateTime::SpanSet object is
62       passed then only the events that occur within that set will be returned
63       including expansion of all recurring events. All events will be
64       normalised to have a dtstart and dtend rather than any other method of
65       determining their start and stop time.
66
67       Additionally you can pass a period string which can be one of the
68       following
69
70           year month week day hour minute second
71
72       This will explode an event into as many sub events as needed e.g a
73       period of 'day' will explode a 2-day event into 2 one day events with
74       the second starting just after the first
75
76   collapse <events>
77       Provides a Data::ICal object with a method to collapse
78       "recurrence-id"s.
79
80       Given a list of events, some of which might have "recurrence-id"s,
81       return a list of events with all recurrences within "span" and all
82       "recurrence-id"s handled correctly.
83
84       Used internally by "events".
85
86   start [new]
87       Returns a DateTime object representing the start time of this event.
88
89       May return undef.
90
91       If passed a DateTime object will set that to be the new start time.
92
93   end
94       Returns a DateTime object representing the end time of this event.
95
96       May return undef.
97
98       If passed a DateTime object will set that to be the new end time.
99
100   all_day
101       Returns 1 if event is all day or 0 if not.
102
103       If no end has been set and 1 is passed then will set end to be a
104       nanosecond before midnight the next day.
105
106       The have multi-day all-day events simply set the end time to be
107       nanosecond before midnight on the last day of the event.
108
109   floating
110       An event is considered floating if it has a start but no end. It is
111       intended to represent an event that is associated with a given calendar
112       date and time of day, such as an anniversary and should not be
113       considered as taking up any amount of time.
114
115       Returns 1 if the evnt is floating and 0 if it isn't.
116
117       If passed a 1 then will set the event to be floating by deleting the
118       end time.
119
120       If passed a 0 and no end is currently set then it will set end to be a
121       nanosecond before midnight the next day.
122
123   duration
124       Returns a DateTime::Duration object representing the duration of this
125       event.
126
127       May return undef.
128
129       If passed a DateTime::Duration object will set that to be the new
130       duration.
131
132   period
133       Returns a DateTime::Span object representing the period of this event.
134
135       May return undef.
136
137       If passed a DateTime::Span object will set that to be the new period.
138
139   recurrence
140       Returns a DateTime::Set object representing the union of all the
141       "RRULE"s in this object.
142
143       May return undef.
144
145       If passed one or more DateTime lists, DateTime::Span lists,
146       DateTime::Sets, or DateTime::SpanSets then set the recurrence rules to
147       be those.
148
149   rdate
150       Returns a DateTime::Set object representing the set of all "RDATE"s in
151       the object.
152
153       May return undef.
154
155   exrule
156       Returns a DateTime::Set object representing the union of all the
157       "EXRULE"s in this object.
158
159       May return undef.
160
161       If passed one or more DateTime lists, DateTime::Span lists,
162       DateTime::Sets, or DateTime::SpanSets then set the recurrence exclusion
163       rules to be those.
164
165   exdate
166       Returns a DateTime::Set object representing the set of all "RDATE"s in
167       the object.
168
169       May return undef.
170
171   recurrence_id
172       Returns a DateTime object representing the recurrence-id of this event.
173
174       May return undef.
175
176       If passed a DateTime object will set that to be the new recurrence-id.
177
178   uid
179       Returns the uid of this event.
180
181       If passed a new value then sets that to be the new uid value.
182
183   summary
184       Returns a string representing the summary of this event.
185
186       May return undef.
187
188       If passed a new value then sets that to be the new summary (and will
189       escape all relevant characters).
190
191   description
192       Returns a string representing the description of this event.
193
194       May return undef.
195
196       If passed a new value then sets that to be the new description (and
197       will escape all relevant characters).
198
199   url
200       Returns a string representing the url of this event.
201
202       May return undef.
203
204       If passed a new value then sets that to be the new description (and
205       will escape all relevant characters).
206
207   explode <span> [period]
208       Takes DateTime::Set, DateTime::Span or DateTime::SpanSet and returns an
209       array of events.
210
211       If this is not a recurring event, and it falls with the span, then it
212       will return one event with the dtstart and dtend properties set and no
213       other time information.
214
215       If this is a recurring event then it will return all times that this
216       recurs within the span. All returned events will have the dtstart and
217       dtend properties set and no other time information.
218
219       If "period" is optionally passed then events longer than "period" will
220       be exploded into multiple events.
221
222       "period" can be any of the following
223
224           year month week day hour minute second
225
226   original <event>
227       Store or fetch a reference to the original event this was derived from.
228
229   split_up <period>
230       Split an n-period event into n 1-period events.
231
232   is_in <span>
233       Takes DateTime::Set, DateTime::Span or DateTime::SpanSet and returns
234       whether this event can fall within that time frame.
235

AUTHOR

237       Simon Wistow <simon@thegestalt.org>
238

COPYING

240       Copyright, 2005 Simon Wistow
241
242       Distributed under the same terms as Perl itself.
243

BUGS

245       Potential timezone problems?
246