.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Date::Manip::Holidays 3pm"
.TH Date::Manip::Holidays 3pm 2024-03-02 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Date::Manip::Holidays \- describes holidays and events
.SH SYNOPSIS
.IX Header "SYNOPSIS"
This describes the Holidays and Events sections of the config file,
and how they are used.
.PP
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.
.SH HOLIDAYS
.IX Header "HOLIDAYS"
The holiday section of the config file is used to define holidays.  Each
line is of the form:
.PP
.Vb 1
\&   STRING = HOLIDAY
.Ve
.PP
HOLIDAY is the name of the holiday or it can be blank.
.PP
If HOLIDAY is blank, the holiday is unnamed, but still treated as a
holiday.  For example, in the US, the day after Thanksgiving is often
a work holiday though it is not named.
.PP
HOLIDAY should be unique in most cases.  The only exception is if the
holiday definition is complex enough that it is impossible to describe
it with one STRING.  In this case, multiple lines may be given with
different values of STRING but the same value for HOLIDAY, and in these
cases, the first STRING that matches a given year will be used.  This
situation is described in more detail below.
.PP
NOTE: It is not allowed to have unnamed holidays that require multiple
definitions, so a name will have to be assigned in that case.
.PP
STRING is a string which can be parsed to give a valid date. It can be any
of the following forms:
.IP "\fBA full date\fR" 4
.IX Item "A full date"
Specific holidays can be set which occur only a single time.
.Sp
.Vb 1
\&   May 5, 2000                     = A one\-time\-only holiday
.Ve
.Sp
Any format parseable by \f(CW\*(C`Date::Manip::Date::parse_date\*(C'\fR can be used.
.Sp
There is one caveat to using a full date.  Date::Manip assumes that
most holidays will appear once per year, so if you were to explicitly
defined New Years (observed) as:
.Sp
.Vb 1
\&   2004\-12\-31                      = New Year\*(Aqs Day
.Ve
.Sp
then it would assume that it had found the occurrence of New Year's for
2004 when in fact, this is the 2005 occurrence.
.Sp
Full date specifications should only be used as a last resort, and
probably only if you will explicitly specify all occurrence of the
holiday.
.IP "\fBA date without a year\fR" 4
.IX Item "A date without a year"
Some holidays occur every year on the same day. These can be defined
using the simple lines:
.Sp
.Vb 3
\&   Jan 1                           = New Year\*(Aqs Day
\&   Jul 4th                         = Independence Day
\&   fourth Thu in Nov               = Thanksgiving
.Ve
.Sp
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.
.Sp
Any format parseable by \f(CW\*(C`Date::Manip::Date::parse_date\*(C'\fR which allows the
year to be at the end can be used.
.IP \fBRecurrence\fR 4
.IX Item "Recurrence"
The dates can be specified using recurrences:
.Sp
.Vb 4
\&   1*0:0:0:0:0:0*EASTER            = Easter
\&   1*11:0:11:0:0:0*DWD             = Veteran\*(Aqs Day
\&   1*11:4:4:0:0:0                  = Thanksgiving
\&   1*11:4:4:0:0:0*FD1              = Day after Thanksgiving
.Ve
.Sp
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:
.Sp
.Vb 1
\&   Dec 25               = Christmas
.Ve
.Sp
but if it falls on a weekend, there won't be a business holiday
associated with it. It could be defined using a recurrence:
.Sp
.Vb 1
\&   1*12:0:24:0:0:0*DWD  = Christmas
.Ve
.Sp
so that if Christmas falls on a weekend, a holiday will be taken
on the Friday before or the Monday after the weekend.
.Sp
You can use the fully specified format of a recurrence:
.Sp
.Vb 1
\&  1*2:0:1:0:0:0***Jan 1 1999*Dec 31 2002 = Feb 2 from 1999\-2002
.Ve
.SH "OTHER HOLIDAY CONSIDERATIONS"
.IX Header "OTHER HOLIDAY CONSIDERATIONS"
.IP "\fBRecurrences which change years\fR" 4
.IX Item "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.
.Sp
For example, the most useful definition of New Year's day is:
.Sp
.Vb 1
\&   1*1:0:1:0:0:0*DWD               = New Year\*(Aqs Day
.Ve
.Sp
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.
.IP "\fBOrder of definitions is preserved\fR" 4
.IX Item "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.
.Sp
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:
.Sp
.Vb 2
\&   1*12:0:25:0:0:0*NWD  = Christmas
\&   1*12:0:26:0:0:0*NWD  = Boxing
.Ve
.Sp
or
.Sp
.Vb 2
\&   1*12:0:25:0:0:0*NWD  = Christmas
\&   1*12:0:25:0:0:0*NWD  = Boxing
.Ve
.Sp
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.
.IP "\fBMultiple holidays\fR" 4
.IX Item "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:
.Sp
.Vb 2
\&   1*1:0:1:0:0:0*DWD               = New Year\*(Aqs Day (observed)
\&   Jan 1                           = New Year\*(Aqs Day
.Ve
.Sp
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).
.Sp
Likewise, the two holidays:
.Sp
.Vb 2
\&   3rd Sunday in June              = Father\*(Aqs Day
\&   Jun 17                          = Bunker Hill Day
.Ve
.Sp
sometimes fall on the same day.  Using the
\&\f(CW\*(C`Date::Manip::Date::list_holidays\*(C'\fR method (or the \f(CW\*(C`Date_IsHoliday\*(C'\fR
function), you can get a list of all names that the date contains.
.IP "\fBComplex holiday descriptions\fR" 4
.IX Item "Complex holiday descriptions"
Occasionally, you cannot describe a holiday using a single line.  For
example, the US Federal Reserve banks use a complex holiday description
where:
.Sp
.Vb 4
\&   For holidays falling on Saturday, Federal Reserve Banks
\&   and Branches will be open the preceding Friday. For holidays
\&   falling on Sunday, all Federal Reserve Banks and Branches
\&   will be closed the following Monday.
.Ve
.Sp
Since Saturday is not a business day, the DWD modifier will not work.
For these, you need a more complicated definition.
.Sp
The following definitions both work:
.Sp
.Vb 6
\&   # Saturday
\&   1*1:0:1:0:0:0*NBD,BD1,IBD,FD1   = New Year\*(Aqs Day
\&   # Sunday (observed Monday)
\&   1*1:0:1:0:0:0*NBD,BD1,NBD,FD2   = New Year\*(Aqs Day
\&   # M\-F
\&   1*1:0:1:0:0:0*IBD               = New Year\*(Aqs Day
.Ve
.Sp
and
.Sp
.Vb 6
\&   # Saturday
\&   1*1:0:1:0:0:0*IW6               = New Year\*(Aqs Day
\&   # Sunday (observed Monday)
\&   1*1:0:1:0:0:0*IW7,FD1           = New Year\*(Aqs Day
\&   # M\-F
\&   1*1:0:1:0:0:0*IBD               = New Year\*(Aqs Day
.Ve
.SH EVENTS
.IX Header "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:
.IP "\fBEvents can be assigned to any time and duration\fR" 4
.IX Item "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.
.Sp
Events can be based at any time of the day, and may be of any duration.
.IP "\fBEvents don't affect business mode calculations\fR" 4
.IX Item "Events don't affect business mode calculations"
Unlike holidays, events are completely ignored when doing business
mode calculations.
.PP
Whereas holidays were added with business mode math in mind, events
were added with calendar and scheduling applications in mind.
.PP
Every line in the events section is of the form:
.PP
.Vb 1
\&   EVENT = NAME
.Ve
.PP
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:
.PP
.Vb 4
\&   Date
\&   YMD
\&   YM
\&   Recur
\&
\&   Date  ; Date
\&   YMD   ; YMD
\&   YM    ; YM
\&   Date  ; Delta
\&   Recur ; Delta
.Ve
.PP
Date refers to a full date/time (and is any string that can be parsed
by \f(CW\*(C`Date::Manip::Date::parse\*(C'\fR). YMD is any string which can be parsed by
\&\f(CW\*(C`Date::Manip::Date::parse_date\*(C'\fR. 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.
.PP
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.
.PP
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.
.PP
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.
.PP
Currently, having an event longer than 1 year is NOT supported, but no
checking is done for this.
.SH "KNOWN BUGS"
.IX Header "KNOWN BUGS"
None known.
.SH "BUGS AND QUESTIONS"
.IX Header "BUGS AND QUESTIONS"
Please refer to the Date::Manip::Problems documentation for
information on submitting bug reports or questions to the author.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Date::Manip        \- main module documentation
.SH LICENSE
.IX Header "LICENSE"
This script is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.SH AUTHOR
.IX Header "AUTHOR"
Sullivan Beck (sbeck@cpan.org)