holidays 0.9.0

data/LICENSE

@@ -0,0 +1,21 @@
+==== Ruby Holidays Gem License
+
+Copyright (c) 2007 Alex Dunae
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README

@@ -0,0 +1,76 @@
+= Ruby Holidays Gem
+  
+A set of functions to deal with holidays in Ruby.
+
+Extends Ruby's built-in Date class and supports custom holiday definition lists.
+
+=== Installation
+
+To install the gem from RubyForge:
+
+  gem install holidays
+
+Or, download the source <tt>.tgz</tt> file from http://rubyforge.org/holidays and 
+extract it somewhere in your include path.
+
+=== Examples
+
+For more information, see the notes at the top of the Holidays module.
+
+==== Using the Holidays class
+Get all holidays on April 25, 2008 in Australia.
+  date = Date.civil(2008,4,25)
+
+  Holidays.on(date, :au)
+  => [{:name => 'ANZAC Day',...}]
+
+Get holidays that are observed on July 2, 2007 in British Columbia, Canada.
+  date = Date.civil(2007,7,2)
+
+  Holidays.on(date, :ca_bc, :observed)
+  => [{:name => 'Canada Day',...}]
+
+Get all holidays in July, 2008 in Canada and the US.
+  from = Date.civil(2008,7,1)
+  to   = Date.civil(2008,7,31)
+
+  Holidays.between(from, to, :ca, :us)
+  => [{:name => 'Canada Day',...}
+      {:name => 'Independence Day',...}]
+
+Get informal holidays in February.
+  from = Date.civil(2008,2,1)
+  to   = Date.civil(2008,2,15)
+
+  Holidays.between(from, to)
+  => [{:name => 'Valentine\'s Day',...}]
+
+
+==== Extending Ruby's Date class
+Check which holidays occur in Iceland on January 1, 2008.
+  d = Date.civil(2008,7,1)
+
+  d.holidays(:is)
+  => [{:name => 'Nýársdagur'}...]
+
+Lookup Canada Day in different regions.
+  d = Date.civil(2008,7,1)
+
+  d.holiday?(:ca)     # Canada
+  => true
+
+  d.holiday?(:ca_bc)  # British Columbia, Canada
+  => true
+
+  d.holiday?(:fr)     # France
+  => false
+
+=== Credits and code
+
+* Project page: http://code.dunae.ca/holidays
+* 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.

data/REFERENCES

@@ -0,0 +1,16 @@
+=== References
+
+I am grateful to the following sources.
+
+==== Date calculations
+* http://michaelthompson.org/technikos/holidays.php
+
+==== Easter calculations
+* http://www.assa.org.au/edm.html
+* http://www.smart.net/~mmontes/ec-cal.html
+
+==== World dates
+* http://www.un.org/geninfo/faq/factsheets/FS18.HTM
+* http://en.wikipedia.org/wiki/List_of_holidays_by_country
+
+

data/data/SYNTAX

@@ -0,0 +1,111 @@
+== Holiday Gem Definition Syntax
+
+All holidays are defined in YAML files in the <tt>data/</tt> directory.  These  definition files have three main parts: *months*, *methods* and *tests*. 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: ca_victoria_day(year)
+
+If a holiday can occur in different months (e.g. Easter) it can go in the '0' month.
+
+    0:
+    - name: Easter Monday
+      regions: [ca]
+      function: easter(year)+1
+
+Calculated-date functions take the year (integer) as a parameter and must return either a Date object or an integer representing the day of the month.
+
+
+=== Calculating observed dates
+
+Several built-in methods are available for holidays that are observed on varying dates.  For example, for a holiday that is observed on Monday if it falls on a weekend you could write:
+
+    7:
+    - name: Canada Day
+      regions: [ca]
+      mday: 1
+      observed: to_monday_if_weekend(date)
+
+Methods included in the Holidays module are:
+
+* Holidays#to_monday_if_sunday
+* Holidays#to_monday_if_weekend
+* Holidays#to_weekday_if_boxing_weekend
+* Holidays#to_weekday_if_weekend
+
+Observed-date functions take a Date object as a parameter and must return either a Date object or an integer representing the day of the month.
+
+
+
+=== Tests
+
+All definition files should have tests included.  In the YAML file, tests are just a block of Ruby code.
+
+  tests: |
+    {Date.civil(2008,1,1) => 'New Year\'s Day', 
+     Date.civil(2008,3,21) => 'Good Friday', 
+     Date.civil(2008,3,24) => 'Easter Monday',
+     Date.civil(2008,9,1) => 'Labour Day',
+     Date.civil(2008,12,25) => 'Christmas Day',
+     Date.civil(2008,12,26) => 'Boxing Day'}.each do |date, name|
+      assert_equal name, Holidays.on(date, :ca, :informal)[0][:name]
+    end
+
+    # Victoria Day
+    [Date.civil(2004,5,24), Date.civil(2005,5,23), Date.civil(2006,5,22),
+     Date.civil(2007,5,21), Date.civil(2008,5,19)].each do |date|
+      assert_equal 'Victoria Day', Holidays.on(date, :ca)[0][:name]
+    end

data/data/au.yaml

@@ -0,0 +1,106 @@
+# Australian holiday definitions for the Ruby Holiday gem.
+# Updated: 2008-11-29.
+# Sources:  
+# - http://en.wikipedia.org/wiki/Australian_public_holidays
+# - http://www.docep.wa.gov.au/lr/LabourRelations/Content/Wages%20and%20Conditions/Public%20Holidays/Public_Holidays.html
+# - http://www.wst.tas.gov.au/employment_info/public_holidays
+# TODO: missing some regional holidays
+--- 
+months:
+  0: 
+  - name: Good Friday
+    regions: [au]
+    function: easter(year)-2
+  - name: Easter Saturday
+    regions: [au]
+    function: easter(year)-1
+  - name: Easter Monday
+    regions: [au]
+    function: easter(year)+1
+  - name: Easter Monday
+    regions: [au_tas]
+    function: easter(year)+2
+  1: 
+  - name: New Year's Day
+    regions: [au]
+    mday: 1
+  - name: Australia Day
+    regions: [au]
+    mday: 26
+  3: 
+  - name: Labour Day
+    regions: [au_wa]
+    week: 1
+    wday: 1
+  - name: Eight Hours Day
+    regions: [au_tas]
+    week: 2
+    wday: 1
+  - name: Labour Day
+    regions: [au_vic]
+    week: 2
+    wday: 1
+  4: 
+  - name: ANZAC Day
+    regions: [au]
+    mday: 25
+  5: 
+  - name: Labour Day
+    regions: [au_qld]
+    week: 1
+    wday: 1
+  - name: May Day
+    regions: [au_nt]
+    week: 1
+    wday: 1
+  6: 
+  - name: Foundation Day
+    regions: [au_wa]
+    week: 1
+    wday: 1
+  - name: Queen's Birthday
+    regions: [au_act, au_nsw, au_sa, au_tas, au_nt, au_qld, au_vic]
+    week: 2
+    wday: 1
+  - name: Queensland Day
+    regions: [au_qld]
+    mday: 6
+    type: informal
+  10: 
+  - name: Labour Day
+    regions: [au_act, au_nsw, au_sa]
+    week: 1
+    wday: 1
+  12: 
+  - name: Christmas Day
+    regions: [au]
+    mday: 25
+  - name: Boxing Day
+    regions: [au]
+    mday: 26
+tests: |
+    {Date.civil(2007,1,1) => 'New Year\'s Day', 
+     Date.civil(2007,1,26) => 'Australia Day', 
+     Date.civil(2007,4,6) => 'Good Friday',
+     Date.civil(2007,4,9) => 'Easter Monday',
+     Date.civil(2007,4,25) => 'ANZAC Day',
+     Date.civil(2007,12,25) => 'Christmas Day',
+     Date.civil(2007,12,26) => 'Boxing Day'}.each do |date, name|
+      assert_equal name, Holidays.on(date, :au, :informal)[0][:name]
+    end
+
+    [:au_sa, :au_act, :au_nsw, :au_].each do |r|
+      assert_equal 'Labour Day', Date.civil(2007,10,1).holidays(r)[0][:name]
+    end
+
+    [:au_sa, :au_act, :au_nsw, :au_vic, :au_tas, :au_qld, :au_nt, :au_].each do |r|
+      assert_equal 'Queen\'s Birthday', Date.civil(2007,6,11).holidays(r)[0][:name]
+    end
+
+    assert_equal 'Labour Day', Date.civil(2007,3,5).holidays(:au_wa)[0][:name]
+    assert_equal 'Labour Day', Date.civil(2007,3,12).holidays(:au_vic)[0][:name]
+    assert_equal 'Labour Day', Date.civil(2007,5,7).holidays(:au_qld)[0][:name]
+
+    assert_equal 'May Day', Date.civil(2007,5,7).holidays(:au_nt)[0][:name]
+    
+    assert_equal 'Eight Hours Day', Date.civil(2007,3,12).holidays(:au_tas)[0][:name]

data/data/build_defs.rb

@@ -0,0 +1,152 @@
+require 'yaml'
+
+# Functions are stored in generated files as both Procs (:function) and 
+# Strings (:function_id). The String version makes comparisons of Procs much 
+# easier.
+#
+# TODO:
+# - better comparison of existing rules
+def parse_holiday_defs(module_name, files)
+  regions = []
+  rules_by_month = {}
+  custom_methods = {}
+  test_strs = []
+
+  files.each do |file|
+    def_file = YAML.load_file(file)
+    puts "  Loading #{file}"
+    if def_file['months']
+      puts "   - importing dates..."
+      def_file['months'].each do |month, definitions|
+        rules_by_month[month] = [] unless rules_by_month[month]
+        definitions.each do |definition|
+          rule = {}
+          definition.each do |key, val|
+            rule[key] = val
+          end
+
+          rule['regions'] = rule['regions'].collect { |r| r.to_sym }
+
+          regions << rule['regions']
+
+          exists = false
+          rules_by_month[month].each do |ex|
+            if ex['name'] == rule['name'] and ex['wday'] == rule['wday'] and ex['mday'] == rule['mday'] and ex['week'] == rule['week'] and ex['type'] == rule['type'] and ex['function'] == rule['function'] and ex['observed'] == rule['observed']
+              ex['regions'] << rule['regions'].flatten
+              exists = true
+            end
+          end
+          unless exists
+            rules_by_month[month] << rule
+          end
+
+        end # /defs.each
+      end
+    end
+
+    if def_file['methods']
+      puts "   - importing methods..."
+      def_file['methods'].each do |name, code|
+        custom_methods[name] = code
+      end # /methods.each
+    end
+
+    if def_file['tests']
+      puts "   - importing testings..."
+      test_strs << def_file['tests']
+    end
+  end
+
+  # Build the definitions
+  month_strs = []
+  rules_by_month.each do |month, rules|
+    month_str = "      #{month.to_s} => ["
+    rule_strings = []
+    rules.each do |rule|
+      str = '{'
+      if rule['mday']
+        str << ":mday => #{rule['mday']}, "
+      elsif rule['function']
+        str << ":function => lambda { |year| Holidays.#{rule['function']} }, "
+        str << ":function_id => \"#{rule['function'].to_s}\", "
+      else
+        str << ":wday => #{rule['wday']}, :week => #{rule['week']}, "
+      end
+
+      if rule['observed']
+        str << ":observed => lambda { |date| Holidays.#{rule['observed']}(date) }, "
+        str << ":observed_id => \"#{rule['observed'].to_s}\", "
+      end
+
+      if rule['type']
+        str << ":type => :#{rule['type']}, "
+      end
+
+      # shouldn't allow the same region twice
+      str << ":name => \"#{rule['name']}\", :regions => [:" + rule['regions'].uniq.join(', :') + "]}"
+      rule_strings << str
+    end
+    month_str << rule_strings.join(",\n            ") + "]"
+    month_strs << month_str
+  end
+
+  month_strs.join(",\n")
+
+
+  # Build the methods
+  method_str = ''
+  custom_methods.each do |key, code|
+    method_str << code + "\n\n"
+  end
+
+
+  # Build the module file
+  module_src =<<-EOM
+module Holidays
+  # This file is generated by the Ruby Holiday gem.
+  #
+  # Definitions loaded: #{files.join(', ')}
+  #
+  # To use the definitions in this file, load them right after you load the 
+  # Holiday gem:
+  #
+  #   require 'holidays'
+  #   require 'holidays/#{module_name.downcase}'
+  #
+  # More definitions are available at http://code.dunae.ca/holidays.
+  module #{module_name} # :nodoc:
+    DEFINED_REGIONS = [:#{regions.flatten.uniq.join(', :')}]
+
+    HOLIDAYS_BY_MONTH = {
+#{month_strs.join(",\n")}
+    }
+  end
+
+#{method_str}
+end
+
+Holidays.merge_defs(Holidays::#{module_name}::DEFINED_REGIONS, Holidays::#{module_name}::HOLIDAYS_BY_MONTH)
+EOM
+
+
+# Build the test file
+  unless test_strs.empty?
+    test_src =<<-EndOfTests
+require File.dirname(__FILE__) + '/../test_helper'
+require 'holidays/#{module_name.downcase}'
+
+# This file is generated by the Ruby Holiday gem.
+#
+# Definitions loaded: #{files.join(', ')}
+class #{module_name.capitalize}DefinitionTests < Test::Unit::TestCase  # :nodoc:
+
+  def test_#{module_name.downcase}
+#{test_strs.join("\n\n")}
+  end
+end
+    EndOfTests
+  end
+
+return module_src, test_src || ''
+
+end