view release on metacpan or  search on metacpan

README  view on Meta::CPAN

NAME
    Date::Holidays::CA - Date::Holidays::CA determines public holidays for
    Canadian jurisdictions

VERSION
    version 0.07

SYNOPSIS
        # procedural approach

        use Date::Holidays::CA qw(:all);

        my ($year, $month, $day) = (localtime)[ 5, 4, 3 ];
        $year  += 1900;
        $month += 1;

        print 'Woot!' if is_holiday($year, $month, $day, {province => 'BC'});

        my $calendar = holidays($year, {province => 'BC'});
        #returns a hash reference
        print $calendar->{'0701'};              # "Canada Day/Fête du Canada"


        # object-oriented approach

        use DateTime;
        use Date::Holidays::CA;

        my $dhc = Date::Holidays::CA->new({ province => 'QC' });

        print 'Woot!' if $dhc->is_holiday(DateTime->today);

        my $calendar = $dhc->holidays_dt(DateTime->today->year);
        print join keys %$calendar, "\n";       # lists holiday names for QC

DESCRIPTION
    Date::Holidays::CA determines public holidays for Canadian
    jurisdictions. Its interface is a superset of that provided by
    Date::Holidays -- read on for details.

NAME
    Date::Holidays::CA - Holidays for Canadian locales

FUNCTIONS / METHODS
  Class Methods
   new()
    Create a new Date::Holidays::CA object. Parameters should be given as a
    hashref of key-value pairs.

        my $dhc = Date::Holidays::CA->new();        # defaults

        my $dhc = Date::Holidays::CA->new({
            province => 'ON', language => 'EN'
        });

    Two parameters can be specified: province and language.

   Province
    *   CA

        Canadian Federal holidays (the default).

    *   AB

        Alberta

    *   BC

        British Columbia

    *   MB

        Manitoba

    *   NB

        New Brunswick

    *   NL

        Newfoundland & Labrador

    *   NS

        Nova Scotia

    *   NT

        Northwest Territories

    *   NU

        Nunavut

README  view on Meta::CPAN

    *   FR/EN

        French text followed by English text.

    *   EN

        English text only.

    *   FR

        French text only.

  Object Methods
   get()
    Retrieve fields of a Date::Holidays::CA object.

        $prov = $dhc->('province');

   set()
    Alter fields of a Date::Holidays::CA object. Specify parameters just as
    with new().

        $dhc->set({province => 'QC', language => 'FR/EN'});

  Combination Methods
    These methods are callable in either object-oriented or procedural
    style.

   is_holiday()
    For a given year, month (1-12) and day (1-31), return 1 if the given day
    is a holiday; 0 if not. When using procedural calling style, an
    additional hashref of options can be specified.

        $holiday_p = is_holiday($year, $month, $day);

        $holiday_p = is_holiday($year, $month, $day, {
            province => 'BC', language => 'EN'
        });

        $holiday_p = $dhc->is_holiday($year, $month, $day);

   is_ca_holiday()
    Similar to "is_holiday". Return the name of the holiday occurring on the
    specified date if there is one; "undef" if there isn't.

        print $dhc->is_ca_holiday(2001, 1, 1);          # "New Year's Day"

   is_holiday_dt()
    As is_holiday, but accepts a DateTime object in place of a numeric year,
    month, and day.

        $holiday_p = is_holiday($dt, {province => 'SK', language => 'EN'});

        $holiday_p = $dhc->is_holiday($dt);

   holidays()
    For the given year, return a hashref containing all the holidays for
    that year. The keys are the date of the holiday in "mmdd" format (eg
    '1225' for December 25); the values are the holiday names.

        my $calendar = holidays($year, {province => 'MB', language => 'EN'});
        #returns a hash reference
        print $calendar->{'0701'};               # "Canada Day"

        my $calendar = $dhc->holidays($year);
        #returns a hash reference
        print $calendar->{'1111'};               # "Remembrance Day"

   ca_holidays()
    Same as holidays().

   holidays_dt()
    Similar to holidays(), after a fashion: returns a hashref with the
    holiday names as the keys and DateTime objects as the values.

        my $calendar = $dhc->holidays_dt($year);

SPECIFICATIONS
    The following holidays are recognized:

    *New Year's Day*
        January 1.

    *Islander Day*
        PE. Originally added in 2009 as the second Monday in February, this
        holiday will be revised to the third Monday in February starting in
        2010. *This module shows Islander Day as falling on the third
        Monday* -- see the *KNOWN BUGS* section.

    *Family Day / Louis Riel Day*
        The Third Monday of February is Family Day in AB, SK, and ON, and
        Louis Riel Day in MB.

    *St. Patrick's Day*
        NL. Nearest Monday to March 17.

    *Good Friday*
        The Friday falling before Easter Sunday.

    *Easter Monday*
        CA, QC. The Monday following Easter Sunday.

    *St. Patrick's Day*
        NL. Nearest Monday to April 23.

    *Victoria Day*
        Monday falling on or before May 24.

    *National Aboriginal Day*
        NT. June 21.

    *Saint-Jean-Baptiste Day*
        QC. June 24.

    *Discovery Day*
        There are actually two holidays named "Discovery Day". Newfoundland
        observes Discovery Day on the Monday nearest June 24, and the Yukon
        observes Discovery Day on the third Monday of August.

    *Canada Day*
        July 1.

    *Nunavut Day*
        NU. July 9.

    *Orangemen's Day*
        NL. Monday nearest July 12.

    *Civic Holiday*
        AB, BC, MB, NB, NS, NT, NU, ON, PE, SK (that is to say, not CA, NL,
        QC, or YT). First Monday of August.

        Different provinces call this holiday different things -- eg "BC
        Day" in British Columbia, "Alberta Heritage Day" in Alberta, "Natal
        Day" in Nova Scotia and PEI, and so forth.