view release on metacpan or  search on metacpan

lib/Date/Manip/Recur.pod  view on Meta::CPAN

Unlike the B<nth> method which will return a specific event (or
undef if the Nth even is not defined), the next and prev methods
will only work with defined events.

So, for the recurrence:

   the 31st of every month

next might return the following sequence of events:

   Jan 31 2000
   Mar 31 2000
   May 31 2000

The rules for determining what event to return the first time one
of these is called are as follows:

1) If there is a range, next will return the first event that occurs
after the start of the range.  prev will return the last event that
occurs before the end of the range.

2) If there is no range, next will return the first event on or after
the base date.  prev will return the last event before the base date.

The error codes are the same as for the nth method.

=back

=head1 HISTORY OF THE FREQUENCY NOTATION

I realize that the frequency notation described above looks quite
complicated at first glance, but it is (IMO) the best notation for
expressing recurring events in existence. I actually consider it the
single most important contribution to date/time handling in
Date::Manip.

When I first decided to add recurring events to Date::Manip, I first
came up with a list of common ways of specifying recurring events, and
then went looking for a notation that could be used to define them.  I
was hoping for a notation that would be similar to cron notation, but
more powerful.

After looking in several specifications (including ISO 8601) and after
a discussion on a mailing list of calendar related topics, it appeared
that there was no concise, flexible notation for handling recurring
events that would handle all of the common forms I'd come up with.

So, as a matter of necessity, I set about inventing my own notation.
As I was looking at my list, it struck me that all of the parts which
specified a frequency were higher level (i.e. referred to a larger
unit of time) than those parts which specified a specific value (what
I've called the rtime). In other words, when the terms were laid out
from year down to seconds, the frequency part was always left of
specific values.

That led immediately to the notation described above, so I started analyzing
it to figure out if it could express all of the recurring events I'd
come up with. It succeeded on 100% of them. Not only that, but by playing
with different values (especially different combinations of m/w/d values), I
found that it would define recurring events that I hadn't even thought of,
but which seemed perfectly reasonable in hindsight.

After a very short period, I realized just how powerful this notation was,
and set about implementing it, and as I said above, of all the contributions
that Date::Manip has made, I consider this to be the most important.

=head1 KNOWN BUGS

If you specify a recurrence which cannot be satisfied for the base date,
or for any time after the base date, the recurrence will crash.  This
can only happen if you specify a recurrence that always occurs in the
spring DST transition using the current timezone rules.

For example, in a US timezone, the current timezone rules state that a
DST transition occurs at 02:00:00 on the 2nd Sunday in March and the
clock jumps to 03:00.  This started in 2006.  As a result, the recurrence

   1*3:2:7:2:0:0

with a base date of 2006 or later cannot be satisfied.

=head1 BUGS AND QUESTIONS

Please refer to the L<Date::Manip::Problems> documentation for
information on submitting bug reports or questions to the author.

=head1 SEE ALSO

L<Date::Manip>        - main module documentation

=head1 LICENSE

This script is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

=head1 AUTHOR

Sullivan Beck (sbeck@cpan.org)

=cut