Elixir library for finding which holidays fall on given dates.

Based on the Holidays Ruby Gem

The package can be installed as:

1. Add holidays to your list of dependencies in mix.exs:

   def deps do [{:holidays, "~> 0.1.1"}] end

iex> Holidays.on({2016, 1, 1}, [:us])
[%{name: "New Year's Day"}]

The on function gives a list of holidays for a date within specified regions.

Dates in Erlang (and therefore Elixir) are represented by the {year, month, day} tuple.

This module uses pattern matching as much as possible. So, when a holiday occurs on a fixed month and day every year, it will match on a clause that looks something like this:

defp do_on({_year, 1, 1}, :us), do: [%{name: "New Year's Day"}]

A holiday that occurs on a certain week and week day will match like this after calling a function to get the week and day atoms from the date. (The first parameter is the month.)

defp do_on(5, :last, :monday, :us), do: [%{name: "Memorial Day"}]

Regions are often country codes, like :us or :ca, but may also be entities such as UPS (:ups) or the New York Stock Exchange (:nyse). They can sometimes also be states/provinces, like :us_ca or :us_dc.

Holidays are defined within modules in the lib/holidays/definitions directory which use the holiday macro from Holidays.Define.

It's fairly easy to take yaml files from the original Ruby implementation and translate them into the Elixir definition modules. The yaml files are included in the root definitions folder. That would be a great place to contribute if there is a region you need which hasn't been translated yet. Just be sure to include some tests. There's even a handy holiday_test macro to make it super simple to assert that the expected holiday is returned on the given date and region.

The Holidays.DateCalculator.WeekendModifier contains functions ported from Ruby to support the observed property as found in the original project, but this hasn't been implemented in the Holidays module's code gen yet. The property does exist in the definition modules that have been translated so far.

The other feature from the Ruby project that could be implemented is the ability to specify a date range for the on function.

I also haven't figured out how to best support custom holiday definitions that aren't part of this library.

Also, if you have suggestions for anything I've done that doesn't make sense or could be done better, please let met know or send a pull request.

The Holidays module must be recompiled whenever changes are made to a definition module. When the holiday macro is called, the holiday is appended to the @holidays attribute of the main Holidays module. If it's already been compiled, you'll see an error like:

== Compilation error on file lib/holidays/definitions/us.ex ==
** (ArgumentError) could not call register_attribute on module Holidays because it was already compiled

I've been fixing that by calling mix clean and then trying the compile again.