108 lines
2.9 KiB
Text
108 lines
2.9 KiB
Text
= Custom dates with the Ruby Holidays Gem
|
|
|
|
It's easy to add your own custom holiday definitions to the Holidays gem. In a nutshell:
|
|
1. Build a definition file
|
|
2. Run the <tt>rake</tt> task to make a custom module
|
|
3. <tt>require</tt> your new module and enjoy!
|
|
|
|
|
|
== 1. Building the YAML file
|
|
|
|
Definition files have two main parts: *months* and *methods*. Before you start, you may want to look some of the existing files at http://code.dunae.ca/svn/holidays/trunk/data.
|
|
|
|
=== Months
|
|
|
|
Holidays are grouped by month from 1 through 12. Each entry within a month can have several fields.
|
|
|
|
[<tt>name</tt>] The name of the holiday.
|
|
[<tt>regions</tt>] One or more region codes.
|
|
|
|
===== Dates defined by a fixed date (e.g. January 1st)
|
|
|
|
[<tt>wday</tt>] Integer representing day of the month (1 through 31).
|
|
|
|
For example, the following holiday is on the first of January and available in the <tt>ca</tt>, <tt>us</tt> and <tt>au</tt> regions.
|
|
|
|
1:
|
|
- name: New Year's Day
|
|
regions: [ca,us,au]
|
|
mday: 1
|
|
|
|
|
|
===== Dates defined by a week number (e.g. first Monday of a month)
|
|
|
|
[<tt>wday</tt>] Integer representing day of the week (0 = Sunday through 6 = Saturday).
|
|
[<tt>week</tt>] Integer representing week number (1 = first week, 3 = third week, -1 = last week),
|
|
|
|
|
|
For example, the following holiday is on the first Monday of September and available in the <tt>ca</tt> region.
|
|
|
|
9:
|
|
- name: Labour Day
|
|
regions: [ca]
|
|
week: 1
|
|
wday: 1
|
|
|
|
|
|
|
|
|
|
=== Calculating dates with methods
|
|
|
|
In addition to defining holidays by day or week, you can create custom methods to calculate a date.
|
|
|
|
For example, Canada celebrates Victoria Day, which falls on the Monday on or before May 24. So, under the <tt>methods</tt> section we could create a custom method that returns a Date object.
|
|
|
|
methods:
|
|
ca_victoria_day: |
|
|
def self.ca_victoria_day(year)
|
|
date = Date.civil(year,5,24)
|
|
if date.wday > 1
|
|
date -= (date.wday - 1)
|
|
elsif date.wday == 0
|
|
date -= 6
|
|
end
|
|
date
|
|
end
|
|
|
|
This would be represented in the <tt>months</tt> section as:
|
|
|
|
5:
|
|
- name: Victoria Day
|
|
regions: [ca]
|
|
function: lambda { |year| ca_victoria_day(year) }
|
|
|
|
|
|
Functions called in this manner must return either a Date object or an integer representing the day of the month.
|
|
|
|
|
|
|
|
== 2. Building the definition module
|
|
|
|
Once you have your YAML definition file you need to generate a Ruby module using <tt>rake</tt>.
|
|
|
|
To build the module for school holidays
|
|
|
|
rake generate MyCustomDates custom.yaml
|
|
|
|
|
|
Your module can include definitions from multiple YAML files.
|
|
|
|
rake generate MyCustomDates ca.yaml us.yaml mx.yaml custom.yaml
|
|
|
|
|
|
== 3. Using your custom definitions
|
|
|
|
Your custom module is ready to use.
|
|
|
|
require 'holidays'
|
|
require 'path/to/custom'
|
|
|
|
Holidays.by_day(date, :your_region)
|
|
|
|
|
|
|
|
=== Sharing
|
|
|
|
If you've built a definition file that others might enjoy, why not share it?
|
|
|
|
Send any definition files to 'code' at 'dunae.ca'.
|