view release on metacpan or  search on metacpan

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

include "the first of every month", "every other day", "the 4th
Thursday of each month at 2:00 PM", and "every 2 hours and 30 minutes".

Second, it may require a base date to work from.  This piece of information
is not required for every type of recurrence.  For example, if the
frequency is "the first of every month", no base date is required.  All the
information about when the event occurs is included in the frequency
description.  If the frequency were "every other day" though, you need to
know at least one day on which the event occurred.

Third, the recurring event may have a range (a starting and ending date).

Fourth, there may be some flags included which modify the behavior of the
above information.

The fully specified recurrence is written as these 5 pieces of information
(both a start and end date) as an asterisk separated list:

  freq*flags*base*date0*date1

Here, base, date0, and date1 are any strings (which must not contain any
asterisks) which can be parsed by ParseDate.  flags is a comma separated
list of flags (described below), and freq is a string describing the
frequency of the recurring event.

The syntax of the frequency description is a colon separated list of the
format Y:M:W:D:H:MN:S (which stand for year, month, week, etc.).  One (and
only one) of the colons may optionally be replaced by an asterisk, or an
asterisk may be prepended to the string.  For example, the following are
all valid frequency descriptions:

  1:2:3:4:5:6:7
  1:2*3:4:5:6:7
 *1:2:3:4:5:6:7

But the following are NOT valid because they contain 2 or more asterisks:

  1:2*3:4:5*6:7
  1*2*3:4:5*6:7
 *1:2:3:4:5:6*7

If an asterisk is included, values to the left of it refer to the number of
times that time interval occurs between recurring events.  For example,
if the first part of the recurrence is:

  1:2*

this says that the recurring event occurs approximately every 1 year and 2
months.  I say approximately, because elements to the right of the asterisk,
as well as any flags included in the recurrence will affect when the actual
events occur.

If no asterisks are included, then the entire recurrence is of this form.
For example,

  0:0:0:1:12:0:0

refers to an event that occurs every 1 day, 12 hours.

Values that occur after an asterisk refer to a specific value for that type
of time element (i.e. exactly as it would appear on a calendar or a clock).
For example, if the recurrence ends with:

  *12:0:0

then the recurring event occurs at 12:00:00 (noon).

For example:

  0:0:2:1:0:0:0        every 2 weeks and 1 day
  0:0:0:0:5:30:0       every 5 hours and 30 minutes
  0:0:0:2*12:30:0      every 2 days at 12:30 (each day)

Values to the right of the asterisk can be listed a single values, ranges
(2 numbers separated by a dash "-"), or a comma separated list of values
or ranges.  In most cases, negative values are appropriate for the week
or day values. -1 stands for the last possible value, -2 for the second
to the last, etc.

Some examples are:

  0:0:0:1*2,4,6:0:0    every day at at 2:00, 4:00, and 6:00
  0:0:0:2*12-13:0,30:0 every other day at 12:00, 12:30, 13:00,
                       and 13:30
  0:1:0*-1:0:0:0       the last day of every month
  *1990-1995:12:0:1:0:0:0
                       Dec 1 in 1990 through 1995

There is no way to express the following with a single recurrence:

  every day at 12:30 and 1:00

You have to use two recurrences to do this.

When a non-zero day element occurs to the right of the asterisk, it can take
on multiple meanings, depending on the value of the month and week
elements.  It can refer to the day of the week, day of the month, or day of
the year.  Similarly, if a non-zero week element occurs to the right of
the asterisk, it actually refers to the nth time a certain day of the week
occurs, either in the month or in the year.

If the week element is non-zero and the day element is non-zero (and to the
right of the asterisk), the day element refers to the day of the week. It
can be any value from 1 to 7 (negative values -1 to -7 are also
allowed). If you use the ISO 8601 convention, the first day of the week is
Monday (though Date::Manip can use any day as the start of the week by
setting the FirstDay config variable).  So, assuming that you are using the
ISO 8601 convention, the following examples illustrate day-of-week
recurrences:

  0:1*4:2:0:0:0        4th Tuesday (day 2) of every month
  0:1*-1:2:0:0:0       last Tuesday of every month
  0:0:3*2:0:0:0        every 3rd Tuesday (every 3 weeks
                       on 2nd day of week)
  1:0*12:2:0:0:0       the 12th Tuesday of each year

If the week element is non-zero, and the day element is zero, the day
defaults to 1 (i.e. the first day of the week).

  0:1*2:0:0:0:0        the 2nd occurrence of FirstDay
                       in the year (typically Monday)

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

the minute the first line is parsed, Christmas is defined as a holiday.
The second line then steps forward 2 work days (skipping Christmas since
that's no longer a work day) and define the work day two days after
Christmas, NOT the day after Christmas.

An good alternative would appear to be:

   1*12:0:24:0:0:0*FW1  = Christmas
   1*12:0:24:0:0:0*FW1  = Boxing

This unfortunately fails because the recurrences are currently stored in a
hash.  Since these two recurrences are identical, they fail (the first one
is overwritten by the second and in essence, Christmas is never defined).

To fix this, make them unique with either a fake flag (which is ignored):

   1*12:0:24:0:0:0*FW1,a  = Boxing

or adding an innocuous 0 somewhere:

   01*12:0:24:0:0:0*FW1   = Boxing

The other good alternative would be to make two completely different
recurrences such as:

   1*12:0:24:0:0:0*FW1  = Christmas
   1*12:0:25:0:0:0*FW1  = Boxing

At times, you may want to switch back and forth between two holiday files.
This can be done by calling the following:

  Date_Init("EraseHolidays=1","PersonalCnf=FILE1");
  ...
  Date_Init("EraseHolidays=1","PersonalCnf=FILE2");
  ...

=head1 EVENTS SECTION

The Events section of the config file is similar to the Holiday section.
It is used to name certain days or times, but there are a few important
differences:

=over 4

=item B<Events can be assigned to any time and duration>

All holidays are exactly 1 day long.  They are assigned to a period
of time from midnight to midnight.

Events can be based at any time of the day, and may be of any duration.

=item B<Events don't affect business mode calculations>

Unlike holidays, events are completely ignored when doing business
mode calculations.

=back

Whereas holidays were added with business mode math in mind, events
were added with calendar and scheduling applications in mind.

Every line in the events section is of the form:

   EVENT = NAME

where NAME is the name of the event, and EVENT defines when it occurs
and its duration.  An EVENT can be defined in the following ways:

   Date
   Date*

   Date  ; Date
   Date  ; Delta

Here, Date* refers to a string containing a Date with NO TIME fields
(Jan 12, 1/1/2000, 2010-01-01) while Date does contain time fields.
Similarly, Recur* stands for a recurrence with the time fields all
equal to 0) while Recur stands for a recurrence with at least one
non-zero time field.

Both Date* and Recur* refer to an event very similar to a holiday which
goes from midnight to midnight.

Date and Recur refer to events which occur at the time given and with
a duration of 1 hour.

Events given by "Date ; Date", "Date ; Delta", and "Recur ; Delta"
contain both the starting date and either ending date or duration.

Events given as three elements "Date ; Delta ; Delta" or "Recur ; Delta ;
Delta" take a date and add both deltas to it to give the starting and
ending time of the event.  The order and sign of the deltas is
unimportant (and both can be the same sign to give a range of times
which does not contain the base date).

=head1 KNOWN PROBLEMS

The following are not bugs in Date::Manip, but they may give some people
problems.

=over 4

=item B<Unable to determine Time Zone>

Perhaps the most common problem occurs when you get the error:

   Error: Date::Manip unable to determine Time Zone.

Date::Manip tries hard to determine the local time zone, but on some
machines, it cannot do this (especially non-Unix systems).  To fix this,
just set the TZ variable, either at the top of the Manip.pm file, in the
DateManip.cnf file, or in a call to Date_Init.  I suggest using the form
"EST5EDT" so you don't have to change it every 6 months when going to or
from daylight saving time.

Windows NT does not seem to set the time zone by default.  From the
Perl-Win32-Users mailing list:

   > How do I get the TimeZone on my NT?
   >