1# Copyright (c) 1995-2021 Sullivan Beck. All rights reserved. 2# This program is free software; you can redistribute it and/or modify it 3# under the same terms as Perl itself. 4 5=pod 6 7=head1 NAME 8 9Date::Manip::Holidays - describes holidays and events 10 11=head1 SYNOPSIS 12 13This describes the Holidays and Events sections of the config file, 14and how they are used. 15 16Holidays and events are specific days that are named. Holidays are 17used in business mode calculations, events are not. Events may be used 18for other calendaring operations. 19 20=head1 HOLIDAYS 21 22The holiday section of the config file is used to define holidays. Each 23line is of the form: 24 25 STRING = HOLIDAY 26 27HOLIDAY is the name of the holiday or it can be blank. 28 29If HOLIDAY is blank, the holiday is unnamed, but still treated as a 30holiday. For example, in the US, the day after Thanksgiving is often 31a work holiday though it is not named. 32 33HOLIDAY should be unique in most cases. The only exception is if the 34holiday definition is complex enough that it is impossible to describe 35it with one STRING. In this case, multiple lines may be given with 36different values of STRING but the same value for HOLIDAY, and in these 37cases, the first STRING that matches a given year will be used. This 38situation is described in more detail below. 39 40NOTE: It is not allowed to have unnamed holidays that require multiple 41definitions, so a name will have to be assigned in that case. 42 43STRING is a string which can be parsed to give a valid date. It can be any 44of the following forms: 45 46=over 4 47 48=item B<A full date> 49 50Specific holidays can be set which occur only a single time. 51 52 May 5, 2000 = A one-time-only holiday 53 54Any format parseable by C<Date::Manip::Date::parse_date> can be used. 55 56There is one caveat to using a full date. Date::Manip assumes that 57most holidays will appear once per year, so if you were to explicitly 58defined New Years (observed) as: 59 60 2004-12-31 = New Year's Day 61 62then it would assume that it had found the occurrence of New Year's for 632004 when in fact, this is the 2005 occurrence. 64 65Full date specifications should only be used as a last resort, and 66probably only if you will explicitly specify all occurrence of the 67holiday. 68 69=item B<A date without a year> 70 71Some holidays occur every year on the same day. These can be defined 72using the simple lines: 73 74 Jan 1 = New Year's Day 75 Jul 4th = Independence Day 76 fourth Thu in Nov = Thanksgiving 77 78These dates must be written in a form which can be parsed as a full 79date by simply adding the year to the end of the string. Please refer 80to the L<Date::Manip::Date> documentation to see what forms will 81work. ISO 8601 dates will not work since the year comes first. 82 83Any format parseable by C<Date::Manip::Date::parse_date> which allows the 84year to be at the end can be used. 85 86=item B<Recurrence> 87 88The dates can be specified using recurrences: 89 90 1*0:0:0:0:0:0*EASTER = Easter 91 1*11:0:11:0:0:0*DWD = Veteran's Day 92 1*11:4:4:0:0:0 = Thanksgiving 93 1*11:4:4:0:0:0*FD1 = Day after Thanksgiving 94 95In cases where you are interested in business type calculations, you'll 96want to define most holidays using recurrences, since they can define 97when a holiday is celebrated in the financial world. For example, 98Christmas might be defined as: 99 100 Dec 25 = Christmas 101 102but if it falls on a weekend, there won't be a business holiday 103associated with it. It could be defined using a recurrence: 104 105 1*12:0:24:0:0:0*DWD = Christmas 106 107so that if Christmas falls on a weekend, a holiday will be taken 108on the Friday before or the Monday after the weekend. 109 110You can use the fully specified format of a recurrence: 111 112 1*2:0:1:0:0:0***Jan 1 1999*Dec 31 2002 = Feb 2 from 1999-2002 113 114=back 115 116=head1 OTHER HOLIDAY CONSIDERATIONS 117 118=over 4 119 120=item B<Recurrences which change years> 121 122It is now valid to have a recurrence defined for New Year's day which 123pushes the holiday to the previous year. 124 125For example, the most useful definition of New Year's day is: 126 127 1*1:0:1:0:0:0*DWD = New Year's Day 128 129which means to choose the closest working day to observe the 130holiday, even though this might mean that the holiday is observed 131on the previous year. 132 133=item B<Order of definitions is preserved> 134 135The order of the definitions is preserved. In other words, when looking 136at the holidays for a year, previously defined holidays (in the order 137given in the config file) are correctly handled. 138 139As an example, if you wanted to define both Christmas and Boxing days 140(Boxing is the day after Christmas, and is celebrated in some parts of 141the world), and you wanted to celebrate Christmas on a business day on 142or after Dec 25, and Boxing day as the following work day, you could do 143it in one of the following ways: 144 145 1*12:0:25:0:0:0*NWD = Christmas 146 1*12:0:26:0:0:0*NWD = Boxing 147 148or 149 150 1*12:0:25:0:0:0*NWD = Christmas 151 1*12:0:25:0:0:0*NWD = Boxing 152 153Holidays go into affect the minute they are parsed which is why the 154second example works (though for clarity, the first one is 155preferable). The first recurrence defined the first business day on 156or after Dec 25 as Christmas. The second one then defines the 157business day after that as Boxing day. Since the definitions are 158stored as a list (NOT a hash as they were in Date::Manip 5.xx), using 159the same recurrence twice does not cause a problem. 160 161=item B<Multiple holidays> 162 163Having multiple holidays on a single day is allowed. As an example, 164you may want to look at New Years day as both the observed and actual 165holidays, so you might have: 166 167 1*1:0:1:0:0:0*DWD = New Year's Day (observed) 168 Jan 1 = New Year's Day 169 170Most of the time, both will fall on the same day, but sometimes 171they may differ. In this example, it is important that the 172observed holiday be listed first. Otherwise, Jan 1 will be 173marked as a holiday and then the observed date will check Jan 1, 174but where it is not a business day, it will move to another day 175(due to the DWD modifier). 176 177Likewise, the two holidays: 178 179 3rd Sunday in June = Father's Day 180 Jun 17 = Bunker Hill Day 181 182sometimes fall on the same day. Using the 183C<Date::Manip::Date::list_holidays> method (or the C<Date_IsHoliday> 184function), you can get a list of all names that the date contains. 185 186=item B<Complex holiday descriptions> 187 188Occasionally, you cannot describe a holiday using a single line. For 189example, the US Federal Reserve banks use a complex holiday description 190where: 191 192 For holidays falling on Saturday, Federal Reserve Banks 193 and Branches will be open the preceding Friday. For holidays 194 falling on Sunday, all Federal Reserve Banks and Branches 195 will be closed the following Monday. 196 197Since Saturday is not a business day, the DWD modifier will not work. 198For these, you need a more complicated definition. 199 200The following definitions both work: 201 202 # Saturday 203 1*1:0:1:0:0:0*NBD,BD1,IBD,FD1 = New Year's Day 204 # Sunday (observed Monday) 205 1*1:0:1:0:0:0*NBD,BD1,NBD,FD2 = New Year's Day 206 # M-F 207 1*1:0:1:0:0:0*IBD = New Year's Day 208 209and 210 211 # Saturday 212 1*1:0:1:0:0:0*IW6 = New Year's Day 213 # Sunday (observed Monday) 214 1*1:0:1:0:0:0*IW7,FD1 = New Year's Day 215 # M-F 216 1*1:0:1:0:0:0*IBD = New Year's Day 217 218=back 219 220=head1 EVENTS 221 222The Events section of the config file is similar to the Holiday section. 223It is used to name certain days or times, but there are a few important 224differences: 225 226=over 4 227 228=item B<Events can be assigned to any time and duration> 229 230All holidays are exactly 1 day long. They are assigned to a period 231of time from midnight to midnight. 232 233Events can be based at any time of the day, and may be of any duration. 234 235=item B<Events don't affect business mode calculations> 236 237Unlike holidays, events are completely ignored when doing business 238mode calculations. 239 240=back 241 242Whereas holidays were added with business mode math in mind, events 243were added with calendar and scheduling applications in mind. 244 245Every line in the events section is of the form: 246 247 EVENT = NAME 248 249where NAME is the name of the event, and EVENT defines when it occurs 250and its duration. An EVENT can be defined in the following ways: 251 252 Date 253 YMD 254 YM 255 Recur 256 257 Date ; Date 258 YMD ; YMD 259 YM ; YM 260 Date ; Delta 261 Recur ; Delta 262 263Date refers to a full date/time (and is any string that can be parsed 264by C<Date::Manip::Date::parse>). YMD is any string which can be parsed by 265C<Date::Manip::Date::parse_date>. YM is any string which can be parsed by 266the parse_date method to give a date in the current year. Recur is a 267partial or fully specified recurrence. Delta is any string that can be 268parsed to form a delta. 269 270With the "Date" form, or the "Recur" form, the event starts at the 271time (or times) specified by the date or recurrence, and last 1 hour 272long. With the "YMD" and "YM" forms, the event occurs on the given 273day, and lasts all day. 274 275With all of the two part forms ("Date;Date", "YM;YM", etc.), the event 276starts at the first date and goes to the second date, or goes an 277amount of time specified by the delta. 278 279The "YMD;YMD" and "YM;YM" forms means that the event lasts from the 280start of the first date to the end of the second. In the Date;Date 281form, the event goes from the first date to the second date 282inclusive. In other words, both dates are in the event. In the 283"Date;Delta" and "Recur;Delta" forms, the Delta tells the length of 284the event. Also, in the Date;Date form, the second date may NOT be 285expressed as a delta. 286 287Currently, having an event longer than 1 year is NOT supported, but no 288checking is done for this. 289 290=head1 KNOWN BUGS 291 292None known. 293 294=head1 BUGS AND QUESTIONS 295 296Please refer to the L<Date::Manip::Problems> documentation for 297information on submitting bug reports or questions to the author. 298 299=head1 SEE ALSO 300 301L<Date::Manip> - main module documentation 302 303=head1 LICENSE 304 305This script is free software; you can redistribute it and/or 306modify it under the same terms as Perl itself. 307 308=head1 AUTHOR 309 310Sullivan Beck (sbeck@cpan.org) 311 312=cut 313