From aeee76cadf30412bfc080a8cf2dcce4a0da3885a Mon Sep 17 00:00:00 2001 From: Alex Dunae Date: Tue, 20 Nov 2007 19:54:55 +0000 Subject: [PATCH] Added LICENSE and REFERENCES Updated docs --- LICENSE | 21 +++++++++++ README | 78 +++++++++++++++++++++++------------------ REFERENCES | 17 +++++++++ lib/holidays.rb | 93 ++++++++++++++++++++++++++++--------------------- rakefile.rb | 15 ++++---- 5 files changed, 143 insertions(+), 81 deletions(-) create mode 100644 LICENSE create mode 100644 REFERENCES diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..10635cd --- /dev/null +++ b/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. \ No newline at end of file diff --git a/README b/README index d5009a8..d254ab1 100644 --- a/README +++ b/README @@ -1,48 +1,58 @@ -holidays - by FIX (your name) - FIX (url) - -== DESCRIPTION: += Ruby Holidays Gem -FIX (describe your package) +A set of classes to deal with public/statutory holidays in Ruby. -== FEATURES/PROBLEMS: +Extends Ruby's built-in Date class and supports custom holiday definition lists. + +=== Examples + +==== Using the Holidays class + + # Get all holidays on April 25, 2008 in Australia + date = Date.civil(2008,4,25) + Holidays.by_day(date, :au) + => [{:name => 'ANZAC 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 => 'Idenpendence Day',...}] + + +==== Extending Ruby's Date class + require 'date' + require 'holidays' + + # Lookup Canada Day in the :ca region + Date.civil(2008,7,1).is_holiday?(:ca) + => true -* FIX (list of features or problems) + # Lookup Canada Day in the :fr region + Date.civil(2008,7,1).is_holiday?(:fr) + => false -== SYNOPSIS: +=== Installation - FIX (code sample of usage) +To install the gem from RubyForge: -== REQUIREMENTS: + gem install holidays -* FIX (list of requirements) +Or, download the source .tgz file from http://rubyforge.org/holidays/ and +extract it somewhere in your include path. -== INSTALL: +=== Custom holiday definitions -* FIX (sudo gem install, anything else) -== LICENSE: -(The MIT License) +=== Credits and code -Copyright (c) 2007 FIX +* Project page: http://code.dunae.ca/holidays +* Source: http://code.dunae.ca/svn/holidays +* Docs: http://code.dunae.ca/holidays/doc -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: +By Alex Dunae (dunae.ca, e-mail 'code' at the same domain), 2007. -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. +Made on Vancouver Island. \ No newline at end of file diff --git a/REFERENCES b/REFERENCES new file mode 100644 index 0000000..c5febf9 --- /dev/null +++ b/REFERENCES @@ -0,0 +1,17 @@ +=== 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://en.wikipedia.org/wiki/List_of_holidays_by_country + +==== US dates +* http://www.opm.gov/Operating_Status_Schedules/fedhol/index.asp +* http://www.smart.net/~mmontes/ushols.html diff --git a/lib/holidays.rb b/lib/holidays.rb index 50f0f26..cdba993 100644 --- a/lib/holidays.rb +++ b/lib/holidays.rb @@ -1,24 +1,16 @@ - -# === References -# ==== Calculations -# * http://michaelthompson.org/technikos/holidays.php -# ==== World -# * http://en.wikipedia.org/wiki/List_of_holidays_by_country -# ==== US -# * http://www.opm.gov/Operating_Status_Schedules/fedhol/index.asp -# * http://www.smart.net/~mmontes/ushols.html module Holidays - # Exception class for dealing with unknown regions. - class UnkownRegionError < StandardError; end + # Exception thrown when an unknown region is encountered. + class UnkownRegionError < ArgumentError; end - VERSION = '1.0.0' + VERSION = '0.9.0' - HOLIDAY_REGIONS = {:ca => 'Canada', :us => 'United States'} + REGIONS = [:ca, :us, :au, :gr, :fr] + HOLIDAYS_TYPES = [:bank, :statutory, :religious, :informal] WEEKS = {:first => 1, :second => 2, :third => 3, :fourth => 4, :fifth => 5, :last => -1} MONTH_LENGTHS = [ 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31] - # :wday: Day of the week (0 is Sunday, 6 is Saturday) + # :wday Day of the week (0 is Sunday, 6 is Saturday) HOLIDAYS_BY_MONTH = { 1 => [{:mday => 1, :name => 'New Year\'s Day', :regions => [:us, :ca, :au]}, {:mday => 1, :name => 'Australia Day', :regions => [:au]}, @@ -50,7 +42,21 @@ module Holidays {:mday => 26, :name => 'Boxing Day', :regions => [:ca,:gr,:au]}] } - # Get all holidays on a certain date + # Get all holidays on a given date. + # + # [date] A Date object. + # [regions] A symbol (e.g. :ca) or an array of symbols + # (e.g. [:ca, :ca_bc, :us]). + # + # Returns an array of hashes or nil. + # + # Each holiday is returned as a hash with the following fields: + # [:year] Integer. + # [:month] Integer. + # [:day] Integer. + # [:name] String. + # [:regions] An array of region symbols. + # [:types] An array of holiday-type symbols. def self.by_day(date, regions = [:ca, :us]) #raise(UnkownRegionError, "No holiday information is available for region '#{region}'") unless known_region?(region) @@ -83,6 +89,10 @@ module Holidays holidays end + # Get all holidays occuring between two dates, inclusively. + # + # Returns an array of hashes or nil. See Holidays#by_day for the output + # format. #-- # TODO: do not take full months def self.between(start_date, end_date, regions = [:ca,:us]) @@ -107,8 +117,6 @@ module Holidays end end end - - #puts dates.inspect holidays end @@ -139,22 +147,15 @@ module Holidays end - #def self.calculate_mday(yr, mo, wday, int) - # earliest = 1 + 7 * (int - 1) - - # wd = Date.civil(yr, mo, earliest).wday - # if wday == earliest - # off = 0 - # else - # if wday < wd - # off = wday + (7 - wd) - # else - # off = (wday + (7 - wd)) - 7 - # end - # end - - # earliest + off - # end +private + # Check regions against list of supported regions and return an array of + # symbols. + def self.check_regions(regions) # :nodoc: + regions = [regions] unless regions.kind_of?(Array) + regions = regions.collect { |r| r.to_sym } + raise UnkownRegionError unless regions.all? { |r| r == :any or REGIONS.include?(r) } + regions + end end @@ -162,29 +163,41 @@ end class Date include Holidays - # Check if the current date is a holiday. + # Check if the current date is a holiday in a given region. # # Date.civil('2008-01-01').is_holiday?(:ca) # => true - def is_holiday?(regions = [:ca, :us]) + def is_holiday?(regions = :any) holidays = Holidays.by_day(self, regions) holidays.empty? end - # Calculate the day of the month based on week and day of the week. + # Calculate day of the month based on the week number and the day of the + # week. # - # First Monday of Jan, 2008 + # ==== Parameters + # [year] Integer. + # [month] Integer from 1-12. + # [week] One of :first, :second, :third, + # :fourth or :fifth. + # [wday] Day of the week as an integer from 0 (Sunday) to 6 + # (Saturday) or as a symbol (e.g. :monday). + # + # Returns an integer. + # + # ===== Examples + # First Monday of January, 2008: # calculate_mday(2008, 1, :first, :monday) # - # Third Thursday of Dec, 2008 + # Third Thursday of December, 2008: # calculate_mday(2008, 12, :third, 4) # - # Last Monday of Jan, 2008 + # Last Monday of January, 2008: # calculate_mday(2008, 1, :last, 1) #-- # see http://www.irt.org/articles/js050/index.htm def self.calculate_mday(year, month, week, wday) - raise ArgumentError, "Week paramater must be one of Holidays::WEEKS." unless WEEKS.include?(week) + raise ArgumentError, "Week parameter must be one of Holidays::WEEKS." unless WEEKS.include?(week) week = WEEKS[week] diff --git a/rakefile.rb b/rakefile.rb index a12d0fe..3f044a6 100644 --- a/rakefile.rb +++ b/rakefile.rb @@ -19,26 +19,27 @@ Rake::RDocTask.new(:rdoc) do |rdoc| rdoc.title = 'Ruby Holidays Gem' rdoc.options << '--all' << '--inline-source' << '--line-numbers' rdoc.rdoc_files.include('README') - #rdoc.rdoc_files.include('LICENSE') + rdoc.rdoc_files.include('REFERENCES') + rdoc.rdoc_files.include('LICENSE') rdoc.rdoc_files.include('lib/*.rb') #rdoc.rdoc_files.include('lib/holidays/*.rb') end spec = Gem::Specification.new do |s| - s.name = "holidays" - s.version = "0.9.0" - s.author = "Alex Dunae" - s.homepage = "http://code.dunae.ca/holidays" + s.name = 'holidays' + s.version = '0.9.0' + s.author = 'Alex Dunae' + s.homepage = 'http://code.dunae.ca/holidays' s.platform = Gem::Platform::RUBY s.description = <<-EOF A collection of Ruby methods to deal with statutory and other holidays. You deserve a holiday! EOF - s.summary = "A collection of Ruby methods to deal with statutory and other holidays. You deserve a holiday!" + s.summary = 'A collection of Ruby methods to deal with statutory and other holidays. You deserve a holiday!' s.files = FileList["{lib}/**/*"].to_a s.test_files = Dir.glob('test/test_*.rb') s.has_rdoc = true - s.extra_rdoc_files = ["README", "LICENSE"] + s.extra_rdoc_files = ['README', 'REFERENCES', 'LICENSE'] s.rdoc_options << '--all' << '--inline-source' << '--line-numbers' end