Ruby Holidays Gem

What is this?

The Ruby Holidays Gem allows you to look up holidays in multiple regions based on customizable definition lists.

It also extends Ruby’s built-in Date class.

What do I get?

The Holidays Gem gives you one module and a handful of methods.

Holidays#on(date, *options)
Holidays#between(start, end, *options)
Date#holidays(*options)
Holidays#holiday?(*options)

There are more methods in the docs, but these should get you started.

How does it work?

Start by requiring the gem and one or more region files. The following loads all the necessary data for Canada, Australia and the Scandinavian countries.

  require 'holidays'
  require 'holidays/ca'
  require 'holidays/au'
  require 'holidays/scandinavia'

Look up a date and see what’s happening.

  date = Date.civil(2008,4,25)

  Holidays.by_day(date, :au)   # lookup holidays on Apr 25, 2008 in Australia
  => [{:name => 'ANZAC Day', :date => #<Date:...>, :regions => [:au]}]

Each method returns an array of holiday hashes. Each hash contains:

:name (the local name of the holiday),
:date a Date object and
:regions (an array containing ISO country codes).

You can look up multiple regions at once…

  from = Date.civil(2008,7,1)
  to   = Date.civil(2008,7,31)

  # holidays in July, 2008 in Canada and the US.
  Holidays.between(from, to, :ca, :us)
  => [{:name => 'Canada Day',...}
      {:name => 'Independence Day',...}]

You can look up holidays on the day they are actually observed&hellip

  # Canada Day is July 1 except when July 1 is a Sunday, then it moves to
  # July 2

  date = Date.civil(2007,7,2)
  Holidays.by_day(date, :ca, :observed)
  => [{:name => 'Canada Day',...}]

You can choose to include informal holidays….

  # lookup  informal holidays in February
  from = Date.civil(2008,2,1)
  to   = Date.civil(2008,2,29)

  Holidays.between(from, to, :us, :informal)
  => [{:name => 'Valentine\'s Day',...}]

What are my *options?

The *options parameters can be passed in any order. Here are the options:

:region: By region. For example, return holidays in the Canada with :ca.
:region_: By region and sub regions. For example, return holidays in Germany and all its sub regions with :de_.
:region_sub: By sub region. Return national holidays in Spain plus holidays in Spain‘s Valencia region with :es_v.
:any: Any region. Return holidays from any loaded region.
:informal: Include informal holidays (like Valentine’s Day).
:observed: Return holidays on the day they are observed.

What are my holidays?

If you don’t see your country in the repository you’ll have to make your own definition file. Don’t worry, it’s easy.

Check out the definition file syntax in the documentation or look at an existing definition file.
Make your definition file.
Add your definition file to data/index.yaml.
Run rake defs:build_all (and rake test).
Consider sending your definition file to code at dunae dot ca so that everyone can benefit.

How do I get one?

To install the gem from RubyForge:

gem install holidays

Or, download the source .tgz file from http://rubyforge.org/projects/holidays/ and extract it somewhere in your include path.

Credits and code

Source: http://code.dunae.ca/svn/holidays
Docs: http://code.dunae.ca/holidays/doc

By Alex Dunae (dunae.ca, e-mail 'code' at the same domain), 2007.

Made on Vancouver Island.

code.dunae.ca