NAME¶
Date::Manip::Holidays - describes holidays and events
SYNOPSIS¶
This describes the Holidays and Events sections of the config file, and how they
are used.
Holidays and events are specific days that are named. Holidays are used in
business mode calculations, events are not. Events may be used for other
calendaring operations.
HOLIDAYS¶
The holiday section of the config file is used to define holidays. Each line is
of the form:
STRING = HOLIDAY
HOLIDAY is the name of the holiday (or it can be blank in which case the day
will still be treated as a holiday... for example the day after Thanksgiving
is often a work holiday though it is not named).
STRING is a string which can be parsed to give a valid date. It can be any of
the following forms:
- A full date
- Specific holidays can be set which occur only a single
time.
May 5, 2000 = A one-time-only holiday
Any format parseable by Date::Manip::Date::parse_date can be used.
- A date without a year
- Some holidays occur every year on the same day. These can
be defined using the simple lines:
Jan 1 = New Year's Day
Jul 4th = Independence Day
fourth Thu in Nov = Thanksgiving
These dates must be written in a form which can be parsed as a full date by
simply adding the year to the end of the string. Please refer to the
Date::Manip::Date documentation to see what forms will work. ISO 8601
dates will not work since the year comes first.
Any format parseable by Date::Manip::Date::parse_date can be used.
- Recurrence
- The dates can be specified using recurrences:
1*0:0:0:0:0:0*EASTER = Easter
1*11:0:11:0:0:0*DWD = Veteran's Day
In cases where you are interested in business type calculations, you'll want
to define most holidays using recurrences, since they can define when a
holiday is celebrated in the financial world. For example, Christmas might
be defined as:
Dec 25 = Christmas
but if it falls on a weekend, there won't be a business holiday associated
with it. It could be defined using a recurrence:
1*12:0:24:0:0:0*DWD = Christmas
so that if Christmas falls on a weekend, a holiday will be taken on the
Friday before or the Monday after the weekend.
You can use the fully specified format of a recurrence:
1*2:0:1:0:0:0***Jan 1 1999*Dec 31 2002 = Feb 2 from 1999-2002
OTHER HOLIDAY CONSIDERATIONS¶
- Recurrences which change years
- It is now valid to have a recurrence defined for New Year's
day which pushes the holiday to the previous year.
For example, the most useful definition of New Year's day is:
1*1:0:1:0:0:0*DWD = New Year's Day
which means to choose the closest working day to observe the holiday, even
though this might mean that the holiday is observed on the previous
year.
- Order of definitions is preserved
- The order of the definitions is preserved. In other words,
when looking at the holidays for a year, previously defined holidays (in
the order given in the config file) are correctly handled.
As an example, if you wanted to define both Christmas and Boxing days
(Boxing is the day after Christmas, and is celebrated in some parts of the
world), and you wanted to celebrate Christmas on a business day on or
after Dec 25, and Boxing day as the following work day, you could do it in
one of the following ways:
1*12:0:25:0:0:0*NWD = Christmas
1*12:0:26:0:0:0*NWD = Boxing
or
1*12:0:25:0:0:0*NWD = Christmas
1*12:0:25:0:0:0*NWD = Boxing
Holidays go into affect the minute they are parsed which is why the second
example works (though for clarity, the first one is preferable). The first
recurrence defined the first business day on or after Dec 25 as Christmas.
The second one then defines the business day after that as Boxing day.
Since the definitions are stored as a list (NOT a hash as they were in
Date::Manip 5.xx), using the same recurrence twice does not cause a
problem.
- Multiple holidays
- Having multiple holidays on a single day is allowed. As an
example, you may want to look at New Years day as both the observed and
actual holidays, so you might have:
1*1:0:1:0:0:0*DWD = New Year's Day (observed)
Jan 1 = New Year's Day
Most of the time, both will fall on the same day, but sometimes they may
differ. In this example, it is important that the observed holiday be
listed first. Otherwise, Jan 1 will be marked as a holiday and then the
observed date will check Jan 1, but where it is not a business day, it
will move to another day (due to the DWD modifier).
Likewise, the two holidays:
3rd Sunday in June = Father's Day
Jun 17 = Bunker Hill Day
sometimes fall on the same day. Using the Date::Manip::Date::list_holidays
method (or the Date_IsHoliday function), you can get a list of all names
that the date contains.
EVENTS¶
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:
- 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.
- Events don't affect business mode calculations
- Unlike holidays, events are completely ignored when doing
business mode calculations.
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
YMD
YM
Recur
Date ; Date
YMD ; YMD
YM ; YM
Date ; Delta
Recur ; Delta
Date refers to a full date/time (and is any string that can be parsed by
Date::Manip::Date::parse). YMD is any string which can be parsed by
Date::Manip::Date::parse_date. YM is any string which can be parsed by the
parse_date method to give a date in the current year. Recur is a partial or
fully specified recurrence. Delta is any string that can be parsed to form a
delta.
With the "Date" form, or the "Recur" form, the event starts
at the time (or times) specified by the date or recurrence, and last 1 hour
long. With the "YMD" and "YM" forms, the event occurs on
the given day, and lasts all day.
With all of the two part forms ("Date;Date", "YM;YM", etc.),
the event starts at the first date and goes to the second date, or goes an
amount of time specified by the delta.
The "YMD;YMD" and "YM;YM" forms means that the event lasts
from the start of the first date to the end of the second. In the Date;Date
form, the event goes from the first date to the second date inclusive. In
other words, both dates are in the event. In the "Date;Delta" and
"Recur;Delta" forms, the Delta tells the length of the event. Also,
in the Date;Date form, the second date may NOT be expressed as a delta.
Currently, having an event longer than 1 year is NOT supported, but no checking
is done for this.
KNOWN BUGS¶
None known.
BUGS AND QUESTIONS¶
Please refer to the Date::Manip::Problems documentation for information on
submitting bug reports or questions to the author.
SEE ALSO¶
Date::Manip - main module documentation
LICENSE¶
This script is free software; you can redistribute it and/or modify it under the
same terms as Perl itself.
AUTHOR¶
Sullivan Beck (sbeck@cpan.org)