Added LICENSE and REFERENCES

Updated docs

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.

README

@@ -1,48 +1,58 @@
-holidays
+= Ruby Holidays Gem
-    by FIX (your name)
-    FIX (url)
   
-== DESCRIPTION:
+A set of classes to deal with public/statutory holidays in Ruby.
 
-FIX (describe your package)
+Extends Ruby's built-in Date class and supports custom holiday definition lists.
 
-== FEATURES/PROBLEMS:
+=== Examples
 
-* FIX (list of features or problems)
+==== Using the Holidays class
 
-== SYNOPSIS:
+  # Get all holidays on April 25, 2008 in Australia
+  date = Date.civil(2008,4,25)
+  Holidays.by_day(date, :au)
+  => [{:name => 'ANZAC Day',...}]
 
-  FIX (code sample of usage)
 
-== REQUIREMENTS:
+  # 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',...}]
 
-* FIX (list of requirements)
 
-== INSTALL:
+==== Extending Ruby's Date class
+  require 'date'
+  require 'holidays'
 
-* FIX (sudo gem install, anything else)
+  # Lookup Canada Day in the :ca region
+  Date.civil(2008,7,1).is_holiday?(:ca)
+  => true
   
-== LICENSE:
+  # Lookup Canada Day in the :fr region
+  Date.civil(2008,7,1).is_holiday?(:fr)
+  => false
 
-(The MIT License)
+=== Installation
 
-Copyright (c) 2007 FIX
+To install the gem from RubyForge:
 
-Permission is hereby granted, free of charge, to any person obtaining
+  gem install holidays
-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
+Or, download the source <tt>.tgz</tt> file from http://rubyforge.org/holidays/ and 
-included in all copies or substantial portions of the Software.
+extract it somewhere in your include path.
 
-THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+=== Custom holiday definitions
-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,
+=== Credits and code
-TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+
-SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+* 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.

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

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.
+  # Exception thrown when an unknown region is encountered.
-  class UnkownRegionError < StandardError; end
+  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.
+  #
+  # [<tt>date</tt>]    A Date object.
+  # [<tt>regions</tt>] A symbol (e.g. <tt>:ca</tt>) or an array of symbols 
+  #                    (e.g. <tt>[:ca, :ca_bc, :us]</tt>).
+  #
+  # Returns an array of hashes or nil.
+  #
+  # Each holiday is returned as a hash with the following fields:
+  # [<tt>:year</tt>]    Integer.
+  # [<tt>:month</tt>]   Integer.
+  # [<tt>:day</tt>]     Integer.
+  # [<tt>:name</tt>]    String.
+  # [<tt>:regions</tt>] An array of region symbols.
+  # [<tt>:types</tt>]   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)
+private
-  #  earliest = 1 + 7 * (int - 1)
+  # Check regions against list of supported regions and return an array of 
-
+  # symbols.
-  #  wd = Date.civil(yr, mo, earliest).wday
+  def self.check_regions(regions) # :nodoc:
-  #  if wday == earliest
+    regions = [regions] unless regions.kind_of?(Array)
-  #    off = 0
+    regions = regions.collect { |r| r.to_sym }
-  #  else
+    raise UnkownRegionError unless regions.all? { |r| r == :any or REGIONS.include?(r) }
-  #    if wday < wd
+    regions
-  #      off = wday + (7 - wd)
+  end
-  #    else
-  #      off = (wday + (7 - wd)) - 7
-  #    end
-  #  end
-
-  #  earliest + off
- # 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
+  # [<tt>year</tt>] Integer.
+  # [<tt>month</tt>] Integer from 1-12.
+  # [<tt>week</tt>] One of <tt>:first</tt>, <tt>:second</tt>, <tt>:third</tt>,
+  #                 <tt>:fourth</tt> or <tt>:fifth</tt>.
+  # [<tt>wday</tt>] Day of the week as an integer from 0 (Sunday) to 6
+  #                 (Saturday) or as a symbol (e.g. <tt>:monday</tt>).
+  #
+  # 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]
 

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.name = 'holidays'
-  s.version = "0.9.0"
+  s.version = '0.9.0'
-  s.author = "Alex Dunae"
+  s.author = 'Alex Dunae'
-  s.homepage = "http://code.dunae.ca/holidays"
+  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