1Date::Manip::Holidays(3U)ser Contributed Perl DocumentatiDoante::Manip::Holidays(3)
2
3
4

NAME

6       Date::Manip::Holidays - describes holidays and events
7

SYNOPSIS

9       This describes the Holidays and Events sections of the config file, and
10       how they are used.
11
12       Holidays and events are specific days that are named. Holidays are used
13       in business mode calculations, events are not. Events may be used for
14       other calendaring operations.
15

HOLIDAYS

17       The holiday section of the config file is used to define holidays.
18       Each line is of the form:
19
20          STRING = HOLIDAY
21
22       HOLIDAY is the name of the holiday or it can be blank.
23
24       If HOLIDAY is blank, the holiday is unnamed, but still treated as a
25       holiday.  For example, in the US, the day after Thanksgiving is often a
26       work holiday though it is not named.
27
28       HOLIDAY should be unique in most cases.  The only exception is if the
29       holiday definition is complex enough that it is impossible to describe
30       it with one STRING.  In this case, multiple lines may be given with
31       different values of STRING but the same value for HOLIDAY, and in these
32       cases, the first STRING that matches a given year will be used.  This
33       situation is described in more detail below.
34
35       NOTE: It is not allowed to have unnamed holidays that require multiple
36       definitions, so a name will have to be assigned in that case.
37
38       STRING is a string which can be parsed to give a valid date. It can be
39       any of the following forms:
40
41       A full date
42           Specific holidays can be set which occur only a single time.
43
44              May 5, 2000                     = A one-time-only holiday
45
46           Any format parseable by "Date::Manip::Date::parse_date" can be
47           used.
48
49           There is one caveat to using a full date.  Date::Manip assumes that
50           most holidays will appear once per year, so if you were to
51           explicitly defined New Years (observed) as:
52
53              2004-12-31                      = New Year's Day
54
55           then it would assume that it had found the occurrence of New Year's
56           for 2004 when in fact, this is the 2005 occurrence.
57
58           Full date specifications should only be used as a last resort, and
59           probably only if you will explicitly specify all occurrence of the
60           holiday.
61
62       A date without a year
63           Some holidays occur every year on the same day. These can be
64           defined using the simple lines:
65
66              Jan 1                           = New Year's Day
67              Jul 4th                         = Independence Day
68              fourth Thu in Nov               = Thanksgiving
69
70           These dates must be written in a form which can be parsed as a full
71           date by simply adding the year to the end of the string. Please
72           refer to the Date::Manip::Date documentation to see what forms will
73           work. ISO 8601 dates will not work since the year comes first.
74
75           Any format parseable by "Date::Manip::Date::parse_date" which
76           allows the year to be at the end can be used.
77
78       Recurrence
79           The dates can be specified using recurrences:
80
81              1*0:0:0:0:0:0*EASTER            = Easter
82              1*11:0:11:0:0:0*DWD             = Veteran's Day
83              1*11:4:4:0:0:0                  = Thanksgiving
84              1*11:4:4:0:0:0*FD1              = Day after Thanksgiving
85
86           In cases where you are interested in business type calculations,
87           you'll want to define most holidays using recurrences, since they
88           can define when a holiday is celebrated in the financial world.
89           For example, Christmas might be defined as:
90
91              Dec 25               = Christmas
92
93           but if it falls on a weekend, there won't be a business holiday
94           associated with it. It could be defined using a recurrence:
95
96              1*12:0:24:0:0:0*DWD  = Christmas
97
98           so that if Christmas falls on a weekend, a holiday will be taken on
99           the Friday before or the Monday after the weekend.
100
101           You can use the fully specified format of a recurrence:
102
103             1*2:0:1:0:0:0***Jan 1 1999*Dec 31 2002 = Feb 2 from 1999-2002
104

OTHER HOLIDAY CONSIDERATIONS

106       Recurrences which change years
107           It is now valid to have a recurrence defined for New Year's day
108           which pushes the holiday to the previous year.
109
110           For example, the most useful definition of New Year's day is:
111
112              1*1:0:1:0:0:0*DWD               = New Year's Day
113
114           which means to choose the closest working day to observe the
115           holiday, even though this might mean that the holiday is observed
116           on the previous year.
117
118       Order of definitions is preserved
119           The order of the definitions is preserved. In other words, when
120           looking at the holidays for a year, previously defined holidays (in
121           the order given in the config file) are correctly handled.
122
123           As an example, if you wanted to define both Christmas and Boxing
124           days (Boxing is the day after Christmas, and is celebrated in some
125           parts of the world), and you wanted to celebrate Christmas on a
126           business day on or after Dec 25, and Boxing day as the following
127           work day, you could do it in one of the following ways:
128
129              1*12:0:25:0:0:0*NWD  = Christmas
130              1*12:0:26:0:0:0*NWD  = Boxing
131
132           or
133
134              1*12:0:25:0:0:0*NWD  = Christmas
135              1*12:0:25:0:0:0*NWD  = Boxing
136
137           Holidays go into affect the minute they are parsed which is why the
138           second example works (though for clarity, the first one is
139           preferable).  The first recurrence defined the first business day
140           on or after Dec 25 as Christmas.  The second one then defines the
141           business day after that as Boxing day.  Since the definitions are
142           stored as a list (NOT a hash as they were in Date::Manip 5.xx),
143           using the same recurrence twice does not cause a problem.
144
145       Multiple holidays
146           Having multiple holidays on a single day is allowed. As an example,
147           you may want to look at New Years day as both the observed and
148           actual holidays, so you might have:
149
150              1*1:0:1:0:0:0*DWD               = New Year's Day (observed)
151              Jan 1                           = New Year's Day
152
153           Most of the time, both will fall on the same day, but sometimes
154           they may differ.  In this example, it is important that the
155           observed holiday be listed first.  Otherwise, Jan 1 will be marked
156           as a holiday and then the observed date will check Jan 1, but where
157           it is not a business day, it will move to another day (due to the
158           DWD modifier).
159
160           Likewise, the two holidays:
161
162              3rd Sunday in June              = Father's Day
163              Jun 17                          = Bunker Hill Day
164
165           sometimes fall on the same day.  Using the
166           "Date::Manip::Date::list_holidays" method (or the "Date_IsHoliday"
167           function), you can get a list of all names that the date contains.
168
169       Complex holiday descriptions
170           Occasionally, you cannot describe a holiday using a single line.
171           For example, the US Federal Reserve banks use a complex holiday
172           description where:
173
174              For holidays falling on Saturday, Federal Reserve Banks
175              and Branches will be open the preceding Friday. For holidays
176              falling on Sunday, all Federal Reserve Banks and Branches
177              will be closed the following Monday.
178
179           Since Saturday is not a business day, the DWD modifier will not
180           work.  For these, you need a more complicated definition.
181
182           The following definitions both work:
183
184              # Saturday
185              1*1:0:1:0:0:0*NBD,BD1,IBD,FD1   = New Year's Day
186              # Sunday (observed Monday)
187              1*1:0:1:0:0:0*NBD,BD1,NBD,FD2   = New Year's Day
188              # M-F
189              1*1:0:1:0:0:0*IBD               = New Year's Day
190
191           and
192
193              # Saturday
194              1*1:0:1:0:0:0*IW6               = New Year's Day
195              # Sunday (observed Monday)
196              1*1:0:1:0:0:0*IW7,FD1           = New Year's Day
197              # M-F
198              1*1:0:1:0:0:0*IBD               = New Year's Day
199

EVENTS

201       The Events section of the config file is similar to the Holiday
202       section.  It is used to name certain days or times, but there are a few
203       important differences:
204
205       Events can be assigned to any time and duration
206           All holidays are exactly 1 day long.  They are assigned to a period
207           of time from midnight to midnight.
208
209           Events can be based at any time of the day, and may be of any
210           duration.
211
212       Events don't affect business mode calculations
213           Unlike holidays, events are completely ignored when doing business
214           mode calculations.
215
216       Whereas holidays were added with business mode math in mind, events
217       were added with calendar and scheduling applications in mind.
218
219       Every line in the events section is of the form:
220
221          EVENT = NAME
222
223       where NAME is the name of the event, and EVENT defines when it occurs
224       and its duration.  An EVENT can be defined in the following ways:
225
226          Date
227          YMD
228          YM
229          Recur
230
231          Date  ; Date
232          YMD   ; YMD
233          YM    ; YM
234          Date  ; Delta
235          Recur ; Delta
236
237       Date refers to a full date/time (and is any string that can be parsed
238       by "Date::Manip::Date::parse"). YMD is any string which can be parsed
239       by "Date::Manip::Date::parse_date". YM is any string which can be
240       parsed by the parse_date method to give a date in the current year.
241       Recur is a partial or fully specified recurrence. Delta is any string
242       that can be parsed to form a delta.
243
244       With the "Date" form, or the "Recur" form, the event starts at the time
245       (or times) specified by the date or recurrence, and last 1 hour long.
246       With the "YMD" and "YM" forms, the event occurs on the given day, and
247       lasts all day.
248
249       With all of the two part forms ("Date;Date", "YM;YM", etc.), the event
250       starts at the first date and goes to the second date, or goes an amount
251       of time specified by the delta.
252
253       The "YMD;YMD" and "YM;YM" forms means that the event lasts from the
254       start of the first date to the end of the second. In the Date;Date
255       form, the event goes from the first date to the second date inclusive.
256       In other words, both dates are in the event. In the "Date;Delta" and
257       "Recur;Delta" forms, the Delta tells the length of the event. Also, in
258       the Date;Date form, the second date may NOT be expressed as a delta.
259
260       Currently, having an event longer than 1 year is NOT supported, but no
261       checking is done for this.
262

KNOWN BUGS

264       None known.
265

BUGS AND QUESTIONS

267       Please refer to the Date::Manip::Problems documentation for information
268       on submitting bug reports or questions to the author.
269

SEE ALSO

271       Date::Manip        - main module documentation
272

LICENSE

274       This script is free software; you can redistribute it and/or modify it
275       under the same terms as Perl itself.
276

AUTHOR

278       Sullivan Beck (sbeck@cpan.org)
279
280
281
282perl v5.32.0                      2020-12-15          Date::Manip::Holidays(3)
Impressum