Provided by: libdatetime-event-recurrence-perl_0.19-1_all 
NAME
DateTime::Event::Recurrence - DateTime::Set extension for create basic recurrence sets
SYNOPSIS
use DateTime;
use DateTime::Event::Recurrence;
my $dt = DateTime->new( year => 2000,
month => 6,
day => 20,
);
my $daily_set = DateTime::Event::Recurrence->daily;
my $dt_next = $daily_set->next( $dt );
my $dt_previous = $daily_set->previous( $dt );
my $bool = $daily_set->contains( $dt );
my @days = $daily_set->as_list( start => $dt1, end => $dt2 );
my $iter = $daily_set->iterator;
while ( my $dt = $iter->next ) {
print ' ', $dt->datetime;
}
DESCRIPTION
This module provides convenience methods that let you easily create "DateTime::Set"
objects for various recurrences, such as "once a month" or "every day". You can also
create more complicated recurrences, such as "every Monday, Wednesday and Thursday at
10:00 AM and 2:00 PM".
USAGE
• yearly monthly weekly daily hourly minutely secondly
These methods all return a new "DateTime::Set" object representing the given
recurrence.
my $daily_set = DateTime::Event::Recurrence->daily;
If no parameters are given, then the set members each occur at the beginning of the
specified recurrence.
For example, by default, the "monthly()" method returns a set containing the first day
of each month.
Without parameters, the "weekly()" method returns a set containing Mondays.
However, you can pass in parameters to alter where these datetimes fall. The
parameters are the same as those given to the "DateTime::Duration" constructor for
specifying the length of a duration. For example, to create a set representing a
daily recurrence at 10:30 each day, we write this:
my $daily_at_10_30_set =
DateTime::Event::Recurrence->daily( hours => 10, minutes => 30 );
To represent every Tuesday (second day of the week):
my $weekly_on_tuesday_set =
DateTime::Event::Recurrence->weekly( days => 2 );
A negative duration counts backwards from the end of the period. This is done in the
same manner as is specified in RFC 2445 (iCal).
Negative durations are useful for creating recurrences such as the last day of each
month:
my $last_day_of_month_set =
DateTime::Event::Recurrence->monthly( days => -1 );
You can also provide multiple sets of duration arguments, such as this:
my $set = DateTime::Event::Recurrence->daily
( hours => [ 10, 14, -1 ],
minutes => [ 15, 30, -15 ],
);
This specifies a recurrence occurring every day at these 9 different times:
10:15, 10:30, 10:45, # +10h ( +15min / +30min / last 15min (-15) )
14:15, 14:30, 14:45, # +14h ( +15min / +30min / last 15min (-15) )
23:15, 23:30, 23:45, # last 1h (-1) ( +15min / +30min / last 15min (-15) )
To create a set of recurrences occurring every thirty seconds, we could do this:
my $every_30_seconds_set =
DateTime::Event::Recurrence->minutely( seconds => [ 0, 30 ] );
The following is also valid. See the section on the "interval" parameter:
my $every_30_seconds_set =
DateTime::Event::Recurrence->secondly( interval => 30 );
Invalid DateTimes
Invalid values are skipped at run time.
For example, when days are added to a month, the result is checked for a nonexisting day
(such as 31 or 30), and the invalid datetimes are skipped.
Another example of this would be creating a set via the "daily()" method and specifying
"hours => 25".
The "days" Parameter
The "days" parameter can be combined with yearly, monthly, and weekly recurrences,
resulting in six possible meanings:
# tuesday of every week
my $set = DateTime::Event::Recurrence->weekly( days => 2 );
# 10th day of every month
my $set = DateTime::Event::Recurrence->monthly( days => 10 );
# second full week of every month, on tuesday
my $set = DateTime::Event::Recurrence->monthly( weeks => 2, days => 2 );
# 10th day of every year
my $set = DateTime::Event::Recurrence->yearly( days => 10 );
# 10th day of every december
my $set = DateTime::Event::Recurrence->yearly( months => 12, days => 10 );
# second week of every year, on tuesday
my $set = DateTime::Event::Recurrence->yearly( weeks => 2, days => 2 );
Week days can also be called by name, as is specified in RFC 2445 (iCal):
my $weekly_on_tuesday_set =
DateTime::Event::Recurrence->weekly( days => 'tu' );
The "days" parameter defaults to "the first day". See also the section on the
"week_start_day" parameter.
# second full week of every month, on monday
my $set = DateTime::Event::Recurrence->monthly( weeks => 2 );
# second tuesday of every month
my $set = DateTime::Event::Recurrence->monthly( weeks => 2, days => "tu", week_start_day => "1tu" );
The "interval" and "start" Parameters
The "interval" parameter represents how often the recurrence rule repeats.
The optional "start" parameter specifies where to start counting:
my $dt_start = DateTime->new( year => 2003, month => 6, day => 15 );
my $set = DateTime::Event::Recurrence->daily
( interval => 11,
hours => 10,
minutes => 30,
start => $dt_start,
);
This specifies a recurrence that happens at 10:30 on the day specified by "start => $dt",
and then every 11 days before and after $dt. So we get a set like this:
...
2003-06-04T10:30:00,
2003-06-15T10:30:00,
2003-06-26T10:30:00,
...
In this case, the method is used to specify the unit, so "daily()" means that our unit is
a day, and "interval => 11" specifies the quantity of our unit.
The "start" parameter should have no time zone.
The "week_start_day" Parameter
The "week_start_day" represents how the 'first week' of a period is calculated:
"mo", "tu", "we", "th", "fr", "sa", "su" - The first week is one that starts on this week-
day, and has the most days in this period. Works for "weekly" and "yearly" recurrences.
"1mo", "1tu", "1we", "1th", "1fr", "1sa", "1su" - The first week is one that starts on
this week-day, and has all days in this period. This works for "weekly()", "monthly()"
and "yearly()" recurrences.
The "week_start_day" defaults to "1mo", except in yearly ("yearly()") recurrences which
default to "mo".
Time Zones
Recurrences are created in the 'floating' time zone, as specified in the "DateTime"
module.
If you want to specify a time zone for a recurrence, you can do this by calling
"set_time_zone()" on the returned set:
my $daily = DateTime::Event::Recurrence->daily;
$daily->set_time_zone( 'Europe/Berlin' );
You can also pass a "DateTime.pm" object with a time zone to the set's "next()" and
"previous()" methods:
my $dt = DateTime->today( time_zone => 'Europe/Berlin' );
my $next = $daily->next($dt);
A recurrence can be affected DST changes, so it would be possible to specify a recurrence
that creates nonexistent datetimes. Because "DateTime.pm" throws an exception if asked to
create a non-existent datetime, please be careful when setting a time zone for your
recurrence.
It might be preferable to always use "UTC" for your sets, and then convert the returned
object to the desired time zone.
Leap Seconds
There are no leap seconds, because the recurrences are created in the 'floating' time
zone.
The value 60 for seconds (the leap second) is ignored. If you really want the leap
second, then specify the second as "-1".
AUTHOR
Flavio Soibelmann Glock fglock@gmail.com
CREDITS
The API was developed with help from the people in the datetime@perl.org list.
Special thanks to Dave Rolsky, Ron Hill and Matt Sisk for being around with ideas.
If you can understand what this module does by reading the docs, you should thank Dave
Rolsky. If you can't understand it, yell at him. He also helped removing weird idioms
from the code.
Jerrad Pierce came with the idea to move "interval" from DateTime::Event::ICal to here.
COPYRIGHT
Copyright (c) 2003 Flavio Soibelmann Glock. All rights reserved. This program is free
software; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this module.
SEE ALSO
datetime@perl.org mailing list
DateTime Web page at http://datetime.perl.org/
DateTime - date and time :)
DateTime::Set - for recurrence-set accessors docs. You can use DateTime::Set to specify
recurrences using callback subroutines.
DateTime::Event::ICal - if you need more complex recurrences.
DateTime::SpanSet - sets of intervals, including recurring sets of intervals.