From 208e2eea708ee436aedad898a092a90e081efbd2 Mon Sep 17 00:00:00 2001
From: Alex Dunae <alex@dunae.ca>
Date: Thu, 22 Nov 2007 00:47:08 +0000
Subject: [PATCH] Updated docs Renamed Date#is_holiday? to Date#holiday? Added
 Date#holidays

---
 CUSTOM DATES    | 20 ++++++++++++--------
 lib/holidays.rb | 24 +++++++++++++++++-------
 2 files changed, 29 insertions(+), 15 deletions(-)

diff --git a/CUSTOM DATES b/CUSTOM DATES
index f91abcb..0525746 100644
--- a/CUSTOM DATES	
+++ b/CUSTOM DATES	
@@ -2,11 +2,11 @@
   
 It's easy to add your own custom holiday definitions to the Holidays gem. In a nutshell:
 1. Build a definition file
-2. Run a <tt>rake</tt> to make a custom module
-3. <tt>require</tt> your new module
+2. Run the <tt>rake</tt> task to make a custom module
+3. <tt>require</tt> your new module and enjoy!
 
 
-== Building the YAML file
+== 1. Building the YAML file
 
 Definition files have two main parts: *months* and *methods*. Before you start, you may want to look some of the existing files at http://code.dunae.ca/svn/holidays/trunk/data.
 
@@ -21,8 +21,9 @@ Holidays are grouped by month from 1 through 12.  Each entry within a month can
 
 [<tt>wday</tt>]  Integer representing day of the month (1 through 31).
 
-For example, the following holiday is on the first of the month and available in the <tt>ca</tt>, <tt>us</tt> and <tt>au</tt> regions.
+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
@@ -34,8 +35,9 @@ For example, the following holiday is on the first of the month and available in
 [<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 the month and available in the <tt>ca</tt> region.
+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
@@ -74,20 +76,22 @@ Functions called in this manner must return either a Date object or an integer r
 
 
 
-== Building the definition module
+== 2. Building the definition module
 
 Once you have your YAML definition file you need to generate a Ruby module using <tt>rake</tt>.
 
 To build the module for school holidays
 
-  rake generate Custom custom.yaml
+  rake generate MyCustomDates custom.yaml
 
 
 Your module can include definitions from multiple YAML files.
 
-  rake generate Custom ca.yaml us.yaml mx.yaml custom.yaml
+  rake generate MyCustomDates ca.yaml us.yaml mx.yaml custom.yaml
 
 
+== 3. Using your custom definitions
+
 Your custom module is ready to use.
 
   require 'holidays'
diff --git a/lib/holidays.rb b/lib/holidays.rb
index f02a40d..80885dd 100644
--- a/lib/holidays.rb
+++ b/lib/holidays.rb
@@ -2,7 +2,7 @@ $:.unshift File.dirname(__FILE__)
 require 'holidays/easter'
 
 module Holidays
-  # Exception thrown when an unknown region is encountered.
+  # Exception thrown when an unknown region is requested.
   class UnkownRegionError < ArgumentError; end
 
   self.extend Easter
@@ -43,7 +43,7 @@ module Holidays
   # [<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])
+  def self.by_day(date, regions = :any)
     regions = validate_regions(regions)
 
     hbm = HOLIDAYS_BY_MONTH.values_at(0,date.mon).flatten
@@ -86,7 +86,7 @@ module Holidays
   # format.
   #--
   # TODO: do not take full months
-  def self.between(start_date, end_date, regions = [:ca,:us])
+  def self.between(start_date, end_date, regions = :any)
     regions = validate_regions(regions)
     holidays = []
 
@@ -141,15 +141,25 @@ end
 class Date
   include Holidays
 
-  # Check if the current date is a holiday in a given region.
+  # Get holidays on the current date.
   #
-  #   Date.civil('2008-01-01').is_holiday?(:ca)
-  #   => true
-  def is_holiday?(regions = :any)
+  # Returns an array.
+  #
+  #   Date.civil('2008-01-01').holidays(:ca)
+  #   => [{:name => 'Canada Day',...}]
+  def holidays(regions = :any)
     holidays = Holidays.by_day(self, regions)
     !holidays.empty?
   end
 
+  # Check if the current date is a holiday.
+  #
+  #   Date.civil('2008-01-01').holiday?(:ca)
+  #   => true
+  def holiday?(regions = :any)
+    !self.holidays(regions).empty?
+  end
+
   # Calculate day of the month based on the week number and the day of the 
   # week.
   #