Date::Holidays::CA - Holidays for Canadian locales
# 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'}); 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
Date::Holidays::CA determines public holidays for Canadian jurisdictions. Its interface is a superset of that provided by Date::Holidays -- read on for details.
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.
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
ON
Ontario
PE
Prince Edward Island
QC
Quebec
SK
Saskatchewan
YT
Yukon Territory
EN/FR
English text followed by French text.
FR/EN
French text followed by English text.
EN
English text only.
FR
French text only.
Retrieve fields of a Date::Holidays::CA object.
$prov = $dhc->('province');
Alter fields of a Date::Holidays::CA object. Specify parameters just as with new().
$dhc->set({province => 'QC', language => 'FR/EN'});
These methods are callable in either object-oriented or procedural style.
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);
Similar to is_holiday. Return the name of the holiday occurring on the specified date if there is one; undef if there isn't.
is_holiday
undef
print $dhc->is_ca_holiday(2001, 1, 1); # "New Year's Day"
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);
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.
mmdd
my $calendar = holidays($year, {province => 'MB', language => 'EN'}); print $calendar->('0701'); # "Canada Day" my $calendar = $dhc->holidays($year); print $calendar->('1111'); # "Remembrance Day"
Same as holidays().
holidays()
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);
The following holidays are recognized:
January 1.
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.
The Third Monday of February is Family Day in AB, SK, and ON, and Louis Riel Day in MB.
NL. Nearest Monday to March 17.
The Friday falling before Easter Sunday.
CA, QC. The Monday following Easter Sunday.
NL. Nearest Monday to April 23.
Monday falling on or before May 24.
NT. June 21.
QC. June 24.
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.
July 1.
NU. July 9.
NL. Monday nearest July 12.
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.
First Monday of September.
Second Monday of October.
All but ON and QC. November 11.
December 25.
CA, NL, NT, NU, ON, PE. December 26.
http://en.wikipedia.org/wiki/Public_holidays_in_Canada
http://www.craigmarlatt.com/canada/symbols_facts&lists/holidays.html
http://www.craigmarlatt.com/canada/symbols_facts&lists/august_holiday.html
http://geonames.nrcan.gc.ca/info/prov_abr_e.php (Provincial abbreviations)
A grillion government web pages listing official statutory holidays, all of which seem to have gone offline or moved.
http://www.gov.mb.ca/labour/standards/doc,louis-riel_day,factsheet.html (MB's Louis Riel Day)
http://www.theguardian.pe.ca/index.cfm?sid=244766&sc=98 (PEI's Islander Day)
Historical holidays are not supported; the current set of holidays will be projected into the past or future. For instance, Louis Riel Day was added as a Manitoba holiday in 2008, but if you use this module to generate a holiday list for 2007, Louis Riel Day will be present. Also, PEI's Islander Day was first observed on the second Monday of 2009, but will subsequently be observed on the third Monday of the month; this module will always show it as occurring on the third Monday. This will be addressed if there is demand to do so.
Several lesser holidays are not yet implemented:
I am told that the morning of the Stampede Parade is commonly given as a half-day holiday by employers within the city of Calgary, but I haven't been able to verify this, nor does there seem to be a way to mathematically calculate when parade day will be scheduled.
Regatta Day is a municipal holiday in St Johns, NL, and it is scheduled for the first Wednesday in August. However, if the weather on Quidi Vidi Lake does not look promising on Regatta morning, the event (and the attendant holiday) are postponed until the next suitable day.
How to programatically determine the day of this holiday has not yet been satisfactorily ascertained. Acme::Test::Weather has been considered.
Some few employees apparently get the day of the Gold Cup and Saucer harness race as a holiday, but I haven't been able to independently verify this.
In Quebec, the vast majority of the construction industry gets the last full two weeks of July off, and it's also a popular time for other folks to book vacation. Since this technically only applies to a single industry, I haven't added it to this module, but I will if there is sufficient demand.
As you can see from the KNOWN BUGS section above, our holiday structure can be fairly baroque. Different provinces and cities get different holidays; sometimes these are paid statutory holidays that are included in Employment Standards legislation; other times they are unofficial holidays that are given by convention and codified only in collective agreements and municipal by-laws. Thus, it's hard to know what's commonly considered "a holiday" in the various regions of the country without actually having lived and worked there.
I only have direct experience with British Columbia and Ontario; my impression of what folks in other provinces consider to be a holiday is based on research on the WWW. I've tried to define a holiday as any day when "the majority of the workforce either get the day off (paid or unpaid) or receive pay in lieu." If the holidays list in this module doesn't accurately reflect the application of that definition to your region of Canada, I'd like to hear about it.
Assistance with French translations of the holiday names and this documentation is most welcome. My French isn't all that great, but I'm happy to learn. =)
Finally, I'd appreciate an email from any users of this module. I'm curious to know who has picked it up, and any feedback you might have will shape its future development.
For reasons outlined in the two sections above, please be forewarned that what days are considered holidays may change with versions of the module.
Rick Scott <rick@cpan.org>
Copyright (C) 2006-2009 by Rick Scott
This module is free software! You can copy, modify, share and distribute it under the same license as Perl itself.
To install Date::Holidays::CA, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Date::Holidays::CA
CPAN shell
perl -MCPAN -e shell install Date::Holidays::CA
For more information on module installation, please visit the detailed CPAN module installation guide.