NAME
Date::Holidays - a Date::Holidays::* OOP wrapper
SYNOPSIS
use Date::Holidays;
my $dh = Date::Holidays->new(
countrycode => 'dk'
);
$holidayname = $dh->is_holiday(
year => 2004,
month => 12,
day => 25
);
$hashref = $dh->holidays(
year => 2004
);
$holidays_hashref = $dh->is_holiday(
year => 2004,
month => 12,
day => 25,
countries => ['se', 'dk', 'no'],
);
foreach my $country (keys %{$holidays_hashref}) {
print $holidays_hashref->{$country}."\n";
}
$holidays_hashref = $dh->is_holiday(
year => 2004,
month => 12,
day => 25,
);
#Example of a module with additional parameters
my $dh = Date::Holidays->new(
countrycode => 'au'
);
$holidayname = $dh->is_holiday(
year => 2004,
month => 12,
day => 25,
state => 'TAS',
);
$hashref = $dh->holidays(
year => 2004
state => 'TAS',
);DESCRIPTION
These are the methods implemented in this class. They act as wrappers around the different modules implementing different national holidays, and at the same time they provide an OOP interface.
As described below is requires that a certain API is implemented (SEE: holidays and is_holiday below).
If you are an author who wants to comply to this suggestion, either look at some of the other modules in the Date::Holidays::* namespace and Date::Holidays::Abstract or Date::Holidays::Super - or write me.
new
This is the constructor. It takes the following parameter:
- countrycode (OPTIONAL, see below), two letter unique code representing a country name. Please refer to ISO3166 (or Locale::Country)
The constructor loads the module from Date::Holidays::*, which matches the country code.
holidays
This is a wrapper around the loaded module's holidays method if this is implemented. If this method is not implemented it tries <countrycode>_holidays.
Takes one named argument:
holidays_dt *EXPERIMENTAL*
This method is similar to holidays. It takes one named argument b<year>.
The result is a hashref just as for holidays, but instead the names of the holidays are used as keys and the values are DateTime objects.
is_holiday
This is yet another wrapper around the loaded module's is_holiday method if this is implemented. Also if this method is not implemented it tries is_<countrycode>_holiday.
Takes 3 arguments:
- year, four digit parameter representing year
- month, 1-12, representing month
- day, 1-31, representing day
- countries (OPTIONAL), a list of ISO3166 country codes
is_holiday returns the name of a holiday is present in the country specified by the country code provided to the Date::Holidays constructor.
If however the Date::Holidays object was not provided with a country code, all known countries are tested for a holiday on the specified date, unless the countries parameter specified a subset of countries to test.
In the case where a set of countries are tested the return value from the method is a hashref with the country codes as keys and the values as the result.
- undef if the country has no module or the data could not be obtained
- a name of the holiday if a holiday is present
- an empty string if the a module was located but the day is not a holiday
is_holiday_dt *EXPERIMENTAL*
This method is similar to is_holiday, but instead of 3 separate arguments is only takes a single argument, a DateTime object.
Return 1 for true if the object is a holiday and 0 for false if not.
DEVELOPING A DATE::HOLIDAYS::* MODULE
There is no control of the Date::Holidays::* namespace at all, so I am by no means an authority, but this is recommendations on order to make the modules in the Date::Holidays more uniform and thereby more usable.
If you want to participate in the effort to make the Date::Holidays::* namespace even more usable, feel free to do so, your feedback and suggestions will be more than welcome.
If you want to add your country to the Date::Holidays::* namespace, please feel free to do so. If a module for you country is already present, I am sure the author would not mind patches, suggestion or even help.
If however you country does not seem to be represented in the namespace, you are more than welcome to become the author of the module in question.
Please note that the country code is expected to be a two letter code based on ISO3166 (or Locale::Country).
As an experiment I have added two modules to the namespace, Date::Holidays::Abstract and Date::Holidays::Super, abstract is attempt to make sure that the module implements the expected methods.
So by using abstract your module will not work until it follows the the abstract layed out for a Date::Holidays::* module. Unfortunately the module will only check for the presence of the methods not their prototypes.
Date::Holidays::Super is for the lazy programmer, it implements the necessary methods as stubs and there for do not have to implement anything, but your module will not return anything of value. So the methods need to be overwritten in order to comply with the expected output of a Date::Holidays::* method.
The methods which are currently interesting in a Date::Holidays::* module are:
- is_holiday
-
Takes 3 arguments: year, month, day and returns the name of the holiday as a scalar in the national language of the module context in question. Returns undef if the requested day is not a holiday.
Modified example taken from: L<Date::Holidays::DK> use Date::Holidays::DK; my ($year, $month, $day) = (localtime)[ 5, 4, 3 ]; $year += 1900; $month += 1; print "Woohoo" if is_holiday( $year, $month, $day ); #The actual method might not be implemented at this time in the #example module. - is_<countrycode>_holiday
-
Same as above.
This method however should be a wrapper of the above method (or the other way around).
- holidays
-
Takes 1 argument: year and returns a hashref containing all of the holidays in specied for the country, in the national language of the module context in question.
The keys are the dates, month + day in two digits each contatenated.
Modified example taken from: L<Date::Holidays::PT> my $h = holidays($year); printf "Jan. 1st is named '%s'\n", $h->{'0101'}; #The actual method might not be implemented at this time in the #example module. - <countrycode>_holidays
-
This method however should be a wrapper of the above method (or the other way around).
Only is_holiday and holidays are implemented in Date::Holidays::Super and are required by Date::Holidays::Abstract.
ADDITIONAL PARAMETERS
Some countries are divided into regions or similar and might require additional parameters in order to give more exact holiday data.
This is handled by adding additional parameters to is_holiday and holidays.
These parameters are left to the module authors descretion and the actual Date::Holidays::* module should be consulted.
Example Date::Holidays::AU
use Date::Holidays::AU qw( is_holiday );
my ($year, $month, $day) = (localtime)[ 5, 4, 3 ];
$year += 1900;
$month += 1;
my ($state) = 'VIC';
print "Excellent\n" if is_holiday( $year, $month, $day, $state ); SEE ALSO
- Date::Holidays::AU
- Date::Holidays::DE
- Date::Holidays::DK
- Date::Holidays::FR
- Date::Holidays::NO
- Date::Holidays::NZ
- Date::Holidays::PT
- Date::Holidays::UK
- Date::Japanese::Holiday
- Date::Holidays::Abstract
- Date::Holidays::Super
- DateTime
CAVEATS
Currently we have an exception for the Date::Holidays::AU module, so the additional parameter of state is defaulting to 'VIC', please refer to the POD for Date::Holidays::AU for documentation on this.
BUGS
Please report issues via CPAN RT:
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Date-Holidaysor by sending mail to
bug-Date-Holidays@rt.cpan.orgACKNOWLEDGEMENTS
COG (Jose Castro)
RJBS (Ricardo Signes)
MRAMBERG (Marcus Ramberg)
BORUP (Christian Borup)
shild on use.perl.org
AUTHOR
Jonas B. Nielsen, (jonasbn) - <jonasbn@cpan.org>
COPYRIGHT
Date-Holidays is (C) by Jonas B. Nielsen, (jonasbn) 2004-2005
Date-Holidays is released under the artistic license
The distribution is licensed under the Artistic License, as specified by the Artistic file in the standard perl distribution (http://www.perl.com/language/misc/Artistic.html).