|
Packit |
95306a |
# Copyright (c) 1995-2017 Sullivan Beck. All rights reserved.
|
|
Packit |
95306a |
# This program is free software; you can redistribute it and/or modify it
|
|
Packit |
95306a |
# under the same terms as Perl itself.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=pod
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 NAME
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Date::Manip::Holidays - describes holidays and events
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 SYNOPSIS
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This describes the Holidays and Events sections of the config file,
|
|
Packit |
95306a |
and how they are used.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Holidays and events are specific days that are named. Holidays are
|
|
Packit |
95306a |
used in business mode calculations, events are not. Events may be used
|
|
Packit |
95306a |
for other calendaring operations.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 HOLIDAYS
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The holiday section of the config file is used to define holidays. Each
|
|
Packit |
95306a |
line is of the form:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
STRING = HOLIDAY
|
|
Packit |
95306a |
|
|
Packit |
95306a |
HOLIDAY is the name of the holiday or it can be blank.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If HOLIDAY is blank, the holiday is unnamed, but still treated as a
|
|
Packit |
95306a |
holiday. For example, in the US, the day after Thanksgiving is often
|
|
Packit |
95306a |
a work holiday though it is not named.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
HOLIDAY should be unique in most cases. The only exception is if the
|
|
Packit |
95306a |
holiday definition is complex enough that it is impossible to describe
|
|
Packit |
95306a |
it with one STRING. In this case, multiple lines may be given with
|
|
Packit |
95306a |
different values of STRING but the same value for HOLIDAY, and in these
|
|
Packit |
95306a |
cases, the first STRING that matches a given year will be used. This
|
|
Packit |
95306a |
situation is described in more detail below.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
NOTE: It is not allowed to have unnamed holidays that require multiple
|
|
Packit |
95306a |
definitions, so a name will have to be assigned in that case.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
STRING is a string which can be parsed to give a valid date. It can be any
|
|
Packit |
95306a |
of the following forms:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=over 4
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Specific holidays can be set which occur only a single time.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
May 5, 2000 = A one-time-only holiday
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Any format parseable by C<Date::Manip::Date::parse_date> can be used.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
There is one caveat to using a full date. Date::Manip assumes that
|
|
Packit |
95306a |
most holidays will appear once per year, so if you were to explicitly
|
|
Packit |
95306a |
defined New Years (observed) as:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
2004-12-31 = New Year's Day
|
|
Packit |
95306a |
|
|
Packit |
95306a |
then it would assume that it had found the occurrence of New Year's for
|
|
Packit |
95306a |
2004 when in fact, this is the 2005 occurrence.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Full date specifications should only be used as a last resort, and
|
|
Packit |
95306a |
probably only if you will explicitly specify all occurrence of the
|
|
Packit |
95306a |
holiday.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Some holidays occur every year on the same day. These can be defined
|
|
Packit |
95306a |
using the simple lines:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Jan 1 = New Year's Day
|
|
Packit |
95306a |
Jul 4th = Independence Day
|
|
Packit |
95306a |
fourth Thu in Nov = Thanksgiving
|
|
Packit |
95306a |
|
|
Packit |
95306a |
These dates must be written in a form which can be parsed as a full
|
|
Packit |
95306a |
date by simply adding the year to the end of the string. Please refer
|
|
Packit |
95306a |
to the L<Date::Manip::Date> documentation to see what forms will
|
|
Packit |
95306a |
work. ISO 8601 dates will not work since the year comes first.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Any format parseable by C<Date::Manip::Date::parse_date> which allows the
|
|
Packit |
95306a |
year to be at the end can be used.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Recurrence>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The dates can be specified using recurrences:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
1*0:0:0:0:0:0*EASTER = Easter
|
|
Packit |
95306a |
1*11:0:11:0:0:0*DWD = Veteran's Day
|
|
Packit |
95306a |
1*11:4:5:0:0:0 = Thanksgiving
|
|
Packit |
95306a |
1*11:4:5:0:0:0*FD1 = Day after Thanksgiving
|
|
Packit |
95306a |
|
|
Packit |
95306a |
In cases where you are interested in business type calculations, you'll
|
|
Packit |
95306a |
want to define most holidays using recurrences, since they can define
|
|
Packit |
95306a |
when a holiday is celebrated in the financial world. For example,
|
|
Packit |
95306a |
Christmas might be defined as:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Dec 25 = Christmas
|
|
Packit |
95306a |
|
|
Packit |
95306a |
but if it falls on a weekend, there won't be a business holiday
|
|
Packit |
95306a |
associated with it. It could be defined using a recurrence:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
1*12:0:24:0:0:0*DWD = Christmas
|
|
Packit |
95306a |
|
|
Packit |
95306a |
so that if Christmas falls on a weekend, a holiday will be taken
|
|
Packit |
95306a |
on the Friday before or the Monday after the weekend.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
You can use the fully specified format of a recurrence:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
1*2:0:1:0:0:0***Jan 1 1999*Dec 31 2002 = Feb 2 from 1999-2002
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=back
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 OTHER HOLIDAY CONSIDERATIONS
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=over 4
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Recurrences which change years>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
It is now valid to have a recurrence defined for New Year's day which
|
|
Packit |
95306a |
pushes the holiday to the previous year.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
For example, the most useful definition of New Year's day is:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
1*1:0:1:0:0:0*DWD = New Year's Day
|
|
Packit |
95306a |
|
|
Packit |
95306a |
which means to choose the closest working day to observe the
|
|
Packit |
95306a |
holiday, even though this might mean that the holiday is observed
|
|
Packit |
95306a |
on the previous year.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Order of definitions is preserved>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The order of the definitions is preserved. In other words, when looking
|
|
Packit |
95306a |
at the holidays for a year, previously defined holidays (in the order
|
|
Packit |
95306a |
given in the config file) are correctly handled.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
As an example, if you wanted to define both Christmas and Boxing days
|
|
Packit |
95306a |
(Boxing is the day after Christmas, and is celebrated in some parts of
|
|
Packit |
95306a |
the world), and you wanted to celebrate Christmas on a business day on
|
|
Packit |
95306a |
or after Dec 25, and Boxing day as the following work day, you could do
|
|
Packit |
95306a |
it in one of the following ways:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
1*12:0:25:0:0:0*NWD = Christmas
|
|
Packit |
95306a |
1*12:0:26:0:0:0*NWD = Boxing
|
|
Packit |
95306a |
|
|
Packit |
95306a |
or
|
|
Packit |
95306a |
|
|
Packit |
95306a |
1*12:0:25:0:0:0*NWD = Christmas
|
|
Packit |
95306a |
1*12:0:25:0:0:0*NWD = Boxing
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Holidays go into affect the minute they are parsed which is why the
|
|
Packit |
95306a |
second example works (though for clarity, the first one is
|
|
Packit |
95306a |
preferable). The first recurrence defined the first business day on
|
|
Packit |
95306a |
or after Dec 25 as Christmas. The second one then defines the
|
|
Packit |
95306a |
business day after that as Boxing day. Since the definitions are
|
|
Packit |
95306a |
stored as a list (NOT a hash as they were in Date::Manip 5.xx), using
|
|
Packit |
95306a |
the same recurrence twice does not cause a problem.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Multiple holidays>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Having multiple holidays on a single day is allowed. As an example,
|
|
Packit |
95306a |
you may want to look at New Years day as both the observed and actual
|
|
Packit |
95306a |
holidays, so you might have:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
1*1:0:1:0:0:0*DWD = New Year's Day (observed)
|
|
Packit |
95306a |
Jan 1 = New Year's Day
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Most of the time, both will fall on the same day, but sometimes
|
|
Packit |
95306a |
they may differ. In this example, it is important that the
|
|
Packit |
95306a |
observed holiday be listed first. Otherwise, Jan 1 will be
|
|
Packit |
95306a |
marked as a holiday and then the observed date will check Jan 1,
|
|
Packit |
95306a |
but where it is not a business day, it will move to another day
|
|
Packit |
95306a |
(due to the DWD modifier).
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Likewise, the two holidays:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
3rd Sunday in June = Father's Day
|
|
Packit |
95306a |
Jun 17 = Bunker Hill Day
|
|
Packit |
95306a |
|
|
Packit |
95306a |
sometimes fall on the same day. Using the
|
|
Packit |
95306a |
C<Date::Manip::Date::list_holidays> method (or the C<Date_IsHoliday>
|
|
Packit |
95306a |
function), you can get a list of all names that the date contains.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Complex holiday descriptions>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Occasionally, you cannot describe a holiday using a single line. For
|
|
Packit |
95306a |
example, the US Federal Reserve banks use a complex holiday description
|
|
Packit |
95306a |
where:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
For holidays falling on Saturday, Federal Reserve Banks
|
|
Packit |
95306a |
and Branches will be open the preceding Friday. For holidays
|
|
Packit |
95306a |
falling on Sunday, all Federal Reserve Banks and Branches
|
|
Packit |
95306a |
will be closed the following Monday.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Since Saturday is not a business day, the DWD modifier will not work.
|
|
Packit |
95306a |
For these, you need a more complicated definition.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The following definitions both work:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
# Saturday
|
|
Packit |
95306a |
1*1:0:1:0:0:0*NBD,BD1,IBD,FD1 = New Year's Day
|
|
Packit |
95306a |
# Sunday (observed Monday)
|
|
Packit |
95306a |
1*1:0:1:0:0:0*NBD,BD1,NBD,FD2 = New Year's Day
|
|
Packit |
95306a |
# M-F
|
|
Packit |
95306a |
1*1:0:1:0:0:0*IBD = New Year's Day
|
|
Packit |
95306a |
|
|
Packit |
95306a |
and
|
|
Packit |
95306a |
|
|
Packit |
95306a |
# Saturday
|
|
Packit |
95306a |
1*1:0:1:0:0:0*IW6 = New Year's Day
|
|
Packit |
95306a |
# Sunday (observed Monday)
|
|
Packit |
95306a |
1*1:0:1:0:0:0*IW7,FD1 = New Year's Day
|
|
Packit |
95306a |
# M-F
|
|
Packit |
95306a |
1*1:0:1:0:0:0*IBD = New Year's Day
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=back
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 EVENTS
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The Events section of the config file is similar to the Holiday section.
|
|
Packit |
95306a |
It is used to name certain days or times, but there are a few important
|
|
Packit |
95306a |
differences:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=over 4
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Events can be assigned to any time and duration>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
All holidays are exactly 1 day long. They are assigned to a period
|
|
Packit |
95306a |
of time from midnight to midnight.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Events can be based at any time of the day, and may be of any duration.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Events don't affect business mode calculations>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Unlike holidays, events are completely ignored when doing business
|
|
Packit |
95306a |
mode calculations.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=back
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Whereas holidays were added with business mode math in mind, events
|
|
Packit |
95306a |
were added with calendar and scheduling applications in mind.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Every line in the events section is of the form:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
EVENT = NAME
|
|
Packit |
95306a |
|
|
Packit |
95306a |
where NAME is the name of the event, and EVENT defines when it occurs
|
|
Packit |
95306a |
and its duration. An EVENT can be defined in the following ways:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Date
|
|
Packit |
95306a |
YMD
|
|
Packit |
95306a |
YM
|
|
Packit |
95306a |
Recur
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Date ; Date
|
|
Packit |
95306a |
YMD ; YMD
|
|
Packit |
95306a |
YM ; YM
|
|
Packit |
95306a |
Date ; Delta
|
|
Packit |
95306a |
Recur ; Delta
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Date refers to a full date/time (and is any string that can be parsed
|
|
Packit |
95306a |
by C<Date::Manip::Date::parse>). YMD is any string which can be parsed by
|
|
Packit |
95306a |
C<Date::Manip::Date::parse_date>. YM is any string which can be parsed by
|
|
Packit |
95306a |
the parse_date method to give a date in the current year. Recur is a
|
|
Packit |
95306a |
partial or fully specified recurrence. Delta is any string that can be
|
|
Packit |
95306a |
parsed to form a delta.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
With the "Date" form, or the "Recur" form, the event starts at the
|
|
Packit |
95306a |
time (or times) specified by the date or recurrence, and last 1 hour
|
|
Packit |
95306a |
long. With the "YMD" and "YM" forms, the event occurs on the given
|
|
Packit |
95306a |
day, and lasts all day.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
With all of the two part forms ("Date;Date", "YM;YM", etc.), the event
|
|
Packit |
95306a |
starts at the first date and goes to the second date, or goes an
|
|
Packit |
95306a |
amount of time specified by the delta.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The "YMD;YMD" and "YM;YM" forms means that the event lasts from the
|
|
Packit |
95306a |
start of the first date to the end of the second. In the Date;Date
|
|
Packit |
95306a |
form, the event goes from the first date to the second date
|
|
Packit |
95306a |
inclusive. In other words, both dates are in the event. In the
|
|
Packit |
95306a |
"Date;Delta" and "Recur;Delta" forms, the Delta tells the length of
|
|
Packit |
95306a |
the event. Also, in the Date;Date form, the second date may NOT be
|
|
Packit |
95306a |
expressed as a delta.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Currently, having an event longer than 1 year is NOT supported, but no
|
|
Packit |
95306a |
checking is done for this.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 KNOWN BUGS
|
|
Packit |
95306a |
|
|
Packit |
95306a |
None known.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 BUGS AND QUESTIONS
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Please refer to the L<Date::Manip::Problems> documentation for
|
|
Packit |
95306a |
information on submitting bug reports or questions to the author.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 SEE ALSO
|
|
Packit |
95306a |
|
|
Packit |
95306a |
L<Date::Manip> - main module documentation
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 LICENSE
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This script is free software; you can redistribute it and/or
|
|
Packit |
95306a |
modify it under the same terms as Perl itself.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 AUTHOR
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Sullivan Beck (sbeck@cpan.org)
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=cut
|