Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | .\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13 |
2 | .\" | |
3 | .\" Standard preamble: | |
4 | .\" ======================================================================== | |
5 | .de Sh \" Subsection heading | |
6 | .br | |
7 | .if t .Sp | |
8 | .ne 5 | |
9 | .PP | |
10 | \fB\\$1\fR | |
11 | .PP | |
12 | .. | |
13 | .de Sp \" Vertical space (when we can't use .PP) | |
14 | .if t .sp .5v | |
15 | .if n .sp | |
16 | .. | |
17 | .de Vb \" Begin verbatim text | |
18 | .ft CW | |
19 | .nf | |
20 | .ne \\$1 | |
21 | .. | |
22 | .de Ve \" End verbatim text | |
23 | .ft R | |
24 | .fi | |
25 | .. | |
26 | .\" Set up some character translations and predefined strings. \*(-- will | |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a | |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to | |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' | |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. | |
32 | .tr \(*W-|\(bv\*(Tr | |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | |
34 | .ie n \{\ | |
35 | . ds -- \(*W- | |
36 | . ds PI pi | |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
39 | . ds L" "" | |
40 | . ds R" "" | |
41 | . ds C` "" | |
42 | . ds C' "" | |
43 | 'br\} | |
44 | .el\{\ | |
45 | . ds -- \|\(em\| | |
46 | . ds PI \(*p | |
47 | . ds L" `` | |
48 | . ds R" '' | |
49 | 'br\} | |
50 | .\" | |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for | |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the | |
54 | .\" output yourself in some meaningful fashion. | |
55 | .if \nF \{\ | |
56 | . de IX | |
57 | . tm Index:\\$1\t\\n%\t"\\$2" | |
58 | .. | |
59 | . nr % 0 | |
60 | . rr F | |
61 | .\} | |
62 | .\" | |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes | |
64 | .\" way too many mistakes in technical documents. | |
65 | .hy 0 | |
66 | .if n .na | |
67 | .\" | |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
70 | . \" fudge factors for nroff and troff | |
71 | .if n \{\ | |
72 | . ds #H 0 | |
73 | . ds #V .8m | |
74 | . ds #F .3m | |
75 | . ds #[ \f1 | |
76 | . ds #] \fP | |
77 | .\} | |
78 | .if t \{\ | |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | |
80 | . ds #V .6m | |
81 | . ds #F 0 | |
82 | . ds #[ \& | |
83 | . ds #] \& | |
84 | .\} | |
85 | . \" simple accents for nroff and troff | |
86 | .if n \{\ | |
87 | . ds ' \& | |
88 | . ds ` \& | |
89 | . ds ^ \& | |
90 | . ds , \& | |
91 | . ds ~ ~ | |
92 | . ds / | |
93 | .\} | |
94 | .if t \{\ | |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
101 | .\} | |
102 | . \" troff and (daisy-wheel) nroff accents | |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
110 | .ds ae a\h'-(\w'a'u*4/10)'e | |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
112 | . \" corrections for vroff | |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
115 | . \" for low resolution devices (crt and lpr) | |
116 | .if \n(.H>23 .if \n(.V>19 \ | |
117 | \{\ | |
118 | . ds : e | |
119 | . ds 8 ss | |
120 | . ds o a | |
121 | . ds d- d\h'-1'\(ga | |
122 | . ds D- D\h'-1'\(hy | |
123 | . ds th \o'bp' | |
124 | . ds Th \o'LP' | |
125 | . ds ae ae | |
126 | . ds Ae AE | |
127 | .\} | |
128 | .rm #[ #] #H #V #F C | |
129 | .\" ======================================================================== | |
130 | .\" | |
131 | .IX Title "PROFILES 1" | |
132 | .TH PROFILES 1 "2002-09-28" "perl v5.8.0" "User Contributed Perl Documentation" | |
133 | .SH "NAME" | |
134 | Date::Calendar::Profiles \- Some sample profiles for Date::Calendar | |
135 | and Date::Calendar::Year | |
136 | .SH "SYNOPSIS" | |
137 | .IX Header "SYNOPSIS" | |
138 | .Vb 2 | |
139 | \& use Date::Calendar::Profiles qw( $Profiles ); | |
140 | \& use Date::Calendar; | |
141 | .Ve | |
142 | .PP | |
143 | .Vb 2 | |
144 | \& $cal_US_AK = Date::Calendar->new( $Profiles->{'US-AK'} [,LANG] ); | |
145 | \& $cal_DE_BY = Date::Calendar->new( $Profiles->{'DE-BY'} [,LANG] ); | |
146 | .Ve | |
147 | .PP | |
148 | .Vb 1 | |
149 | \& or | |
150 | .Ve | |
151 | .PP | |
152 | .Vb 2 | |
153 | \& use Date::Calendar::Profiles qw( $Profiles ); | |
154 | \& use Date::Calendar::Year; | |
155 | .Ve | |
156 | .PP | |
157 | .Vb 2 | |
158 | \& $year_2000_US_FL = Date::Calendar::Year->new( 2000, $Profiles->{'US-FL'} [,LANG] ); | |
159 | \& $year_2001_DE_NW = Date::Calendar::Year->new( 2001, $Profiles->{'DE-NW'} [,LANG] ); | |
160 | .Ve | |
161 | .PP | |
162 | .Vb 1 | |
163 | \& and also | |
164 | .Ve | |
165 | .PP | |
166 | .Vb 13 | |
167 | \& use Date::Calendar::Profiles | |
168 | \& qw( | |
169 | \& &Previous_Friday | |
170 | \& &Next_Monday | |
171 | \& &Next_Monday_or_Tuesday | |
172 | \& &Nearest_Workday | |
173 | \& &Sunday_to_Monday | |
174 | \& &Advent1 | |
175 | \& &Advent2 | |
176 | \& &Advent3 | |
177 | \& &Advent4 | |
178 | \& &Advent | |
179 | \& ); | |
180 | .Ve | |
181 | .SH "PREFACE" | |
182 | .IX Header "PREFACE" | |
183 | This module provides some sample profiles (i.e., holiday schemes) | |
184 | for use with the \fIDate::Calendar\fR\|(3) and \fIDate::Calendar::Year\fR\|(3) | |
185 | module. | |
186 | .PP | |
187 | You are not required to use these, you can always roll your own | |
188 | (this is very easy). See the section \*(L"\s-1HOW\s0 \s-1TO\s0 \s-1ROLL\s0 \s-1YOUR\s0 \s-1OWN\s0\*(R" below | |
189 | for more instructions on how to do this, and take the profiles | |
190 | from this module as examples. | |
191 | .PP | |
192 | Please let me know of any errors in these profiles, and please | |
193 | send me your own profiles if you'd like to see them included in | |
194 | the next release of this module! Thank you! | |
195 | .PP | |
196 | (But please, only use the ISO\-Latin\-1 character set whenever | |
197 | possible, since my module doesn't support any other character | |
198 | sets yet, or at least tell me which character set you used | |
199 | so I can document this in this manual page. Thank you!) | |
200 | .SH "DESCRIPTION" | |
201 | .IX Header "DESCRIPTION" | |
202 | The method \*(L"\fIinit()\fR\*(R" in module \fIDate::Calendar::Year\fR\|(3) is | |
203 | responsible for parsing the calendar schemes contained | |
204 | here in the Date::Calendar::Profiles module. | |
205 | .PP | |
206 | This method offers a \*(L"mini\-language\*(R" which allows to | |
207 | specify common date formulas, like for instance a simple | |
208 | fixed date (in various different formats, e.g. american | |
209 | or european), or things like \*(L"the second Sunday of May\*(R" | |
210 | (Mother's Day), or \*(L"Easter Sunday minus 46 days\*(R" (Ash | |
211 | Wednesday), to cite just a few. | |
212 | .PP | |
213 | See the section \*(L"\s-1DATE\s0 \s-1FORMULA\s0 \s-1SYNTAX\s0\*(R" below for more | |
214 | details. | |
215 | .PP | |
216 | There are some more complicated formulas, however, which | |
217 | cannot be expressed in such simple terms. | |
218 | .PP | |
219 | The rule that if a holiday falls on a weekend, it will | |
220 | be substituted by either the adjacent Friday or Monday | |
221 | (whichever lies closer), is an example of this. | |
222 | .PP | |
223 | In order to be able to deal with such formulas, and in | |
224 | order to be as flexible as possible, the \*(L"\fIinit()\fR\*(R" method | |
225 | offers the possibility of using callback functions to | |
226 | deal with such dates and formulas. | |
227 | .PP | |
228 | See the section \*(L"\s-1CALLBACK\s0 \s-1INTERFACE\s0\*(R" below for more | |
229 | details on this topic. | |
230 | .PP | |
231 | In order to assist you with more common cases of odd | |
232 | formulas, the module Date::Calendar::Profiles exports | |
233 | the following utility subroutines (which are meant to | |
234 | be used as \*(L"filters\*(R" in callback functions of your own): | |
235 | .IP "\(bu" 2 | |
236 | \&\f(CW\*(C`($year,$month,$day[,ANYTHING]) = Previous_Friday($year,$month,$day[,ANYTHING]);\*(C'\fR | |
237 | .Sp | |
238 | If the given date falls on a Saturday or Sunday, this | |
239 | function changes the date to the adjacent Friday before | |
240 | that, and returns this new date. | |
241 | .Sp | |
242 | Otherwise the given date is returned unchanged. | |
243 | .Sp | |
244 | The rest of the input parameters, if any, are simply | |
245 | copied to the output. | |
246 | .IP "\(bu" 2 | |
247 | \&\f(CW\*(C`($year,$month,$day[,ANYTHING]) = Next_Monday($year,$month,$day[,ANYTHING]);\*(C'\fR | |
248 | .Sp | |
249 | If the given date falls on a Saturday or Sunday, this | |
250 | function changes the date to the adjacent Monday after | |
251 | that, and returns this new date. | |
252 | .Sp | |
253 | Otherwise the given date is returned unchanged. | |
254 | .Sp | |
255 | The rest of the input parameters, if any, are simply | |
256 | copied to the output. | |
257 | .IP "\(bu" 2 | |
258 | \&\f(CW\*(C`($year,$month,$day[,ANYTHING]) = Next_Monday_or_Tuesday($year,$month,$day[,ANYTHING]);\*(C'\fR | |
259 | .Sp | |
260 | If the given date falls on a Saturday, the date of the next | |
261 | Monday (after that weekend) is returned. | |
262 | .Sp | |
263 | If the given date falls on a Sunday, the date of the next | |
264 | Tuesday (after that weekend) is returned. | |
265 | .Sp | |
266 | If the given date falls on a Monday, the date of the next | |
267 | Tuesday (the day after the Monday) is returned. | |
268 | .Sp | |
269 | Otherwise the given date is returned unchanged. | |
270 | .Sp | |
271 | The rest of the input parameters, if any, are simply | |
272 | copied to the output. | |
273 | .Sp | |
274 | This function is used for the second of two adjacent | |
275 | holidays, where the first holiday obeys the \*(L"Next | |
276 | Monday\*(R" rule (see the description of the function | |
277 | immediately above). | |
278 | .Sp | |
279 | Examples of this are Christmas and Boxing Day, among | |
280 | others. | |
281 | .Sp | |
282 | When the first holiday falls on Friday, the second one | |
283 | falls on Saturday and is substituted by Monday. | |
284 | .Sp | |
285 | When the first holiday falls on a Saturday, the second | |
286 | one falls on Sunday, so the first holiday is substituted | |
287 | by Monday and the second one by Tuesday. | |
288 | .Sp | |
289 | When the first holiday falls on a Sunday, the second | |
290 | one falls on a Monday. Therefore the first holiday is | |
291 | substituted by Monday, and consequently the second | |
292 | holiday must be substituted by Tuesday. | |
293 | .Sp | |
294 | Or, in other terms: | |
295 | .Sp | |
296 | .Vb 3 | |
297 | \& Fri Sat => Fri Mon | |
298 | \& Sat Sun => Mon Tue | |
299 | \& Sun Mon => Mon Tue | |
300 | .Ve | |
301 | .Sp | |
302 | Note that there is no filter subroutine yet for the | |
303 | second of two adjacent holidays when the first holiday | |
304 | obeys the \*(L"Nearest Workday\*(R" rule (see the function | |
305 | described immediately below), i.e., | |
306 | .Sp | |
307 | .Vb 3 | |
308 | \& Fri Sat => Fri Mon | |
309 | \& Sat Sun => Fri Mon | |
310 | \& Sun Mon => Mon Tue | |
311 | .Ve | |
312 | .Sp | |
313 | This is left as an excercise to the inclined reader. \f(CW\*(C`:\-)\*(C'\fR | |
314 | .IP "\(bu" 2 | |
315 | \&\f(CW\*(C`($year,$month,$day[,ANYTHING]) = Nearest_Workday($year,$month,$day[,ANYTHING]);\*(C'\fR | |
316 | .Sp | |
317 | If the given date falls on a Saturday, this function | |
318 | returns the date of the Friday on the day before. | |
319 | .Sp | |
320 | If the given date falls on a Sunday, this function | |
321 | returns the date of the Monday on the day after. | |
322 | .Sp | |
323 | Otherwise the given date is returned unchanged. | |
324 | .Sp | |
325 | The rest of the input parameters, if any, are simply | |
326 | copied to the output. | |
327 | .IP "\(bu" 2 | |
328 | \&\f(CW\*(C`($year,$month,$day[,ANYTHING]) = Sunday_to_Monday($year,$month,$day[,ANYTHING]);\*(C'\fR | |
329 | .Sp | |
330 | If the given date falls on a Sunday, this function | |
331 | returns the date of the Monday on the day after. | |
332 | .Sp | |
333 | Otherwise the given date is returned unchanged. | |
334 | .Sp | |
335 | The rest of the input parameters, if any, are simply | |
336 | copied to the output. | |
337 | .PP | |
338 | The typical use of these filter subroutines is in a \*(L"return\*(R" | |
339 | statement at the end of callback functions of your own, when | |
340 | you already have calculated the holiday in question and only | |
341 | need to adjust it according to the rule implemented by the | |
342 | filter subroutine in question. | |
343 | .PP | |
344 | See also the implementation of the Date::Calendar::Profiles | |
345 | module for examples of how to use these functions. | |
346 | .SH "DATE FORMULA SYNTAX" | |
347 | .IX Header "DATE FORMULA SYNTAX" | |
348 | .Vb 1 | |
349 | \& - Fixed dates: | |
350 | .Ve | |
351 | .PP | |
352 | .Vb 2 | |
353 | \& "Christmas" => "24.12", # European format (day, month) | |
354 | \& "Christmas" => "24.12.", | |
355 | .Ve | |
356 | .PP | |
357 | .Vb 4 | |
358 | \& "Christmas" => "24Dec", | |
359 | \& "Christmas" => "24.Dec", | |
360 | \& "Christmas" => "24Dec.", | |
361 | \& "Christmas" => "24.Dec.", | |
362 | .Ve | |
363 | .PP | |
364 | .Vb 2 | |
365 | \& "Christmas" => "24-12", | |
366 | \& "Christmas" => "24-12-", | |
367 | .Ve | |
368 | .PP | |
369 | .Vb 2 | |
370 | \& "Christmas" => "24-Dec", | |
371 | \& "Christmas" => "24-Dec-", | |
372 | .Ve | |
373 | .PP | |
374 | .Vb 3 | |
375 | \& "Christmas" => "12/25", # American format (month, day) | |
376 | \& "Christmas" => "Dec25", | |
377 | \& "Christmas" => "Dec/25", | |
378 | .Ve | |
379 | .PP | |
380 | .Vb 1 | |
381 | \& - Dates relative to Easter Sunday: | |
382 | .Ve | |
383 | .PP | |
384 | .Vb 13 | |
385 | \& "Ladies' Carnival" => "-52", | |
386 | \& "Carnival Monday" => "-48", | |
387 | \& "Mardi Gras" => "-47", | |
388 | \& "Ash Wednesday" => "-46", | |
389 | \& "Palm Sunday" => "-7", | |
390 | \& "Maundy Thursday" => "-3", | |
391 | \& "Good Friday" => "-2", | |
392 | \& "Easter Sunday" => "+0", | |
393 | \& "Easter Monday" => "+1", | |
394 | \& "Ascension" => "+39", | |
395 | \& "Whitsunday" => "+49", | |
396 | \& "Whitmonday" => "+50", | |
397 | \& "Corpus Christi" => "+60", | |
398 | .Ve | |
399 | .PP | |
400 | .Vb 1 | |
401 | \& - The 1st, 2nd, 3rd, 4th or last day of week: | |
402 | .Ve | |
403 | .PP | |
404 | .Vb 7 | |
405 | \& "Thanksgiving" => "4Thu11", | |
406 | \& "Thanksgiving" => "4/Thu/Nov", | |
407 | \& "Columbus Day" => "2/Mon/Oct", | |
408 | \& "Columbus Day" => "2/Mon/10", | |
409 | \& "Columbus Day" => "2/1/Oct", | |
410 | \& "Columbus Day" => "2/1/10", | |
411 | \& "Memorial Day" => "5/Mon/May", # LAST Monday of May | |
412 | .Ve | |
413 | .PP | |
414 | .Vb 1 | |
415 | \& - Half holidays, commemorative days: | |
416 | .Ve | |
417 | .PP | |
418 | .Vb 2 | |
419 | \& "Christmas" => ":24.12.", # only half a day off | |
420 | \& "Valentine's Day" => "#Feb/14", # not an official holiday | |
421 | .Ve | |
422 | .SH "CALLBACK INTERFACE" | |
423 | .IX Header "CALLBACK INTERFACE" | |
424 | The interface of the callback functions to use with the | |
425 | \&\*(L"\fIinit()\fR\*(R" method of the \fIDate::Calendar::Year\fR\|(3) module is | |
426 | very simple: | |
427 | .PP | |
428 | The callback function receives two arguments when called, | |
429 | first the year number for which the holiday is to be | |
430 | calculated, and second the name (the \*(L"label\*(R") of the | |
431 | holiday in question (which serves as key in the hash | |
432 | of a holiday scheme). | |
433 | .PP | |
434 | This second parameter allows you to use the same callback | |
435 | function for different holidays, which might be more practical | |
436 | (than separate callback functions) if for instance you have | |
437 | a set of similar holidays to calculate, like for instance | |
438 | the four Sundays before Christmas (\*(L"Advent\*(R"). | |
439 | .PP | |
440 | The callback function \*(L"\fIAdvent()\fR\*(R" (exported by the | |
441 | Date::Calendar::Profiles module) exemplifies this | |
442 | technique. | |
443 | .PP | |
444 | The callback function is expected to return a list | |
445 | "\f(CW\*(C`($year,$month,$day)\*(C'\fR" with the exact date of the | |
446 | holiday (the year number in the output must of course | |
447 | match the year number passed as parameter). | |
448 | .PP | |
449 | A fatal error occurs if the returned list does not | |
450 | constitute a valid date, in the requested year. | |
451 | .PP | |
452 | Optionally, the callback function may return a fourth | |
453 | value (after the date) containing a string, which may | |
454 | be either \*(L"#\*(R" or \*(L":\*(R". | |
455 | .PP | |
456 | The string \*(L"#\*(R" signifies that the date in question is | |
457 | a purely commemorative date, i.e., that you don't get | |
458 | a day off from work on that day. | |
459 | .PP | |
460 | The string \*(L":\*(R" means that the date in question is a | |
461 | \&\*(L"half\*(R" holiday, i.e., a day on which you get half a | |
462 | day off from work. | |
463 | .PP | |
464 | In case the holiday in question was not observed or did | |
465 | not exist in the requested year, the callback function | |
466 | may also return an empty list. This will cause the \*(L"\fIinit()\fR\*(R" | |
467 | method to simply drop this holiday for that year. | |
468 | .PP | |
469 | The module Date::Calendar::Profiles exports the sample | |
470 | callback functions \*(L"\fIAdvent1()\fR\*(R", \*(L"\fIAdvent2()\fR\*(R", \*(L"\fIAdvent3()\fR\*(R", | |
471 | \&\*(L"\fIAdvent4()\fR\*(R" and \*(L"\fIAdvent()\fR\*(R", which might assist you in | |
472 | rolling your own profiles. | |
473 | .SH "HOW TO ROLL YOUR OWN" | |
474 | .IX Header "HOW TO ROLL YOUR OWN" | |
475 | Every calendar profile (holiday scheme) is a hash. | |
476 | .PP | |
477 | The name of the holiday (like \*(L"Christmas\*(R", for instance) | |
478 | serves as the key in this hash and must therefore be | |
479 | unique (unless you want to override a default which was | |
480 | set previously, but see below for more on this). | |
481 | .PP | |
482 | The value for each key is either a string, which specifies | |
483 | a simple date formula, or the reference of a callback function. | |
484 | .PP | |
485 | See the section \*(L"\s-1CALLBACK\s0 \s-1INTERFACE\s0\*(R" above for a description | |
486 | of the interface (in and out) of these callback functions. | |
487 | .PP | |
488 | See the section \*(L"\s-1DATE\s0 \s-1FORMULA\s0 \s-1SYNTAX\s0\*(R" above and the description | |
489 | of the \*(L"\fIinit()\fR\*(R" method in \fIDate::Calendar::Year\fR\|(3) for the | |
490 | exact syntax of date formula strings. | |
491 | .PP | |
492 | \&\fB\s-1BEWARE\s0\fR that if keys are not unique in the source code, | |
493 | later entries will overwrite previous ones! I.e., | |
494 | .PP | |
495 | .Vb 4 | |
496 | \& ... | |
497 | \& "My special holiday" => "01-11", | |
498 | \& "My special holiday" => "02-11", | |
499 | \& ... | |
500 | .Ve | |
501 | .PP | |
502 | will \fB\s-1NOT\s0\fR set two holidays of the same name, one on November | |
503 | first, the other on November second, but only one, on November | |
504 | second! | |
505 | .PP | |
506 | Therefore, in order to use sets of defaults and to be able | |
507 | to override some of them, you must \fB\s-1FIRST\s0\fR include any hash | |
508 | containing the default definitions, and \fB\s-1THEN\s0\fR write down | |
509 | your own definitions (see also the Date::Calendar::Profiles | |
510 | module for examples of this!), like this: | |
511 | .PP | |
512 | .Vb 6 | |
513 | \& $defaults = | |
514 | \& { | |
515 | \& "Holiday #1" => "01-01", | |
516 | \& "Holiday #2" => "02-02", | |
517 | \& "Holiday #3" => "03-03" | |
518 | \& }; | |
519 | .Ve | |
520 | .PP | |
521 | .Vb 6 | |
522 | \& $variant1 = | |
523 | \& { | |
524 | \& %$defaults, | |
525 | \& "Holiday #2" => "09-02", | |
526 | \& "Holiday #4" => "04-04" | |
527 | \& }; | |
528 | .Ve | |
529 | .PP | |
530 | This is because of the way hashes work in Perl. | |
531 | .PP | |
532 | Now let's suppose that you want to write a profile containing | |
533 | all your relatives' and friends' birthdays or anniversaries. | |
534 | .PP | |
535 | Simply go ahead and list them in your program, in any order | |
536 | you like, as follows (for example): | |
537 | .PP | |
538 | .Vb 16 | |
539 | \& $Birthdays = | |
540 | \& { | |
541 | \& "Spouse 1971" => "30.12.", | |
542 | \& "Wedding Day 1992" => "01.09.", | |
543 | \& "Valentine's Day" => "14.02.", | |
544 | \& "Son Richard 1996" => "11.05.", | |
545 | \& "Daughter Irene 1994" => "17.01.", | |
546 | \& "Mom 1939" => "19.08.", | |
547 | \& "Dad 1937" => "23.04.", | |
548 | \& "Brother Timothy 1969" => "24.04.", | |
549 | \& "Sister Catherine 1973" => "21.10.", | |
550 | \& "Cousin Paul 1970" => "16.10.", | |
551 | \& "Aunt Marjorie 1944" => "09.06.", | |
552 | \& "Uncle George 1941" => "02.08.", | |
553 | \& "Friend Alexander 1968" => "12.06.", | |
554 | \& }; | |
555 | .Ve | |
556 | .PP | |
557 | The year numbers after the names are not really necessary, | |
558 | but they allow us to display the person's current age. If | |
559 | this year number is omitted, we simply don't display the age. | |
560 | .PP | |
561 | Now in order to query this birthday database, we can use the | |
562 | following little program: | |
563 | .PP | |
564 | .Vb 1 | |
565 | \& #!perl -w | |
566 | .Ve | |
567 | .PP | |
568 | .Vb 4 | |
569 | \& use strict; | |
570 | \& no strict "vars"; | |
571 | \& use Date::Calc qw(:all); | |
572 | \& use Date::Calendar; | |
573 | .Ve | |
574 | .PP | |
575 | .Vb 4 | |
576 | \& $Birthdays = | |
577 | \& { | |
578 | \& ... # (see above) | |
579 | \& }; | |
580 | .Ve | |
581 | .PP | |
582 | .Vb 3 | |
583 | \& @today = Today(); | |
584 | \& $calendar = Date::Calendar->new( $Birthdays ); | |
585 | \& $calendar->year( $today[0] ); | |
586 | .Ve | |
587 | .PP | |
588 | .Vb 41 | |
589 | \& foreach $key (@ARGV) | |
590 | \& { | |
591 | \& if (@list = $calendar->search( $key )) | |
592 | \& { | |
593 | \& foreach $date (@list) | |
594 | \& { | |
595 | \& @labels = $calendar->labels( $date ); | |
596 | \& $dow = shift(@labels); | |
597 | \& # More than one person might have birthday on the same date: | |
598 | \& $name = $key; | |
599 | \& foreach $person (@labels) | |
600 | \& { | |
601 | \& if (index(lc($person),lc($key)) >= 0) | |
602 | \& { | |
603 | \& $name = $person; | |
604 | \& last; | |
605 | \& } | |
606 | \& } | |
607 | \& $delta = Delta_Days(@today, $date->date()); | |
608 | \& $age = ''; | |
609 | \& if ($name =~ s!\es*(\ed+)\es*$!!) | |
610 | \& { | |
611 | \& $age = $today[0] - $1; | |
612 | \& $age-- if ($delta > 0); | |
613 | \& $age = sprintf(" (%2d years old)", $age); | |
614 | \& } | |
615 | \& printf | |
616 | \& ( | |
617 | \& "%-20.20s: %+5d days => %3.3s %2d-%3.3s-%4d%s\en", | |
618 | \& $name, | |
619 | \& $delta, | |
620 | \& $dow, | |
621 | \& $date->day(), | |
622 | \& Month_to_Text($date->month()), | |
623 | \& $date->year(), | |
624 | \& $age | |
625 | \& ); | |
626 | \& } | |
627 | \& } | |
628 | \& else { print "No entry found in birthday list for '$key'!\en" } | |
629 | \& } | |
630 | .Ve | |
631 | .PP | |
632 | .Vb 1 | |
633 | \& __END__ | |
634 | .Ve | |
635 | .PP | |
636 | Let us save this program as, say, \*(L"birthday.pl\*(R". | |
637 | .PP | |
638 | Then we can query this birthday database by providing search strings | |
639 | on the command line, like this (note that this is a (case\-insensitive) | |
640 | substring search, \fB\s-1NOT\s0\fR a regular expression match!): | |
641 | .PP | |
642 | .Vb 2 | |
643 | \& > date | |
644 | \& Wed Oct 3 18:05:45 CEST 2001 | |
645 | .Ve | |
646 | .PP | |
647 | .Vb 3 | |
648 | \& > perl birthday.pl wed spo | |
649 | \& Wedding Day : -32 days => Sat 1-Sep-2001 ( 9 years old) | |
650 | \& Spouse : +88 days => Sun 30-Dec-2001 (29 years old) | |
651 | .Ve | |
652 | .PP | |
653 | .Vb 3 | |
654 | \& > perl birthday.pl son daug | |
655 | \& Son Richard : -145 days => Fri 11-May-2001 ( 5 years old) | |
656 | \& Daughter Irene : -259 days => Wed 17-Jan-2001 ( 7 years old) | |
657 | .Ve | |
658 | .PP | |
659 | .Vb 3 | |
660 | \& > perl birthday.pl broth sist | |
661 | \& Brother Timothy : -162 days => Tue 24-Apr-2001 (32 years old) | |
662 | \& Sister Catherine : +18 days => Sun 21-Oct-2001 (27 years old) | |
663 | .Ve | |
664 | .PP | |
665 | .Vb 3 | |
666 | \& > perl birthday.pl mom dad | |
667 | \& Mom : -45 days => Sun 19-Aug-2001 (62 years old) | |
668 | \& Dad : -163 days => Mon 23-Apr-2001 (64 years old) | |
669 | .Ve | |
670 | .PP | |
671 | .Vb 3 | |
672 | \& > perl birthday.pl uncl aunt | |
673 | \& Uncle George : -62 days => Thu 2-Aug-2001 (60 years old) | |
674 | \& Aunt Marjorie : -116 days => Sat 9-Jun-2001 (57 years old) | |
675 | .Ve | |
676 | .PP | |
677 | .Vb 2 | |
678 | \& > perl birthday.pl alex | |
679 | \& Friend Alexander : -113 days => Tue 12-Jun-2001 (33 years old) | |
680 | .Ve | |
681 | .PP | |
682 | In order to get the whole list, we can supply a substring which is | |
683 | contained in every name, which happens to be a blank (\f(CW"\ "\fR): | |
684 | .PP | |
685 | .Vb 14 | |
686 | \& > perl birthday.pl ' ' | |
687 | \& Daughter Irene : -259 days => Wed 17-Jan-2001 ( 7 years old) | |
688 | \& Valentine's Day : -231 days => Wed 14-Feb-2001 | |
689 | \& Dad : -163 days => Mon 23-Apr-2001 (64 years old) | |
690 | \& Brother Timothy : -162 days => Tue 24-Apr-2001 (32 years old) | |
691 | \& Son Richard : -145 days => Fri 11-May-2001 ( 5 years old) | |
692 | \& Aunt Marjorie : -116 days => Sat 9-Jun-2001 (57 years old) | |
693 | \& Friend Alexander : -113 days => Tue 12-Jun-2001 (33 years old) | |
694 | \& Uncle George : -62 days => Thu 2-Aug-2001 (60 years old) | |
695 | \& Mom : -45 days => Sun 19-Aug-2001 (62 years old) | |
696 | \& Wedding Day : -32 days => Sat 1-Sep-2001 ( 9 years old) | |
697 | \& Cousin Paul : +13 days => Tue 16-Oct-2001 (30 years old) | |
698 | \& Sister Catherine : +18 days => Sun 21-Oct-2001 (27 years old) | |
699 | \& Spouse : +88 days => Sun 30-Dec-2001 (29 years old) | |
700 | .Ve | |
701 | .PP | |
702 | By the way, a similar program is included in the \*(L"examples\*(R" | |
703 | subdirectory of the Date::Calc distribution, called \*(L"anniversaries.pl\*(R". | |
704 | .PP | |
705 | See also the file \*(L"\s-1EXAMPLES\s0.txt\*(R" in the distribution's main directory | |
706 | for a short description of that little script. | |
707 | .SH "SEE ALSO" | |
708 | .IX Header "SEE ALSO" | |
709 | \&\fIDate::Calendar\fR\|(3), \fIDate::Calendar::Year\fR\|(3), | |
710 | \&\fIDate::Calc::Object\fR\|(3), \fIDate::Calc\fR\|(3). | |
711 | .SH "VERSION" | |
712 | .IX Header "VERSION" | |
713 | This man page documents \*(L"Date::Calendar::Profiles\*(R" version 5.3. | |
714 | .SH "AUTHOR" | |
715 | .IX Header "AUTHOR" | |
716 | .Vb 3 | |
717 | \& Steffen Beyer | |
718 | \& mailto:sb@engelschall.com | |
719 | \& http://www.engelschall.com/u/sb/download/ | |
720 | .Ve | |
721 | .SH "COPYRIGHT" | |
722 | .IX Header "COPYRIGHT" | |
723 | Copyright (c) 2000 \- 2002 by Steffen Beyer. All rights reserved. | |
724 | .SH "LICENSE" | |
725 | .IX Header "LICENSE" | |
726 | This package is free software; you can redistribute it and/or | |
727 | modify it under the same terms as Perl itself, i.e., under the | |
728 | terms of the \*(L"Artistic License\*(R" or the \*(L"\s-1GNU\s0 General Public License\*(R". | |
729 | .PP | |
730 | Please refer to the files \*(L"Artistic.txt\*(R" and \*(L"\s-1GNU_GPL\s0.txt\*(R" | |
731 | in this distribution for details! | |
732 | .SH "DISCLAIMER" | |
733 | .IX Header "DISCLAIMER" | |
734 | This package is distributed in the hope that it will be useful, | |
735 | but \s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of | |
736 | \&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0. | |
737 | .PP | |
738 | See the \*(L"\s-1GNU\s0 General Public License\*(R" for more details. |