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

AUTHOR

233       Flavio Soibelmann Glock fglock@pucrs.br
234

CREDITS

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

COPYRIGHT

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