README file for Date-Holidays

$Id: README 1737 2007-02-21 22:20:33Z jonasbn $

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 = 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.09 of Date::Holidays

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.

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
    <countrycode>_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<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.

            $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<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 );   

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 for the next release...

SEE ALSO
    Date::Holidays::AU
    Date::Holidays::DE
    Date::Holidays::DK
    Date::Holidays::CN
    Date::Holidays::FR
    Date::Holidays::NO
    Date::Holidays::NZ
    Date::Holidays::PT
    Date::Holidays::UK
    Date::Holidays::AT
    Date::Holidays::ES
    Date::Japanese::Holiday
    Date::Holidays::Abstract
    Date::Holidays::Super
    DateTime

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::Adapater.

    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 character strings assigned to each country in the world.

    'Unable to locate module for <country>' 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::<country> for the specified country.

CONFIGURATION AND ENVIRONMENT
    No special configuration or environment is required

DEPENDENCIES
    Carp
    DateTime
    Locale::Country
    Module::Load
    Error
    UNIVERSAL

INCOMPATIBILITIES
    None known at the moment, please refer to BUGS AND LIMITATIONS

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::UK in this distribution to
    avoid confusion.

    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

ACKNOWLEDGEMENTS
    * Florian Merges for feedback and pointing out a bug
    * COG (Jose Castro), Date::Holidays::PT author
    * RJBS (Ricardo Signes)
    * MRAMBERG (Marcus Ramberg), Date::Holidays::NO author
    * BORUP (Christian Borup), DateTime suggestions
    * shild on use.perl.org
    * All of the authors/contributors of Date::Holidays::* modules

AUTHOR
    Jonas B. Nielsen, (jonasbn) - "<jonasbn@cpan.org>"

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).

