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 full week of every month, on tuesday
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 week of every year, on tuesday
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 full week of every month, on monday
149           my $set = DateTime::Event::Recurrence->monthly( weeks => 2 );
150
151           # second tuesday of every month
152           my $set = DateTime::Event::Recurrence->monthly( weeks => 2, days => "tu", week_start_day => "1tu" );
153
154   The "interval" and "start" Parameters
155       The "interval" parameter represents how often the recurrence rule
156       repeats.
157
158       The optional "start" parameter specifies where to start counting:
159
160           my $dt_start = DateTime->new( year => 2003, month => 6, day => 15 );
161
162           my $set = DateTime::Event::Recurrence->daily
163                         ( interval => 11,
164                           hours    => 10,
165                           minutes  => 30,
166                           start    => $dt_start,
167                         );
168
169       This specifies a recurrence that happens at 10:30 on the day specified
170       by "start => $dt", and then every 11 days before and after $dt.  So we
171       get a set like this:
172
173           ...
174           2003-06-04T10:30:00,
175           2003-06-15T10:30:00,
176           2003-06-26T10:30:00,
177           ...
178
179       In this case, the method is used to specify the unit, so "daily()"
180       means that our unit is a day, and "interval => 11" specifies the
181       quantity of our unit.
182
183       The "start" parameter should have no time zone.
184
185   The "week_start_day" Parameter
186       The "week_start_day" represents how the 'first week' of a period is
187       calculated:
188
189       "mo", "tu", "we", "th", "fr", "sa", "su" - The first week is one that
190       starts on this week-day, and has the most days in this period.  Works
191       for "weekly" and "yearly" recurrences.
192
193       "1mo", "1tu", "1we", "1th", "1fr", "1sa", "1su" - The first week is one
194       that starts on this week-day, and has all days in this period.  This
195       works for "weekly()", "monthly()" and "yearly()" recurrences.
196
197       The "week_start_day" defaults to "1mo", except in yearly ("yearly()")
198       recurrences which default to "mo".
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@gmail.com
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