DateTime::Event::Recurrence(3pm)

1DateTime::Event::RecurrUesnecre(C3o)ntributed Perl DocumDeantteaTtiimoen::Event::Recurrence(3)
2
3
4

NAME

6       DateTime::Event::Recurrence - DateTime::Set extension for create basic
7       recurrence sets
8

SYNOPSIS

10        use DateTime;
11        use DateTime::Event::Recurrence;
12
13        my $dt = DateTime->new( year   => 2000,
14                                month  => 6,
15                                day    => 20,
16                              );
17
18        my $daily_set = DateTime::Event::Recurrence->daily;
19
20        my $dt_next = $daily_set->next( $dt );
21
22        my $dt_previous = $daily_set->previous( $dt );
23
24        my $bool = $daily_set->contains( $dt );
25
26        my @days = $daily_set->as_list( start => $dt1, end => $dt2 );
27
28        my $iter = $daily_set->iterator;
29
30        while ( my $dt = $iter->next ) {
31            print ' ', $dt->datetime;
32        }
33

DESCRIPTION

35       This module provides convenience methods that let you easily create
36       "DateTime::Set" objects for various recurrences, such as "once a month"
37       or "every day".  You can also create more complicated recurrences, such
38       as "every Monday, Wednesday and Thursday at 10:00 AM and 2:00 PM".
39

USAGE

41       * yearly monthly weekly daily hourly minutely secondly
42           These methods all return a new "DateTime::Set" object representing
43           the given recurrence.
44
45             my $daily_set = DateTime::Event::Recurrence->daily;
46
47           If no parameters are given, then the set members each occur at the
48           beginning of the specified recurrence.
49
50           For example, by default, the "monthly()" method returns a set con‐
51           taining the first day of each month.
52
53           Without parameters, the "weekly()" method returns a set containing
54           Mondays.
55
56           However, you can pass in parameters to alter where these datetimes
57           fall.  The parameters are the same as those given to the "Date‐
58           Time::Duration" constructor for specifying the length of a dura‐
59           tion.  For example, to create a set representing a daily recurrence
60           at 10:30 each day, we write this:
61
62             my $daily_at_10_30_set =
63                 DateTime::Event::Recurrence->daily( hours => 10, minutes => 30 );
64
65           To represent every Tuesday (second day of the week):
66
67             my $weekly_on_tuesday_set =
68                 DateTime::Event::Recurrence->weekly( days => 2 );
69
70           A negative duration counts backwards from the end of the period.
71           This is done in the same manner as is specified in RFC 2445 (iCal).
72
73           Negative durations are useful for creating recurrences such as the
74           last day of each month:
75
76             my $last_day_of_month_set =
77                 DateTime::Event::Recurrence->monthly( days => -1 );
78
79           You can also provide multiple sets of duration arguments, such as
80           this:
81
82               my $set = DateTime::Event::Recurrence->daily
83                             ( hours =>   [ 10, 14,  -1 ],
84                               minutes => [ 15, 30, -15 ],
85                             );
86
87           This specifies a recurrence occurring every day at these 9 differ‐
88           ent times:
89
90             10:15,  10:30,  10:45,   # +10h         ( +15min / +30min / last 15min (-15) )
91             14:15,  14:30,  14:45,   # +14h         ( +15min / +30min / last 15min (-15) )
92             23:15,  23:30,  23:45,   # last 1h (-1) ( +15min / +30min / last 15min (-15) )
93
94           To create a set of recurrences occurring every thirty seconds, we
95           could do this:
96
97               my $every_30_seconds_set =
98                   DateTime::Event::Recurrence->minutely( seconds => [ 0, 30 ] );
99
100           The following is also valid. See the section on the "interval"
101           parameter:
102
103               my $every_30_seconds_set =
104                   DateTime::Event::Recurrence->secondly( interval => 30 );
105
106       Invalid DateTimes
107
108       Invalid values are skipped at run time.
109
110       For example, when days are added to a month, the result is checked for
111       a nonexisting day (such as 31 or 30), and the invalid datetimes are
112       skipped.
113
114       Another example of this would be creating a set via the "daily()"
115       method and specifying "hours => 25".
116
117       The "days" Parameter
118
119       The "days" parameter can be combined with yearly, monthly, and weekly
120       recurrences, resulting in six possible meanings:
121
122           # tuesday of every week
123           my $set = DateTime::Event::Recurrence->weekly( days => 2 );
124
125           # 10th day of every month
126           my $set = DateTime::Event::Recurrence->monthly( days => 10 );
127
128           # second tuesday of every month
129           my $set = DateTime::Event::Recurrence->monthly( weeks => 2, days => 2 );
130
131           # 10th day of every year
132           my $set = DateTime::Event::Recurrence->yearly( days => 10 );
133
134           # 10th day of every december
135           my $set = DateTime::Event::Recurrence->yearly( months => 12, days => 10 );
136
137           # second tuesday of every year
138           my $set = DateTime::Event::Recurrence->yearly( weeks => 2, days => 2 );
139
140       Week days can also be called by name, as is specified in RFC 2445
141       (iCal):
142
143         my $weekly_on_tuesday_set =
144             DateTime::Event::Recurrence->weekly( days => 'tu' );
145
146       The "days" parameter defaults to "the first day".  See also the section
147       on the "week start day" parameter.
148
149           # second monday of every month
150           my $set = DateTime::Event::Recurrence->monthly( weeks => 2 );
151
152       The "interval" and "start" Parameters
153
154       The "interval" parameter represents how often the recurrence rule
155       repeats.
156
157       The optional "start" parameter specifies where to start counting:
158
159           my $dt_start = DateTime->new( year => 2003, month => 6, day => 15 );
160
161           my $set = DateTime::Event::Recurrence->daily
162                         ( interval => 11,
163                           hours    => 10,
164                           minutes  => 30,
165                           start    => $dt_start,
166                         );
167
168       This specifies a recurrence that happens at 10:30 on the day specified
169       by "start => $dt", and then every 11 days before and after $dt.  So we
170       get a set like this:
171
172           ...
173           2003-06-04T10:30:00,
174           2003-06-15T10:30:00,
175           2003-06-26T10:30:00,
176           ...
177
178       In this case, the method is used to specify the unit, so "daily()"
179       means that our unit is a day, and "interval => 11" specifies the quan‐
180       tity of our unit.
181
182       The "start" parameter should have no time zone.
183
184       The "week_start_day" Parameter
185
186       The "week_start_day" parameter is intended for internal use by the
187       "DateTime::Event::ICal" module, for generating RFC2445 recurrences.
188
189       The "week_start_day" represents how the 'first week' of a period is
190       calculated:
191
192       "mo" - this is the default.  The first week is one that starts in mon‐
193       day, and has the most days in this period.
194
195       "tu", "we", "th", "fr", "sa", "su" - The first week is one that starts
196       in this week-day, and has the most days in this period.  Works for
197       "weekly" and "yearly" recurrences.
198
199       "1tu", "1we", "1th", "1fr", "1sa", "1su" - The first week is one that
200       starts in this week-day, and has all days in this period.  This works
201       for "weekly()", "monthly()" and "yearly()" recurrences.
202
203       Time Zones
204
205       Recurrences are created in the 'floating' time zone, as specified in
206       the "DateTime" module.
207
208       If you want to specify a time zone for a recurrence, you can do this by
209       calling "set_time_zone()" on the returned set:
210
211         my $daily = DateTime::Event::Recurrence->daily;
212         $daily->set_time_zone( 'Europe/Berlin' );
213
214       You can also pass a "DateTime.pm" object with a time zone to the set's
215       "next()" and "previous()" methods:
216
217         my $dt = DateTime->today( time_zone => 'Europe/Berlin' );
218         my $next = $daily->next($dt);
219
220       A recurrence can be affected DST changes, so it would be possible to
221       specify a recurrence that creates nonexistent datetimes.  Because
222       "DateTime.pm" throws an exception if asked to create a non-existent
223       datetime, please be careful when setting a time zone for your recur‐
224       rence.
225
226       It might be preferable to always use "UTC" for your sets, and then con‐
227       vert the returned object to the desired time zone.
228
229       Leap Seconds
230
231       There are no leap seconds, because the recurrences are created in the
232       'floating' time zone.
233
234       The value 60 for seconds (the leap second) is ignored.  If you really
235       want the leap second, then specify the second as "-1".
236

AUTHOR

238       Flavio Soibelmann Glock fglock@pucrs.br
239

CREDITS

241       The API was developed with help from the people in the date‐
242       time@perl.org list.
243
244       Special thanks to Dave Rolsky, Ron Hill and Matt Sisk for being around
245       with ideas.
246
247       If you can understand what this module does by reading the docs, you
248       should thank Dave Rolsky.  If you can't understand it, yell at him.  He
249       also helped removing weird idioms from the code.
250
251       Jerrad Pierce came with the idea to move "interval" from Date‐
252       Time::Event::ICal to here.
253

COPYRIGHT

255       Copyright (c) 2003 Flavio Soibelmann Glock.  All rights reserved.  This
256       program is free software; you can redistribute it and/or modify it
257       under the same terms as Perl itself.
258
259       The full text of the license can be found in the LICENSE file included
260       with this module.
261