stephenrichards-holiday_calendar 1.0.10

data/lib/modified_weekday.rb

@@ -0,0 +1,135 @@
+# This class encapsulates all the information needed to describe something like 
+# first monday, second thursday or last wednesday of a particular month.
+
+class ModifiedWeekday
+    
+    
+    @@valid_weekdays    = [:sunday, :monday, :tuesday, :wednesday, :thursday, :friday, :saturday]
+    @@valid_modifiers   = [:last, :first, :second, :third, :fourth]
+    
+    
+    attr_reader :weekday_name, :modifier, :wday, :weekday_occurrance, :expression, :is_last
+    
+    # Instantiate a ModifiedWeekday object from either an expression such as :first_monday, or a date object
+    #
+    # params
+    # * param : param can either be a valid expression or a date object.
+    #   * valid expressions are :xxxx_yyyyyy where xxxx is :first, :second, :third, :fourth, :last and yyyy is monday, tuesday, etc.
+    # 
+    def initialize(param)
+        @weekday_name  = nil
+        @modifier = nil
+        @wday = nil
+        @weekday_occurrance = nil    # 0 = last, 1 = first, 2 = second, etc.
+        @is_last = false
+        
+        
+        if param.is_a? Symbol
+            @expression = param
+            string_expr = @expression.to_s
+            string_modifier, string_weekday = string_expr.split('_')
+            @weekday_name = string_weekday.to_sym
+            @modifier = string_modifier.to_sym
+            validate_weekday
+            validate_modifier
+            @is_last = true if @modifier == :last
+        elsif param.is_a? Date
+            get_modifiers_from_date(param)
+        else
+            raise ArgumentError.new("Invalid Type passed to ModifiedWeekday.new: #{param.class}")
+        end
+    
+    end
+    
+    
+    def to_s
+        @modifier.to_s + "_" + @weekday_name.to_s
+    end
+    
+    
+    
+    def sort_value
+        sort_val = @weekday_occurrance * 10
+        sort_val = 50 if sort_val == 0
+        sort_val += @wday
+    end
+    
+
+
+    # Compare two ModifiedWeekday objects.  Objects are equal if the expression is the same, or the days are the same and the modifier is :last and / or is_last is true.
+    def ==(other)
+        return true if other.expression == self.expression
+        
+        if other.weekday_name == self.weekday_name
+            if other.is_last == true || other.modifier == :last
+                if self.is_last == true || self.modifier == :last
+                    return true
+                end
+            end
+        end
+        return false
+    end
+
+
+
+    private
+    
+    def get_modifiers_from_date(date)
+       @weekday_name = @@valid_weekdays[date.wday]
+       @wday = date.wday
+       @weekday_occurrance = get_weekday_occurrance(date)
+       determine_whether_last(date)
+       @modifier = make_modifier
+       @expression = (@modifier.to_s + '_' + @weekday_name.to_s).to_sym
+       
+    end
+    
+    
+    
+    def get_weekday_occurrance(date)
+        num_weeks = date.mday / 7
+        remainder = date.mday % 7
+        if remainder > 0
+            occurrance = num_weeks + 1
+        else
+            occurrance= num_weeks
+        end
+        occurrance
+    end
+    
+    
+    def determine_whether_last(date)
+       days_in_month = Date.new(date.year, date.month, -1).day
+       days_left = days_in_month - date.day
+       if days_left < 7
+           @is_last = true
+       end
+    end
+    
+    
+    
+    def make_modifier
+        modifier = @@valid_modifiers[@weekday_occurrance]
+        if !modifier && @is_last
+            modifier = :last
+        end
+        modifier
+    end
+    
+    
+    
+    def validate_weekday
+        if !@@valid_weekdays.include?(@weekday_name)
+            raise ArgumentError.new("Invalid Weekday component passed to ModifiedWeekday.new: #{@expression}")
+        end
+        @wday = @@valid_weekdays.index(@weekday_name)
+    end
+    
+    
+    def validate_modifier
+        if !@@valid_modifiers.include?(@modifier)
+            raise ArgumentError.new("Invalid weekday modifier passed to ModifiedWeekday.new: #{@expression}")
+        end
+        @weekday_occurrance = @@valid_modifiers.index(@modifier)
+    end
+end

data/lib/public_holiday.rb

@@ -0,0 +1,173 @@
+
+# Encapsulates a date which is a public holiday for a particular year derived from a 
+# PublicHolidaySpecification and a year
+
+class PublicHoliday
+    
+    include Comparable
+    
+    attr_reader     :year
+    attr_accessor   :date, :date_adjusted_text
+    attr_writer     :name
+
+    
+    # Instantiates a PublicHoliday object
+    # 
+    # params
+    # * public_holiday_specification: a PublicHolidaySpecification object
+    # * year: a year number
+    # 
+    
+    def initialize(public_holiday_specification, year)
+        
+        @year = year
+        @holiday = false
+        @date = nil
+        @name = nil
+        @take_before = Array.new
+        @take_after = Array.new
+        @date_adjusted = false
+        @date_adjusted_text = nil
+        
+        if public_holiday_specification.applies_to_year?(year)
+            @holiday = true
+            setup_public_holiday(public_holiday_specification, @year)
+        end
+    end
+    
+    
+    def <=>(other)
+        self.date <=> other.date
+    end
+    
+    
+    # returns the date and name of the holiday, and optionally, the date adjustedtext if any.
+    def to_s(date_adjusted_text = true)
+        description = "#{@date.strftime("%a %d %b %Y")} : #{self.name}"
+        # if date_adjusted_text  && @date_adjusted
+        #     description += " (#{@date_adjusted_text})"
+        # end
+        description
+    end
+    
+    
+    def name(date_adjusted_text = true)
+        description = @name
+        if date_adjusted_text  && @date_adjusted
+            description += " (#{@date_adjusted_text})"
+        end
+        description        
+    end
+    
+    
+    
+    # returns true if the day number of the holiday date is in the taken_before array
+    def must_be_taken_before?
+        return true if @take_before.include? @date.wday
+        return false
+    end
+    
+    
+    
+    def must_be_taken_after?
+        return true if @take_after.include? @date.wday
+        return false
+    end
+
+
+    def holiday?
+        @holiday
+    end
+
+
+
+    def adjust_date(new_date)
+        @date_adjusted = true
+        if new_date > @date
+            direction = 'carried'
+        else
+            direction  = 'brought'
+        end
+        @date_adjusted_text = "#{direction} forward from #{@date.strftime('%a %d %b %Y')}"
+        @date = new_date
+    end
+
+
+
+    private
+    def setup_public_holiday(phs, year)
+       @name = phs.name
+       if phs.uses_class_method?
+           @date = phs.klass.send(phs.method_name, year)
+       elsif phs.day.is_a? Fixnum
+           @date = Date.new(year, phs.month, phs.day)
+       else
+           @date = generate_date_from_expression(phs, year)
+       end
+       
+       @take_before = phs.take_before
+       @take_after = phs.take_after
+   end
+           
+
+   # generates an actual date for @year from the PublicHolidaySpecification when the specification is written as an expression
+   def generate_date_from_expression(phs, year)
+       if phs.day.class != ModifiedWeekday
+           raise RuntimeError.new("Error - expecting PublicHolidaySpecification.day to be a ModifiedWeekday: is a #{phs.day.class}")
+       end
+       month = phs.month
+       wday = phs.day.wday
+       occurrance = phs.day.weekday_occurrance
+
+       
+       if phs.day.modifier == :last
+           date = get_last_wday_in_month(year, month, wday)
+       else
+           date = get_nth_day_in_month(year, month, wday, occurrance)
+       end
+       date
+   end
+
+
+
+   # returns the date of the nth monday, tuesday, etc. in a month for a particular year
+   #
+   # params
+   # * year : the year for which the date is to be generated
+   # * month : the month number (1-12) for which the date is to be generated
+   # * wday : the wday number (Sunday = 0, Saturday = 6) for which the date is to be generated
+   # * n : the n in nth monday (range 1 - 4 inclusive)
+   #
+   def get_nth_day_in_month(year, month, wday, n)
+       first_day_of_month = Date.new(year, month, 1)
+       wday_of_first_day = first_day_of_month.wday
+       day_number = wday - wday_of_first_day + 1
+       day_number += 7 if day_number < 1
+       
+       # now add on 7 days for each 'n'
+       n -= 1
+       day_number += (n * 7)
+       
+       Date.new(year, month, day_number)
+   end
+       
+
+
+
+
+
+   # determines the date of the last specified weekday in a month
+   def get_last_wday_in_month(year, month, wday)
+       last_day_in_month = Date.new(year, month, -1)
+       wday_of_last_day = last_day_in_month.wday
+       wday_of_last_day += 7 if wday_of_last_day < wday
+       difference = wday_of_last_day - wday
+       date = last_day_in_month - difference
+       date
+   end
+
+    
+end
+        
+        
+        

data/lib/public_holiday_specification.rb

@@ -0,0 +1,294 @@
+require File.dirname(__FILE__) + '/modified_weekday'
+
+# Encapsulates the specification for a public Holiday, from which Named Public Holidays for any year can be generated.
+
+class PublicHolidaySpecification
+    include Enumerable
+    
+    attr_reader     :name, :day, :month, :uses_class_method, :klass, :method_name, :take_before, :take_after
+    
+    
+    @@month_names = {'January' => 1, 'February' => 2, 'March' => 3, 'April'=> 4,
+                     'May' => 5, 'June' => 6, 'July' => 7, 'August' => 8,
+                     'September' => 9, 'October' => 10, 'November' => 11, 'December' => 12}
+                     
+    @@valid_day_names = [:sunday, :monday, :tuesday, :wednesday, :thursday, :friday, :saturday]
+    
+    # Instantiates a PublicHolidaySpecification object.
+    #
+    # params:  key-value pairs as follows:
+    # * name:           Name given to this public holiday.  Mandatory.
+    # * years:          Either :all, a single year, or a range. Mandatory.
+    # * month:          Either an English month name, or month number in range 1-12.  Mandatory.
+    # * day:            Either a number, or a phrase like :first_monday, :third_tuesday, :last_thursday.  Mandatory.
+    # * take_after:     An array, specifying the names or the numbers of the days on which, if the holiday falls on this day, will
+    #                   be taken on the first working day after.  Defaults to an empty array, i.e., no adjustment takes place.
+    # * take_before:    An array, specifying the names or the numbers of the days on which, if the holiday falls on this day, will
+    #                   be taken on the last working day before.  Defaults to an empty array, i.e., no adjustment takes place.              
+    #
+    # e.g.
+    #                   phs = PublicHolidaySpecification.new(:name => 'Christmas', :years => :all, :month => 12, :day => 25, :take_after => ['saturday', 'sunday'])
+    #
+    # or
+    # * name:           Name given to this public holiday.  Mandatory.
+    # * years:          Either :all, a single year, or a range. Mandatory
+    # * class_method:   Name of a class method that takes a year and returns a date
+    # 
+    # e.g.
+    #                   phs = PublicHolidaySpecification.new(:name => 'Good Friday', :years => :all, :class_method => 'ReligiousFestival.good_friday')
+    # 
+    def initialize(params)
+        @name               = nil
+        @years              = nil
+        @month              = nil
+        @day                = nil
+        @uses_class_method  = false
+        @klass              = nil
+        @method_name        = nil
+        @take_after         = Array.new
+        @take_before        = Array.new
+        
+        validate_params(params)
+    end
+    
+    
+    # Instantiates a PublicHolidaySpecification from a yaml definition file
+    def self.instantiate_from_yaml_definition(filename, name, yaml_spec)
+        raise ArgumentError.new("Invalid definition of #{name} in public_holidays section of #{filename}") if !yaml_spec.is_a? Hash
+        params = Hash.new
+        params[:name] = name
+        yaml_spec.each do |key, value|
+            key = key.to_sym if key.is_a? String
+            unless key == :class_method
+                value = value.to_sym if value.is_a? String
+            end
+            params[key] = value
+        end
+        phs = PublicHolidaySpecification.new(params)
+        phs
+    end
+    
+    
+    # Returns true if a class method is used to calaculate the date a holiday falls on
+    def uses_class_method?
+        @uses_class_method
+    end
+
+
+
+
+    # Returns true if the years value for this PublicHolidaySpecification includes the specified year.
+    def applies_to_year?(year)
+        @years.include?(year)
+    end
+    
+    
+
+    def <=>(other)
+        self.sort_value <=> other.sort_value
+    end
+    
+
+    
+    
+    # Displays human_readable form of the PublicHolidaySpecification
+    def to_s
+        str = @name + "\n"
+        str += sprintf("  %014s: %s\n", 'years', @years)
+        if @uses_class_method
+            str += sprintf("  %14s: %s.%s\n\n", 'class_method', @klass, @method_name)
+        else
+            str += sprintf("  %14s: %s\n", 'month', @month)
+            str += sprintf("  %14s: %s\n", 'day', @day)
+            str += sprintf("  %14s: %s\n\n", 'carry_forward', @carry_forward)
+        end
+    end
+        
+    
+    private
+    def public_holiday_on_actual_date?(date)
+        result = false
+        if @years.include?(date.year)  && @month == date.month
+            if @day.is_a? ModifiedWeekday
+                result = true if ModifiedWeekday.new(date) == @day
+            else
+                result = true if @day == date.day
+            end
+        end
+        result
+    end        
+    
+    
+    
+    
+    def validate_params(params)
+            
+        params.each do |key, value|
+            case key
+            when :name
+                @name = value
+            when :years
+                @years = validate_years(value)
+            when :month
+                @month = validate_month(value)
+            when :day
+                @day = validate_day(value)
+            when :take_before
+                @take_before = validate_take_before_after(value)
+            when :take_after
+                @take_after = validate_take_before_after(value)
+            when :class_method
+                validate_class_method(value)
+            else
+                raise ArgumentError.new("Invalid parameter passed to PublicHolidaySpecification.new: #{key} => #{value}")
+            end
+        end
+
+        missing_params = any_mandatory_params_nil?
+        if missing_params.size != 0
+            raise ArgumentError.new("Mandatory parameters are missing in a call to PublicHolidaySpecification.new: #{missing_params.join(', ')}")
+        end 
+    end
+    
+    
+    def validate_class_method(value)
+       class_method =  value
+       classname, method_name = value.split('.')
+       klass = Kernel.const_get(classname)
+       
+       begin
+           valid_method = klass.respond_to?(method_name)
+       rescue NameError => err
+           puts "Unknown Class passed to PublicHolidaySpecification.new as class_method parameter: #{class_method}"
+           raise
+       end
+       
+       if !valid_method
+           raise NameError.new("Unknown method passed to PublicHolidaySpecification.new as class_method parameter: #{class_method}")
+       end
+       
+       @uses_class_method = true
+       @klass = klass
+       @method_name = method_name
+    end
+    
+    
+    
+    
+    
+    def validate_years(value)
+        if value == :all
+            @years = (0..9999)
+        elsif value.class == Fixnum
+            @years = (value..value)
+        elsif value.class == Range
+            @years = value
+        else
+            raise ArgumentError.new("Invalid value passed as years parameter. Must be a Range, Fixnum or :all")
+        end
+    end
+    
+    
+    
+    def validate_month(month)
+        if month.is_a?(String)   &&   @@month_names.has_key?(month)
+            @month = @@month_names[month]
+        elsif month.is_a?(Fixnum)  && (1..12).include?(month)
+            @month = month
+        else
+            raise ArgumentError.new("Invalid month passed to PublicHolidaySpecification.new: #{month}")
+        end
+    end
+    
+    
+    
+    def validate_day(day)
+        if day.is_a?(Symbol)
+            @day = ModifiedWeekday.new(day)
+        elsif day.is_a?(Fixnum)  && (1..31).include?(day)
+            @day = day
+        else
+            raise ArgumentError.new("Invalid value passed as :day parameter to PublicHolidaySpecification.new: #{day}")
+        end
+    end
+    
+    # 
+    # def validate_carry_forward(value)
+    #     if !value.is_a?(TrueClass)  &&  !value.is_a?(FalseClass)
+    #         raise ArgumentError.new(':carry_forward value passed to PublicHolidaySpecification.new must be true or false')
+    #     end
+    #     @carry_forward = value
+    # end
+        
+    # validates parameters passed with the take_before or take_after keywords, and returns an array of day numbers
+    def validate_take_before_after(day_array)
+        if !day_array.is_a? Array
+            raise ArgumentError.new('take_before or take_after parameters must be an array')
+        end
+        
+        day_number_array = Array.new
+        day_array.each do |day|
+            day_number_array << validate_day_name_or_number(day)
+        end
+        day_number_array
+    end
+    
+    
+    def validate_day_name_or_number(day)
+        day_number = nil
+        if day.is_a? Fixnum
+            day_number = validate_day_number(day)
+        else 
+            day_number = validate_day_name(day)
+        end
+        day_number
+    end     
+    
+    
+    def validate_day_number(day)
+        if day < 0 || day > 6
+            raise ArgumentError.new('day number passed as take_before and take_after parameters must be in range 0-6')
+        end
+        day
+    end
+    
+    
+    def validate_day_name(day)
+        day_number = nil
+        if day.is_a? String
+            day_sym = day.downcase.to_sym
+        elsif !day.is_a? Symbol
+            raise ArgumentError.new("day passed to take_before and take_after must be a Number, String or Symbol.  Is #{day.class}")
+        else
+            day_sym = day
+        end
+        day_number = @@valid_day_names.index(day_sym)
+        if day_number.nil?
+            raise ArgumentError.new("#{day} is not a valid day name")
+        end
+        day_number
+    end
+        
+        
+        
+    
+    
+        
+    def any_mandatory_params_nil?
+        return_array = []
+        return_array << :name if !@name
+        return_array << :years if !@years
+        if !@uses_class_method
+            return_array << :month if !@month
+            return_array << :day if !@day
+        end
+        return_array
+    end
+    
+end
+                
+        
+        
+    
+    
+