Blame lib/Date/Manip/Holidays.pod

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