NAME

DateTime::Event::Recurrence - Perl DateTime extension for computing basic recurrences.

SYNOPSIS

 use DateTime;
 use DateTime::Event::Recurrence;
 
 my $dt = DateTime->new( year   => 2000,
                         month  => 6,
                         day    => 20,
                       );

 my $daily_set = daily DateTime::Event::Recurrence;

 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 common recurrences, such as "monthly" or "daily".

USAGE

• yearly monthly weekly daily hourly minutely secondly

  These methods all return a DateTime::Set object representing the given recurrence.

    my $daily_set = daily DateTime::Event::Recurrence;

  If no parameters are given, then the set members occur at the beginning of each recurrence. For example, by default the monthly() method returns a set where each member is the first day of the month. Without parameters, the weekly() returns 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 can do:

    my $daily_at_10_30_set =
        daily DateTime::Event::Recurrence( hours => 10, minutes => 30 );

  To represent every Tuesday (second day of week):

    my $weekly_on_tuesday_set =
        weekly DateTime::Event::Recurrence( days => 2 );

  A negative duration counts backwards from the end of the period. This is the same as is specified in RFC 2445.

  This is useful for creating recurrences such as the last day of month:

    my $last_day_of_month_set =
        monthly DateTime::Event::Recurrence( days => -1 );

  When days are added to a month the result is checked for month overflow (such as nonexisting day 31 or 30), and the invalid datetimes are skipped.

  The behaviour when other duration overflows occur, such as when a duration is bigger than the period, is undefined and is version dependent. Invalid parameter values are usually skipped.

  Note that the 'hours' duration is affected by DST changes and might return unexpected results. In particular, it would be possible to specify a recurrence that creates nonexistent datetimes. This behaviour might change in future versions. Some possible alternatives are to use floating times, or to use negative hours since DST changes usually occur in the beginning of the day.

  The value 60 for seconds (the leap second) is ignored. If you i<really> want the leap second, then specify the second as -1.

  You can also provide multiple sets of duration arguments, such as this:

      my $set = daily DateTime::Event::Recurrence (
          hours =>   [ 10, 14,  -1 ],
          minutes => [ 30, 15, -15 ], );

  specifies a recurrence occuring everyday at these 9 different times:

    10:15,  10:30,  10:45,   # +10h ( +15min / +30min / last 15min )
    14:15,  14:30,  14:45,   # +14h ( +15min / +30min / last 15min )
    23:15,  23:30,  23:45,   # last 1h ( +15min / +30min / last 15min )

  To create a set of recurrences every thirty seconds, we could do this:

      my $every_30_seconds_set =
          minutely DateTime::Event::Recurrence ( seconds => [ 0, 30 ] );

Interval

The interval parameter represents how often the recurrence rule repeats:

    my $dt = DateTime->new( year => 2003, month => 6, day => 15 );

    my $set = daily DateTime::Event::Recurrence (
        interval => 11,
        hours =>    10,
        minutes =>  30,
        start =>    $dt );

specify a recurrence that happens at 10:30 at $dt day, and then at each 11 days, before and after $dt:

    ... 2003-06-04T10:30:00, 
        2003-06-15T10:30:00, 
        2003-06-26T10:30:00, ... 

Week start day

The week_start_day parameter is intended for internal use by the DateTime::Event::ICal module, for generating RFC2445 recurrences.

The week_start_day represents how the 'first week' of a period is calculated:

'mo' - this is the default. The first week is one that starts in monday, and has the most days in this period.

'tu', 'we', 'th', 'fr', 'sa', 'su' - The first week is one that starts in this week-day, and has the most days in this period. Works for weekly and yearly recurrences.

'1tu', '1we', '1th', '1fr', '1sa', '1su' - The first week is one that starts in this week-day, and has all days in this period. Works for weekly, monthly and yearly recurrences.

AUTHOR

Flavio Soibelmann Glock fglock@pucrs.br

CREDITS

The API was developmed 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. 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.

cpanm DateTime::Set::ICal

perl -MCPAN -e shell
install DateTime::Set::ICal