1Date::Manip::Holidays(3U)ser Contributed Perl DocumentatiDoante::Manip::Holidays(3)
2
6 Date::Manip::Holidays - describes holidays and events
7
9 This describes the Holidays and Events sections of the config file, and
10 how they are used.
11 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
17 The holiday section of the config file is used to define holidays.
18 Each line is of the form:
19 STRING = HOLIDAY
21 HOLIDAY is the name of the holiday (or it can be blank in which case
23 the day will still be treated as a holiday... for example the day after
24 Thanksgiving is often a work holiday though it is not named).
25 STRING is a string which can be parsed to give a valid date. It can be
27 any of the following forms:
28 A full date
30 Specific holidays can be set which occur only a single time.
31 May 5, 2000 = A one-time-only holiday
33 Any format parseable by Date::Manip::Date::parse_date can be used.
35 A date without a year
37 Some holidays occur every year on the same day. These can be
38 defined using the simple lines:
39 Jan 1 = New Year's Day
41 Jul 4th = Independence Day
42 fourth Thu in Nov = Thanksgiving
43 These dates must be written in a form which can be parsed as a full
45 date by simply adding the year to the end of the string. Please
46 refer to the Date::Manip::Date documentation to see what forms will
47 work. ISO 8601 dates will not work since the year comes first.
48 Any format parseable by Date::Manip::Date::parse_date can be used.
50 Recurrence
52 The dates can be specified using recurrences:
53 1*0:0:0:0:0:0*EASTER = Easter
55 1*11:0:11:0:0:0*DWD = Veteran's Day
56 In cases where you are interested in business type calculations,
58 you'll want to define most holidays using recurrences, since they
59 can define when a holiday is celebrated in the financial world.
60 For example, Christmas might be defined as:
61 Dec 25 = Christmas
63 but if it falls on a weekend, there won't be a business holiday
65 associated with it. It could be defined using a recurrence:
66 1*12:0:24:0:0:0*DWD = Christmas
68 so that if Christmas falls on a weekend, a holiday will be taken on
70 the Friday before or the Monday after the weekend.
71 You can use the fully specified format of a recurrence:
73 1*2:0:1:0:0:0***Jan 1 1999*Dec 31 2002 = Feb 2 from 1999-2002
75
77 Recurrences which change years
78 It is now valid to have a recurrence defined for New Year's day
79 which pushes the holiday to the previous year.
80 For example, the most useful definition of New Year's day is:
82 1*1:0:1:0:0:0*DWD = New Year's Day
84 which means to choose the closest working day to observe the
86 holiday, even though this might mean that the holiday is observed
87 on the previous year.
88 Order of definitions is preserved
90 The order of the definitions is preserved. In other words, when
91 looking at the holidays for a year, previously defined holidays (in
92 the order given in the config file) are correctly handled.
93 As an example, if you wanted to define both Christmas and Boxing
95 days (Boxing is the day after Christmas, and is celebrated in some
96 parts of the world), and you wanted to celebrate Christmas on a
97 business day on or after Dec 25, and Boxing day as the following
98 work day, you could do it in one of the following ways:
99 1*12:0:25:0:0:0*NWD = Christmas
101 1*12:0:26:0:0:0*NWD = Boxing
102 or
104 1*12:0:25:0:0:0*NWD = Christmas
106 1*12:0:25:0:0:0*NWD = Boxing
107 Holidays go into affect the minute they are parsed which is why the
109 second example works (though for clarity, the first one is
110 preferable). The first recurrence defined the first business day
111 on or after Dec 25 as Christmas. The second one then defines the
112 business day after that as Boxing day. Since the definitions are
113 stored as a list (NOT a hash as they were in Date::Manip 5.xx),
114 using the same recurrence twice does not cause a problem.
115 Multiple holidays
117 Having multiple holidays on a single day is allowed. As an example,
118 you may want to look at New Years day as both the observed and
119 actual holidays, so you might have:
120 1*1:0:1:0:0:0*DWD = New Year's Day (observed)
122 Jan 1 = New Year's Day
123 Most of the time, both will fall on the same day, but sometimes
125 they may differ. In this example, it is important that the
126 observed holiday be listed first. Otherwise, Jan 1 will be marked
127 as a holiday and then the observed date will check Jan 1, but where
128 it is not a business day, it will move to another day (due to the
129 DWD modifier).
130 Likewise, the two holidays:
132 3rd Sunday in June = Father's Day
134 Jun 17 = Bunker Hill Day
135 sometimes fall on the same day. Using the
137 Date::Manip::Date::list_holidays method (or the Date_IsHoliday
138 function), you can get a list of all names that the date contains.
139
141 The Events section of the config file is similar to the Holiday
142 section. It is used to name certain days or times, but there are a few
143 important differences:
144 Events can be assigned to any time and duration
146 All holidays are exactly 1 day long. They are assigned to a period
147 of time from midnight to midnight.
148 Events can be based at any time of the day, and may be of any
150 duration.
151 Events don't affect business mode calculations
153 Unlike holidays, events are completely ignored when doing business
154 mode calculations.
155 Whereas holidays were added with business mode math in mind, events
157 were added with calendar and scheduling applications in mind.
158 Every line in the events section is of the form:
160 EVENT = NAME
162 where NAME is the name of the event, and EVENT defines when it occurs
164 and its duration. An EVENT can be defined in the following ways:
165 Date
167 YMD
168 YM
169 Recur
170 Date ; Date
172 YMD ; YMD
173 YM ; YM
174 Date ; Delta
175 Recur ; Delta
176 Date refers to a full date/time (and is any string that can be parsed
178 by Date::Manip::Date::parse). YMD is any string which can be parsed by
179 Date::Manip::Date::parse_date. YM is any string which can be parsed by
180 the parse_date method to give a date in the current year. Recur is a
181 partial or fully specified recurrence. Delta is any string that can be
182 parsed to form a delta.
183 With the "Date" form, or the "Recur" form, the event starts at the time
185 (or times) specified by the date or recurrence, and last 1 hour long.
186 With the "YMD" and "YM" forms, the event occurs on the given day, and
187 lasts all day.
188 With all of the two part forms ("Date;Date", "YM;YM", etc.), the event
190 starts at the first date and goes to the second date, or goes an amount
191 of time specified by the delta.
192 The "YMD;YMD" and "YM;YM" forms means that the event lasts from the
194 start of the first date to the end of the second. In the Date;Date
195 form, the event goes from the first date to the second date inclusive.
196 In other words, both dates are in the event. In the "Date;Delta" and
197 "Recur;Delta" forms, the Delta tells the length of the event. Also, in
198 the Date;Date form, the second date may NOT be expressed as a delta.
199 Currently, having an event longer than 1 year is NOT supported, but no
201 checking is done for this.
202
204 None known.
205
207 Please refer to the Date::Manip::Problems documentation for information
208 on submitting bug reports or questions to the author.
209
211 Date::Manip - main module documentation
212
214 This script is free software; you can redistribute it and/or modify it
215 under the same terms as Perl itself.
216
218 Sullivan Beck (sbeck@cpan.org)
219perl v5.16.3 2014-06-09 Date::Manip::Holidays(3)