stephenrichards-holiday_calendar 1.0.10

data/README.rb

@@ -0,0 +1,82 @@
+# == HolidayCalendar
+# 
+# 
+# HolidayCalendar is a library for determining public holidays in different countries.
+#
+# Its main features are:
+# * Can load standard holiday calendars for UK (England), France, U.S. Federal Holidays
+# * Can determine whether or not a particular day is a public holiday
+# * Can return the name of a public holiday for a particular date
+# * Can determine whether or not a date is a weekend
+# * Can determine whether or not a date is a working day (i.e. not a weekend nor a public holiday)
+# * Can determine the number of working days between two dates
+# * Can determine the date a specified number of working days before or after a specified date
+# * Users can define public holidays for other territories and add them into the calendar
+#
+#
+#
+# == Overview
+# The library is made up of two main elements:
+# * PublicHolidaySpecification
+# * HolidayCalendar
+#
+# A PublicHolidaySpecification defines the name of the holiday, which years it applies to, when
+# it is taken (e.g. 25th December or  third Thursday in November), and what to do if it falls on 
+# a weekend (ee.g. nothing, take it the last working day before, take it the next working day after).
+#
+# A HolidayCalendar has a name (the territory for which it is valid), defines which days are weekends, 
+# and contains an array of PublicHolidaySpecifications.  Given this data, the status of any date can be generated.
+#
+# A HolidayCalendar can be instantiated from the standard configurations distributed with this library, from a yaml
+# file provided by the user, or from an array of PublicHolidaySpecification objects.
+#
+# == Example 
+# This example loads the UK standard public holidays from the yaml file distributed with this gem.
+# It then loads a second copy, but modifies it for Scotland by removing the Boxing Day holiday and adding a 2nd January holiday.
+# Finally, various calls are made agains the two calendars.
+#
+#
+#        
+#        
+#           require 'holiday_calendar'
+#        
+#           en      = HolidayCalendar.load(:uk)
+#           sco     = HolidayCalendar.load(:uk)
+#           sco.delete('Boxing Day')
+#           sco << PublicHolidaySpecification.new(:name => "2nd Jan", :years => :all, :month => 1, :day => 2, :take_after => [:saturday, :sunday])
+#        
+#        
+#           dates = [
+#                    Date.new(2009,12,25),
+#                    Date.new(2009,12,26),
+#                    Date.new(2009,12,27),
+#                    Date.new(2009,12,28),
+#                    Date.new(2010,1,1),
+#                    Date.new(2010,1,4)
+#                ]
+#        
+#        
+#           dates.each do |date|
+#               if en.public_holiday?(date)
+#                   puts "#{date} is a public holiday in England: #{en.holiday_name(date)}"
+#               end
+#               if sco.public_holiday?(date)
+#                   puts "#{date} is a public holiday in Scotland: #{sco.holiday_name(date)}"
+#               end
+#           end
+#        
+#           puts "\n\nScottish Holidays in 2010"
+#           puts "==========================="
+#           hols = sco.list_for_year(2010)
+#           hols.each { |h| puts h }
+#
+# == Feedback
+#
+# Feedback on this project is welcomed, particularly sets of rules for different countries, or useful additions.
+# please mail me at dev@stephenrichards.eu
+#
+# Stephen Richards
+
+        
+
+

data/config/fr.yaml

@@ -0,0 +1,72 @@
+territory: fr
+
+weekend:
+    - saturday
+    - sunday
+
+public_holidays:
+    Jour de l'An:
+        years: all
+        month: 1
+        day: 1
+        
+
+    Fête du Travail:
+        years: all
+        month: 5
+        day: 1
+        
+
+    Fête de la Victoire 1945:
+        years: all
+        month: 5
+        day: 8
+        
+
+    lundi de Pâques:
+        years: all
+        class_method: ReligiousFestival.easter_monday
+        
+
+    Ascension catholique:
+        years: all
+        class_method: ReligiousFestival.ascension_day
+        
+        
+    Lundi de Pentecôte:
+        years: all
+        class_method: ReligiousFestival.whit_monday
+        
+
+    Fête nationale:
+        years: all
+        month: 7
+        day: 14
+        
+
+    Assomption:
+        years: all
+        month: 8
+        day: 15
+        
+
+    Toussaint:
+        years: all
+        month: 11
+        day: 1
+        
+ 
+    Armistice:
+        years: all
+        month: 11
+        day: 11
+        
+ 
+    Noel:
+        years: all
+        month: 12
+        day: 25
+        take_after:
+            - Saturday
+            - Sunday
+ 

data/config/uk.yaml

@@ -0,0 +1,54 @@
+# holiday calendar schema for UK
+  
+territory: uk
+weekend:
+    - saturday
+    - sunday
+
+public_holidays:
+    New Year's Day:
+        years: all
+        month: 1
+        day: 1
+        take_after:
+            - saturday
+            - sunday
+        
+    Good Friday:
+        years: all
+        class_method: ReligiousFestival.good_friday
+        
+    Easter Monday:
+        years: all
+        class_method: ReligiousFestival.easter_monday
+        
+    May Day:
+        years: all
+        month: 5
+        day: first_monday
+        
+    Spring Bank Holiday:
+        years: all
+        month: 5
+        day: last_monday
+        
+    Summer Bank Holiday:
+        years: all
+        month: 8
+        day: last_monday
+        
+    Christmas Day:
+        years: all
+        month: 12
+        day: 25
+        take_after:
+            - saturday
+            - sunday        
+        
+    Boxing Day:
+        years: all
+        month: 12
+        day: 26
+        take_after:
+            - saturday
+            - sunday

data/config/us.yaml

@@ -0,0 +1,71 @@
+territory: us
+weekend:
+    - saturday
+    - sunday
+
+public_holidays:
+    New Year's Day:
+        years: all
+        month: 1
+        day: 1
+        take_after:
+            - Sunday
+        take_before:
+            - Saturday
+            
+    Birthday of Martin Luther King, Jr.:
+        years: all
+        month: 1
+        day: third_monday
+        
+    Washington's Birthday:
+        years: all
+        month: 2
+        day: third_monday
+        
+    Memorial Day:
+        years: all
+        month: 5
+        day: last_monday
+        
+    Independence Day:
+        years: all
+        month: 7
+        day: 4
+        take_before: 
+            - Saturday
+        take_after: 
+            - Sunday
+        
+    Labor Day:
+        years: all
+        month: 9
+        day: first_monday
+        
+    Columbus Day:
+        years: all
+        month: 10
+        day: second_monday
+        
+    Veterans' Day:
+        years: all
+        month: 11
+        day: 11
+        take_before: 
+            - Saturday
+        take_after: 
+            - Sunday
+            
+    Thanksgiving Day:
+        years: all
+        month: 11
+        day: fourth_thursday
+        
+    Christmas Day:
+        years: all
+        month: 12
+        day: 25
+        take_before:
+            - Saturday
+        take_after: 
+            - Sunday

data/lib/holiday_calendar.rb

@@ -0,0 +1,522 @@
+require File.dirname(__FILE__) + '/public_holiday_specification'
+require File.dirname(__FILE__) + '/public_holiday'
+require File.dirname(__FILE__) + '/religious_festival'
+require 'yaml'
+
+
+
+# This class generates the public holiday date data from PublicHolidaySpecifications.  The class can be instantiated in one of three
+# ways:
+#
+# * HolidayCalendar.load(:territory)
+# * HolidayCalendar.load_file(yaml_file)
+# * HolidayCalendar.create(:territory, [weekends], [public_holidays])
+
+
+class HolidayCalendar
+    
+    attr_accessor   :territory, :weekend, :public_holiday_specifications
+    
+    @@keys_for_std_config   = [:territory]
+    @@keys_for_yaml         = [:filename]
+    @@keys_for_array        = [:territory, :weekend, :specs]
+    @@valid_day_names       = ['sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday']
+    
+    
+    # Instantiates a HolidayCalendar object with empty values
+    def initialize
+        @territory                      = nil
+        @weekend                        = nil
+        @public_holiday_specifications  = nil
+        @generated_years                = Array.new
+        @public_holiday_collection      = Array.new
+        @public_holiday_hash            = Hash.new    
+    end
+    
+    
+    # Instantiates a HolidayCalendar object from the standard configuration file for the specified territory
+    def self.load(territory)
+        cal = HolidayCalendar.new
+        self.instantiate_from_std_config(cal, territory)
+        cal
+    end    
+    
+
+    # Instantiates a HolidayCalendar object from an array of PublicHolidaySpecifications
+    #
+    # params
+    # * territory:          territory name as a symbol
+    # * weekend:            an array of days which are to be conisidered weekends.  Days can be specified as day numbers (Sunday = 0, Saturday = 6), or day names as symbols in lower case.
+    # * public_holidays:    an array of PublicHolidaySpecification objects  
+    def self.create(territory, weekend, public_holidays)
+        cal = HolidayCalendar.new
+        instantiate_from_array(cal, territory, weekend, public_holidays)
+        cal
+    end
+    
+  
+    # Instantiates a HolidayCalendar object from a yaml file containing the definition of holiday specifications.
+    def self.load_file(filename)
+        cal = self.new
+        self.instantiate_from_yaml(cal, filename)
+        cal
+    end    
+    
+    
+    
+    
+    
+    # Adds a new PublicHolidaySpecification or Array of PublicHollidaySpecifications to the Holiday Calendar  
+    #
+    # params
+    # * phs: must be a single PublicHolidaySpecification object or an array of PublicHolidaySpecification 
+    #   objects to be added to the calendar.
+    def <<(phs)
+        if phs.is_a? PublicHolidaySpecification
+            phs_array = [phs]
+        else
+            phs_array = phs
+        end
+        
+        if !all_occurrances_of(PublicHolidaySpecification, phs_array)
+            raise ArgumentError.new('you must pass a PublicHolidaySpecification or an array of PublicHolidaySpecification objects to << method of HolidayCalendar')
+        end
+        
+        @public_holiday_specifications += phs_array
+        @generated_years.clear
+        @public_holiday_collection.clear
+    end
+             
+        
+    # Deletes a public holiday by names from the holiday calendar.
+    # 
+    # params
+    # * public_holiday_name: a string containing the name of the public holiday to be deleted
+    #
+    # returns
+    # * true if a public holiday with that name existed in the calendar and was deleted
+    # * false if no public holiday with that name was found in the calendar
+    #
+    def delete(public_holiday_name)
+        holiday_found = false
+        index = 0
+        @public_holiday_specifications.each do |phs|
+            if phs.name == public_holiday_name
+                holiday_found = true
+                break
+            end
+            index += 1
+        end
+        @public_holiday_specifications.delete_at(index)
+        @generated_years.clear
+        @public_holiday_collection.clear
+        holiday_found
+    end
+    
+    
+    
+
+        
+    # Returns the count of public holidays 
+    #
+    def size
+        @public_holiday_specifications.size
+    end
+
+
+    # Returns true if the specified date is a weekend
+    #
+    def weekend?(date)
+        populate_public_holiday_collection_for_year(date.year)
+        @weekend.include?(date.wday)
+    end
+    
+    
+    # Returns true if the specified date is a public holiday
+    #
+    def public_holiday?(date)
+        return false if weekend?(date)                  # weekend are never public holidays
+        populate_public_holiday_collection_for_year(date.year)
+        
+        return true if @public_holiday_hash.has_key?(date)
+        return false
+    end
+
+    
+    
+    
+        
+    # Returns true if the specified date is neither a weekend nor a public holiday
+    #
+    def working_day?(date, repopulate = true)
+        if repopulate
+            populate_public_holiday_collection_for_year(date.year)
+        end
+        !weekend?(date) && !public_holiday?(date)
+    end
+        
+        
+    # Returns the count of the number of working days between two dates (does not count the start date as 1 day). 
+    #
+    def count_working_days_between(start_date, end_date)
+        populate_public_holiday_collection_for_year(start_date.year)
+        populate_public_holiday_collection_for_year(end_date.year)
+        if start_date >= end_date 
+            raise ArgumentError.new("start_date passed to HolidayCalendar.count_days_between() is not before end_date")
+        end
+        
+        working_day_count = 0
+        date = start_date
+        while date < end_date
+            date += 1
+            working_day_count += 1 if  working_day?(date)
+        end
+        working_day_count
+    end
+    
+    
+    
+    
+    # Returns a date a number of working days after a specified date
+    #
+    # params
+    # * start_date : the date at which to start counting
+    # * num_working_days : the number of working days to count
+    #
+    def working_days_after(start_date, num_working_days)
+        populate_public_holiday_collection_for_year(start_date.year)
+        working_days_offset(start_date, num_working_days, :forward)
+    end
+    
+    
+    
+    # Returns a date a number of working days before a specified date
+    #
+    # params
+    # * start_date : the date at which to start counting
+    # * num_working_days : the number of working days to count
+    #
+    def working_days_before(start_date, num_working_days)
+        populate_public_holiday_collection_for_year(start_date.year)
+        working_days_offset(start_date, num_working_days, :backward)
+    end    
+    
+    
+    # Returns an array of string descriptions of each of the PublicHolidaySpecifications in the calendar
+    #
+    def list
+        specs = Array.new
+        @public_holiday_specifications.each { |phs| specs << phs.to_s }
+        specs
+    end
+    
+    
+    # Returns an array of strings giving the date and the name of the holiday for each holiday in the year
+    #
+    def list_for_year(year)
+        populate_public_holiday_collection_for_year(year)
+        holiday_dates = Array.new
+        @public_holiday_collection.each do |ph|
+            holiday_dates << ph.to_s if ph.year == year
+        end
+        holiday_dates
+    end
+    
+    # Returns the name of the holiday for a particular date, or nil if the date is not a holiday
+    # 
+    # params
+    # * date: the date for which the holiday name is to be returned
+    # * date_adjusted_text: true, if the phrase 'carried forward from' or 'brought forward from' is to be included
+    #   in cases where the date of the holiday was adjusted because it fell on a weekend (or to be more precise, on 
+    #   a day specified in the take_before or take_after options of the PublicHolidaySpecification)
+    #
+    def holiday_name(date, date_adjusted_text = true)
+        populate_public_holiday_collection_for_year(date.year)
+        ph = @public_holiday_hash[date]
+        if ph.nil?
+            return nil
+        else
+            return ph.name(date_adjusted_text)
+        end
+    end
+    
+    
+    
+    private
+    
+    # returns true if array contains only instances of klass
+    def all_occurrances_of(klass, array)
+        array.each do |instance|
+            if !instance.instance_of?(klass)
+                return false
+            end
+        end
+        return true
+    end
+    
+    
+    
+    # read all yaml files in the config directory looking for one with a territory of the specified name, 
+    # and load it
+    def self.instantiate_from_std_config(cal, territory)
+        raise ArgumentError.new('No territory specified for HolidayCalendar.new in std_config mode') if territory.nil?
+        
+        territory = territory.to_s
+        yaml_files = Dir[File.dirname(__FILE__) + '/../config/*.yaml']
+        yaml_files.each do |yf|
+            begin
+                yaml_spec = YAML.load_file(yf)
+                next if yaml_spec['territory'] != territory
+                instantiate_from_yaml(cal, yf)
+            rescue => err
+                puts "ERROR while loading #{yf}"
+                raise
+            end    
+        end
+
+    end
+    
+    
+    def self.instantiate_from_yaml(cal, filename)
+        
+        
+        if !File.exist?(filename)
+            raise ArgumentError.new("The filename specified in HolidayCalender.new cannot be found: #{filename}")
+        end
+                
+        yaml_file_contents = YAML.load_file(filename)
+        validate_yaml_file_contents(cal, filename, yaml_file_contents)
+    end
+    
+    
+    def self.validate_yaml_file_contents(cal, filename, yaml_file_contents)
+        validate_and_populate_territory(cal, filename, yaml_file_contents)
+        validate_and_populate_weekend(cal, filename, yaml_file_contents)
+        validate_and_populate_public_holidays(cal, filename, yaml_file_contents)
+    end
+    
+    
+    def self.validate_and_populate_territory(cal, filename, yaml_file_contents)
+        if !yaml_file_contents.has_key? 'territory'
+            raise ArgumentError.new("YAML file #{filename} does not have a 'territory' setting")
+        end
+        cal.territory = yaml_file_contents['territory'].to_sym
+    end    
+    
+    
+    def self.validate_and_populate_weekend(cal, filename, yaml_file_contents)
+        raise ArgumentError.new("YAML file #{filename} does not have a 'weekend' setting") if !yaml_file_contents.has_key? 'weekend'
+        klass = yaml_file_contents['weekend'].class
+        raise ArgumentError.new("Invalid YAML file element 'weekend' - must be an Array, is #{klass}") if klass != Array
+            
+        weekend_array = Array.new
+        
+        yaml_file_contents['weekend'].each do |day|
+            day_num = @@valid_day_names.index(day.downcase)
+            raise ArgumentError.new("Invalid day specified as weekend: #{day}") if !day_num
+            weekend_array << day_num
+        end
+        cal.weekend = weekend_array
+    end        
+    
+        
+    def self.validate_and_populate_public_holidays(cal, filename, yaml_file_contents)
+        raise ArgumentError.new("YAML file #{filename} does not have a 'public_holidays' setting") if !yaml_file_contents.has_key? 'public_holidays'
+        klass = yaml_file_contents['public_holidays'].class
+        raise ArgumentError.new("Invalid YAML file element 'public_holidays' - must be an Hash, is #{klass}") if klass != Hash
+        
+        phs_array = Array.new
+        yaml_file_contents['public_holidays'].each do |name, yaml_spec|
+            phs = PublicHolidaySpecification.instantiate_from_yaml_definition(filename, name, yaml_spec)
+            phs_array<< phs
+        end
+        cal.public_holiday_specifications = phs_array
+    end
+    
+    
+    
+    def self.instantiate_from_array(cal, territory, weekend, public_holiday_specifications)
+        validate_territory(territory)
+        valid_weekend = validate_weekend(weekend)
+        validate_public_holiday_specifications(public_holiday_specifications)
+        
+        cal.territory = territory
+        cal.weekend = valid_weekend
+        cal.public_holiday_specifications = public_holiday_specifications
+    end
+    
+    
+    def self.validate_territory(territory)
+        raise ArgumentError.new('territory must be specified as symbol in HolidayCalendar.create') if !territory.is_a? Symbol
+    end
+    
+    
+    def self.validate_weekend(weekend)
+        raise ArgumentError.new('weekend must be specified as an Array in HolidayCalendar.create') if !weekend.is_a? Array
+        valid_weekend = Array.new
+        weekend.each do |day|
+            valid_weekend <<  self.normalise_day(day)
+        end
+        valid_weekend
+    end
+    
+    
+    def self.validate_public_holiday_specifications(public_holiday_specifications)
+        raise ArgumentError.new('public_holidays must be specified as an Array in HolidayCalendar.create') if !public_holiday_specifications.is_a? Array
+        public_holiday_specifications.each do |phs|
+            raise ArgumentError.new('public holidays must be an array of PublicHolidaySpecification objects in HolidayCalendar.create') if !phs.instance_of?(PublicHolidaySpecification)
+        end
+    end
+    
+    
+    
+    def self.normalise_day(day)
+        if day.is_a? Fixnum
+            if day >= 0 && day < 7
+                return day
+            end
+        end
+        if day.is_a? String
+            day.downcase!
+            if @@valid_day_names.include?(day)
+                return @@valid_day_names.index(day)
+            end
+        end
+        raise ArgumentError.new('Invalid weekend array passsed to HolidayCalendar.create: each day must be day number in range 0-6 or day name')
+    end
+    
+
+    
+    #  for the specified year  (and a year either side so as to cater for holidays that get taken before in the last day of the 
+    #  previous year, or taken after in the first day of the next year), iterates through the collection of public holiday 
+    #  specifications and
+    #  generates a PublicHoliday object for each one for the specified year and adds it to the collection
+    #  of public holidays.  
+    def populate_public_holiday_collection_for_year(year)
+        return if @generated_years.include?(year)                   # don't generate if we've already done it
+        @public_holiday_specifications.each do |phs|
+            next if !phs.applies_to_year?(year) 
+            @public_holiday_collection << PublicHoliday.new(phs, year)
+        end
+        @generated_years << year                                    # add to the list of years we've generated
+        @public_holiday_collection.sort!
+        populate_public_holiday_hash
+        adjust_carry_forwards
+        populate_holidays_brought_forward_from_next_year(year + 1)
+    end
+    
+    
+    # handles the edge case where early holidays in the following year are brought forward to this year.
+    # this method is called with the following year as a parameter
+    def populate_holidays_brought_forward_from_next_year(year)
+        return if @generated_years.include?(year)               # no need to do anything if the holidays have already been generated for this year
+        @public_holiday_specifications.each do |phs|
+            next if !phs.applies_to_year?(year)
+            ph = PublicHoliday.new(phs, year)
+            if ph.must_be_taken_before?
+                new_date = last_working_day_before(ph.date)
+                if new_date.year < ph.date.year
+                    ph.adjust_date(new_date)
+                    @public_holiday_hash[new_date] = ph
+                end
+            end
+        end
+    end
+
+
+
+    # refreshes the public_holiday_hash based on the contents of the public_holiday_collection
+    def populate_public_holiday_hash
+        @public_holiday_hash = Hash.new
+        @public_holiday_collection.each do |ph|
+            @public_holiday_hash[ph.date] = ph
+        end
+    end
+    
+    
+    # iterates through the public_holiday_collection, and where a public holiday falls on a day
+    # which is in the take_before or take_after array, then adjusts the date accordingly
+    def adjust_carry_forwards
+        @public_holiday_collection.each do |ph|
+            if ph.must_be_taken_after?
+                new_date = next_working_day_after(ph.date)
+                @public_holiday_hash.delete(ph.date)
+                ph.adjust_date(new_date)
+                @public_holiday_hash[new_date] = ph
+            elsif ph.must_be_taken_before?
+                new_date = last_working_day_before(ph.date)
+                @public_holiday_hash.delete(ph.date)
+                ph.adjust_date(new_date)
+                @public_holiday_hash[new_date] = ph            
+            end
+            
+        end
+    end
+            
+
+
+    def next_working_day_after(date)
+       date +=1
+       while !working_day?(date) do
+           date += 1
+       end
+       date
+    end
+    
+    
+    
+    def last_working_day_before(date)
+        date -= 1
+        while !working_day?(date) do
+            date -= 1
+        end
+        date
+    end
+
+
+
+
+
+    
+    
+    def working_days_offset(start_date, num_working_days, direction)
+        date = start_date
+        while num_working_days > 0 do
+            if direction == :forward
+                date += 1
+            else
+                date -= 1
+            end
+            # puts "#{date} #{num_working_days}  #{working_day?(date)}"
+            num_working_days -= 1 if working_day?(date)
+        end
+        date
+    end
+
+        
+end
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+