NAME Date::Holidays - a Date::Holidays::* OOP Adapter aggregator 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 = Date::Holidays->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 = Date::Holidays->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', ); VERSION This POD describes version 0.10 of Date::Holidays DESCRIPTION Date::Holidays is an aggregator of adapters exposing a uniform API to a set of modules either in the Date::Holidays::* namespace of elsewhere. All of these modules deliver methods and information on national calendars. The module seem to more or less follow a defacto standard (see: also the generic adapter Date::Holidays::Adapter), but the adapters are implemented to uniform this and Date::Holidays exposes a more readable API and at the same time it provides an OOP interface, to these modules, which primarily holds a procuderal API. As described below it is recommended that a certain API is implemented (SEE: holidays and is_holiday below), but taking the adapter strategy into consideration this does not matter, or we attempt to do what we can with what is provided. If you are an author who wants to comply to the suggested, either look at some of the other modules in the Date::Holidays::* namespace to get an idea of the de facto standard or have a look at Date::Holidays::Abstract and Date::Holidays::Super - or write me. SUBROUTINES/METHODS new This is the constructor. It takes the following parameters: countrycode (MANDATORY, see below), two letter unique code representing a country name. Please refer to ISO3166 (or Locale::Country) nocheck (optional), if set to true the countrycode specified will not be validated against ISO 3166, for existance, so you can build fake holidays for fake countries, I currently use this for test. The constructor loads the module from Date::Holidays::*, which matches the country code and returns a Date::Holidays module with the specified module loaded and ready to answer to any of the following methods described below, if these are implemented - of course. If no countrycode is provided or the class is not able to load a module, nothing is returned. my $dh = Date::Holidays->new(countrycode => 'dk') or die "No holidays this year, get back to work!\n"; holidays This is a wrapper around the loaded module's holidays method if this is implemented. If this method is not implemented it tries _holidays. Takes one named argument: year, four digit parameter representing year $hashref = $dh->holidays(year => 2007); holidays_dt This method is similar to holidays. It takes one named argument b. 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__holiday. Takes 3 named 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. $name = $dh->is_holiday(year => 2007, day => 24, month => 12); If this method is called using the class name Date::Holidays, all known countries are tested for a holiday on the specified date, unless the countries parameter specifies a subset of countries to test. $hashref = Date::Holidays->is_holiday(year => 2007, day => 24, month => 12); 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 This method is similar to is_holiday, but instead of 3 separate arguments it 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, suggestions 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 some, by me, 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 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__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 concatenated. Modified example taken from: L 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. _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 ); DEVELOPING A DATE::HOLIDAYS::ADAPTER CLASS If you want to contribute with an adapter, please refer to the documentation in Date::Holidays::Adapter. DIAGNOSTICS * Date::Holidays::Exception::AdapterLoad This exception is thrown when Date::Holidays::Adapter attempts to load an actual adapter implementation. This exception is recoverable to the extend that is caught and handled internally. When caught the SUPER adapter is attempted loaded, Date::Holidays::Adapter if this however fails Date::Holidays::Exception::SuperAdapterLoad it thrown see below. * Date::Holidays::Exception::SuperAdapterLoad This exception is thrown when Date::Holidays attempts to load the SUPER adapter Date::Holidays::Adapter, if this fail, we are out of luck and we throw the Date::Holidays::Exception::AdapterInitialization exception. * Date::Holidays::Exception::AdapterInitialization This exception is thrown when in was not possible to load either a implementation of a given adapter, or the SUPER adapter Date::Holidays::Adapter. * Date::Holidays::Exception::NoCountrySpecified The exception is thrown if a country code is provided, which is not listed in Locale::Country, which lists ISO 3166 codes, which is the unique 2 letter strings assigned to each country in the world. * 'Unable to locate module for ' this method is thrown from the _check_countries method, it bails out if it cannot find and load the actual implementation of a module with the name Date::Holidays:: for the specified country. This however is a mere warning. CONFIGURATION AND ENVIRONMENT No special configuration or environment is required. DEPENDENCIES * Carp * DateTime * Locale::Country * Module::Load * Error * UNIVERSAL * Date::Holidays::Adapter INCOMPATIBILITIES None known at the moment, please refer to BUGS AND LIMITATIONS and or the specific adapter classes or their respective adaptees. BUGS AND LIMITATIONS 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. Date::Holidays::DE and Date::Holidays::UK does not implement the holidays methods The actual code for United Kingdom in ISO 3166 is 'GB' (SEE Locale::Country), but the module is called Date::Holidays::UK and so it the adapter class Date::Holidays::Adapter::GB in this distribution to avoid confusion or? The adaptee module for Date::Holidays::Adapter is named: Date::Japanese::Holiday, but the adapter class is following the general adapter naming of Date::Holidays::Adapter::. The adapter for Date::Holidays::PT, Date::Holidays::Adapter::PT does not implement the is_pt_holiday method. The pattern used is an object adapter pattern and inheritance is therefor not used, it is my hope that I can make this work with some Perl magic. BUG REPORTING Please report issues via CPAN RT: http://rt.cpan.org/NoAuth/Bugs.html?Dist=Date-Holidays or by sending mail to bug-Date-Holidays@rt.cpan.org TEST COVERAGE Test coverage in version 0.06 ---------------------------- ------ ------ ------ ------ ------ ------ ------ File stmt bran cond sub pod time total ---------------------------- ------ ------ ------ ------ ------ ------ ------ blib/lib/Date/Holidays.pm 82.1 68.0 66.7 100.0 100.0 100.0 79.6 Total 82.1 68.0 66.7 100.0 100.0 100.0 79.6 ---------------------------- ------ ------ ------ ------ ------ ------ ------ I am working on a better coverage in future releases SEE ALSO * Date::Holidays::AU * Date::Holidays::Adapter::AU * Date::Holidays::DE * Date::Holidays::Adapter::DE * Date::Holidays::DK * Date::Holidays::Adapter::DK * Date::Holidays::CN * Date::Holidays::Adapter::CN * Date::Holidays::FR * Date::Holidays::Adapter::FR * Date::Holidays::NO * Date::Holidays::Adapter::NO * Date::Holidays::NZ * Date::Holidays::Adapter::NZ * Date::Holidays::PT * Date::Holidays::Adapter::PT * Date::Holidays::UK * Date::Holidays::Adapter::GB * Date::Holidays::ES * Date::Holidays::Adapter::ES * Date::Japanese::Holiday * Date::Holidays::Adapter::JP * Date::Holidays::Adapter * Date::Holidays::Abstract * Date::Holidays::Super * Date::Holidays::AT * Date::Holidays::CN ACKNOWLEDGEMENTS * Florian Merges for feedback and pointing out a bug in Date::Holidays, author of Date::Holidays::ES * COG (Jose Castro), Date::Holidays::PT author * RJBS (Ricardo Signes), POD formatting * MRAMBERG (Marcus Ramberg), Date::Holidays::NO author * BORUP (Christian Borup), DateTime suggestions * LTHEGLER (Lars Thegler), Date::Holidays::DK author * shild on use.perl.org, CPAN tester http://use.perl.org/comments.pl?sid=28993&cid=43889 * All of the authors/contributors of Date::Holidays::* modules AUTHOR Jonas B. Nielsen, (jonasbn) - "" LICENSE AND COPYRIGHT Date-Holidays and related modules are (C) by Jonas B. Nielsen, (jonasbn) 2004-2007 Date-Holidays and related modules are 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).