1Date::HolidayParser(3)User Contributed Perl DocumentationDate::HolidayParser(3)
2
3
4

NAME

6       Date::HolidayParser - Parser for .holiday-files
7

VERSION

9       0.4
10

SYNOPSIS

12       This module parses .holiday files. These are files that define holidays
13       in various parts of the world in an easy to read and easy to write (but
14       hard to parse due to its very flexible syntax) format.
15
16       This module returns a hash that you can read and use within your
17       program.
18
19               use Date::HolidayParser;
20
21               my $Holidays = Date::HolidayParser->new("$ENV{HOME}/.holiday");
22               my $Holidays_2006 = $Holidays->get(2006);
23
24               ...
25

DESCRIPTION

27       This is a module that parses .holiday-style files. These are files that
28       define holidays in various parts of the world. The files are easy to
29       write and easy for humans to read, but can be hard to parse because the
30       format allows many different ways to write it.
31
32       This module parses the files for you and returns a hash reference that
33       you can use within your perl program in whatever way you wish.
34

EXPORT

36       This module doesn't export anything by default. It can however export
37       the EasterCalc function upon request by issuing
38
39               use Date::HolidayParser qw(EasterCalc);
40               ...
41

METHODS and FUNCTIONS

43   $object = Date::HolidayParser->new(FILE);
44       This is the main function. It creates a new Date::HolidayParser object
45       for FILE and parses the file.
46
47       FILE must be the full path to the holiday file you want to parse.
48
49   $object->get(YEAR);
50       This gets the holidays for YEAR. It uses the already parsed FILE and
51       calculates the holidays in YEAR and returns a hashref with the parsed
52       data or undef on failure.
53
54       YEAR must be a full year (ie. 2006) not a year relative to 1900 (ie.
55       106).
56
57       See the section HASH SYNTAX below for the syntax of the returned
58       hashref.
59
60   Date::HolidayParser::EasterCalc
61       This is an addition to the real functions that Date::HolidayParser
62       provides.  It's needed inside of the module but might also be useful
63       for others and thus made available.
64
65               use Date::HolidayParser;
66               my $Easter = Date::HolidayParser::EasterCalc(YEAR);
67
68       YEAR must be a full year (ie. 2006) not a year relative to 1900 (ie.
69       106).
70
71       It returns the day of easter of the year supplied.
72
73       NOTE: The day returned begins on 0. This means that the days returned
74       are 0-364 instead of 1-365.
75

ATTRIBUTES

77       Attributes can be supplied to the constructor as a parameter after the
78       file parameter (ie. Date::HolidayParser->new('file', attribute =>
79       "value");), or you can use $object->attribute(VALUE).
80
81   silent
82       If true this will make Date::HolidayParser not output any warnings
83       (such as syntax errors).
84

HASH SYNTAX

86       The returned hash is in the following format:
87
88               \%HasRef = (
89                'MONTH (1-12)' => {
90                  'DAY OF THE MONTH (1-31)' => {
91                    'NAME OF THE HOLIDAY' => 'TYPE OF HOLIDAY'
92                   }
93                  }
94                 );
95
96       MONTH is a numeric month in the range 1-12.
97
98       DAY OF THE MONTH is a numeric day relative to the month in the range
99       1-31 (max).
100
101       NAME OF THE HOLIDAY is the name of the holiday as set by the
102       .holiday-file.
103
104       TYPE OF HOLIDAY is the type of holiday it is. It is one of the
105       following:
106
107       •   "none" means that it is a normal day.
108
109       •   "red" means that it is a "red" day (ie. public holiday/day off).
110

EXAMPLE

112       Here is an example of the module in use.  The UK holiday file was
113       chosen because it is rather small and simple.
114
115   The holiday file
116               :
117               : UK holiday file. Copy to ~/.holiday
118               :
119               : Author: Peter Lord <plord@uel.co.uk>
120               :
121               "New Years Day" red on 1/1
122               "Easter Sunday" red on easter
123               "Good Friday" red on easter minus 2
124               "Easter Monday" red on easter plus 1
125               "May Day" red on first monday in may
126               "Spring Bank Holiday" red on last monday in may
127               "Summer Bank Holiday" red on last monday in august
128               "Christmas Day" red on 12/25
129               "Boxing Day" red on 12/26
130
131   The program
132               #!/usr/bin/perl
133               use warnings;
134               use strict;
135               use Data::Dumper;
136               use Date::HolidayParser;
137
138               # Call Date::HolidayParser to parse the file
139               my $Holidays = Date::HolidayParser->new(/path/to/file);
140               my $Holidays_2006 = $Holidays->get(2006);
141
142               # Set a proper Data::Dumper format and dump the data returned by Date::HolidayParser to STDOUT
143               $Data::Dumper::Purity = 1; $Data::Dumper::Sortkeys = 1; $Data::Dumper::Indent = 1;
144               print Data::Dumper->Dump([$Holidays_2006], ["*Holidays_2006"]);
145
146   The output
147               %Holidays_2006 = (
148                 '1' => {
149                   '1' => {
150                     'New Years Day' => 'red'
151                   }
152                 },
153                 '12' => {
154                   '25' => {
155                     'Christmas Day' => 'red'
156                   },
157                   '26' => {
158                     'Boxing Day' => 'red'
159                   }
160                 },
161                 '4' => {
162                   '14' => {
163                     'Good Friday' => 'red'
164                   },
165                   '16' => {
166                     'Easter Sunday' => 'red'
167                   },
168                   '17' => {
169                     'Easter Monday' => 'red'
170                   }
171                 },
172                 '5' => {
173                   '1' => {
174                     'May Day' => 'red'
175                   },
176                   '29' => {
177                     'Spring Bank Holiday' => 'red'
178                   }
179                 },
180                 '8' => {
181                   '28' => {
182                     'Summer Bank Holiday' => 'red'
183                   }
184                 }
185               );
186
187   Explenation
188       This is a very simple example. It first creates a $Holidays
189       Date::HolidayParser object, then tells it to get the holidays for the
190       year 2006 ($Holidays->get(2006);) and saves the information to
191       $Holidays_2006. Then it tells Data::Dumper to dump a visual (perl-
192       usable) representation of the hash to stdout.
193

SETTINGS

195   $Date::HolidayParser::BeSilent
196       This variable is deprecated, it is the same as setting the silent
197       attribute.  It will be removed in a future version.
198

INCOMPATIBILITIES

200       No longer supports the legacy function-oriented syntax.
201

AUTHOR

203       Eskild Hustvedt - "<zerodogg@cpan.org>"
204

BUGS

206       Please report any bugs or feature requests to
207       "bug-date-holidayparser@rt.cpan.org", or through the web interface at
208       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Date-HolidayParser>.  I
209       will be notified, and then you'll automatically be notified of progress
210       on your bug as I make changes.
211

213       Copyright (C) 2006, 2007, 2010 Eskild Hustvedt, all rights reserved.
214
215       This program is free software; you can redistribute it and/or modify it
216       under the same terms as Perl itself. There is NO warranty; not even for
217       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
218
219
220
221perl v5.32.1                      2021-01-27            Date::HolidayParser(3)
Impressum