recurrence 0.1.5 → 1.0.0

data/.gitignore

@@ -1,2 +1,3 @@
 *.gem
-.bundle
+.bundle
+html

data/Gemfile

@@ -1,6 +1,3 @@
 source :rubygems
 
-gem "rake"
-gem "rspec", "2.0.0.beta.22"
-gem "activesupport", :require => "active_support/all"
-gem "i18n"
+gemspec

data/Gemfile.lock

@@ -1,26 +1,42 @@
+PATH
+  remote: .
+  specs:
+    recurrence (0.1.5)
+      activesupport (>= 3.0.0)
+
 GEM
   remote: http://rubygems.org/
   specs:
-    activesupport (3.0.0)
+    activesupport (3.0.2)
+    archive-tar-minitar (0.5.2)
+    columnize (0.3.2)
     diff-lcs (1.1.2)
-    i18n (0.4.1)
-    rake (0.8.7)
-    rspec (2.0.0.beta.22)
-      rspec-core (= 2.0.0.beta.22)
-      rspec-expectations (= 2.0.0.beta.22)
-      rspec-mocks (= 2.0.0.beta.22)
-    rspec-core (2.0.0.beta.22)
-    rspec-expectations (2.0.0.beta.22)
-      diff-lcs (>= 1.1.2)
-    rspec-mocks (2.0.0.beta.22)
-      rspec-core (= 2.0.0.beta.22)
-      rspec-expectations (= 2.0.0.beta.22)
+    linecache19 (0.5.11)
+      ruby_core_source (>= 0.1.4)
+    rspec (2.1.0)
+      rspec-core (~> 2.1.0)
+      rspec-expectations (~> 2.1.0)
+      rspec-mocks (~> 2.1.0)
+    rspec-core (2.1.0)
+    rspec-expectations (2.1.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.1.0)
+    ruby-debug-base19 (0.11.24)
+      columnize (>= 0.3.1)
+      linecache19 (>= 0.5.11)
+      ruby_core_source (>= 0.1.4)
+    ruby-debug19 (0.11.6)
+      columnize (>= 0.3.1)
+      linecache19 (>= 0.5.11)
+      ruby-debug-base19 (>= 0.11.19)
+    ruby_core_source (0.1.4)
+      archive-tar-minitar (>= 0.5.2)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  activesupport
-  i18n
-  rake
-  rspec (= 2.0.0.beta.22)
+  activesupport (>= 3.0.0)
+  recurrence!
+  rspec (>= 2.0.0)
+  ruby-debug19

data/History.txt

@@ -64,4 +64,11 @@
 == 0.1.5 2010-11-03
 
 * Recurrence.default_starts_date is now configurable; pass in a String or block
-* Add #options reader so we'll be able to use Recurrence with ActiveRecord.composed_of
+* Add Recurrence#options reader so we'll be able to use Recurrence with ActiveRecord.composed_of
+
+== 1.0.0 2010-11-16
+
+* Recurrence#each returns an enumerator when no block is given
+* Recurrence now includes Enumerable
+* The public API is now documented
+* Remove support for Rails plugin

data/README.rdoc

@@ -0,0 +1,124 @@
+= Recurrence
+
+A simple library to handle recurring events.
+
+== Installation
+
+  gem install recurrence
+
+== Usage
+
+  require "rubygems"
+  require "recurrence"
+
+  # Daily
+  r = Recurrence.new(:every => :day)
+  r = Recurrence.new(:every => :day, :interval => 9)
+  r = Recurrence.daily(options = {})
+
+  # Weekly
+  r = Recurrence.new(:every => :week, :on => 5)
+  r = Recurrence.new(:every => :week, :on => :monday)
+  r = Recurrence.new(:every => :week, :on => [:monday, :friday])
+  r = Recurrence.new(:every => :week, :on => [:monday, :wednesday, :friday])
+  r = Recurrence.new(:every => :week, :on => :friday, :interval => 2)
+  r = Recurrence.weekly(:on => :thursday)
+
+  # Monthly by month day
+  r = Recurrence.new(:every => :month, :on => 15)
+  r = Recurrence.new(:every => :month, :on => 31)
+  r = Recurrence.new(:every => :month, :on => 7, :interval => 2)
+  r = Recurrence.new(:every => :month, :on => 7, :interval => :monthly)
+  r = Recurrence.new(:every => :month, :on => 7, :interval => :bimonthly)
+  r = Recurrence.monthly(:on => 31)
+
+  # Monthly by week day
+  r = Recurrence.new(:every => :month, :on => :first, :weekday => :sunday)
+  r = Recurrence.new(:every => :month, :on => :third, :weekday => :monday)
+  r = Recurrence.new(:every => :month, :on => :last,  :weekday => :friday)
+  r = Recurrence.new(:every => :month, :on => :last,  :weekday => :friday, :interval => 2)
+  r = Recurrence.new(:every => :month, :on => :last,  :weekday => :friday, :interval => :quarterly)
+  r = Recurrence.new(:every => :month, :on => :last,  :weekday => :friday, :interval => :semesterly)
+
+  # Yearly
+  r = Recurrence.new(:every => :year, :on => [7, 4]) # => [month, day]
+  r = Recurrence.new(:every => :year, :on => [10, 31], :interval => 3)
+  r = Recurrence.new(:every => :year, :on => [:jan, 31])
+  r = Recurrence.new(:every => :year, :on => [:january, 31])
+  r = Recurrence.yearly(:on => [:january, 31])
+
+  # Limit recurrence
+  # :starts defaults to Date.today
+  # :until defaults to 2037-12-31
+  r = Recurrence.new(:every => :day, :starts => Date.today)
+  r = Recurrence.new(:every => :day, :until => '2010-01-31')
+  r = Recurrence.new(:every => :day, :starts => Date.today, :until => '2010-01-31')
+
+  # Getting an array with all events
+  r.events.each {|date| puts date.to_s }  # => Memoized array
+  r.events!.each {|date| puts date.to_s } # => reset items cache and re-execute it
+  r.events(:starts => '2009-01-01').each {|date| puts date.to_s }
+  r.events(:until => '2009-01-10').each {|date| puts date.to_s }
+  r.events(:starts => '2009-01-05', :until => '2009-01-10').each {|date| puts date.to_s }
+
+  # Iterating events
+  r.each { |date| puts date.to_s } # => Use items method
+  r.each! { |date| puts date.to_s } # => Use items! method
+
+  # Check if a date is included
+  r.include?(Date.today) # => true or false
+  r.include?('2008-09-21')
+
+  # Get next available date
+  r.next   # => Keep the original date object
+  r.next! # => Change the internal date object to the next available date
+
+== Troubleshooting
+
+If you're having problems because already have a class/module called Recurrence that is conflicting with this gem, you can require the namespace and create a class that inherits from <tt>SimplesIdeias::Recurrence</tt>.
+
+  require "recurrence/namespace"
+
+  class RecurrentEvent < SimplesIdeias::Recurrence
+  end
+
+  r = RecurrentEvent.new(:every => :day)
+
+If you're using Rails/Bundler or something like that, remember to override the <tt>:require</tt> option.
+
+  # Gemfile
+  source :rubygems
+
+  gem "recurrence", :require => "recurrence/namespace"
+
+== Maintainer
+
+* Nando Vieira (http://nandovieira.com.br)
+
+== Contributors
+
+* José Valim (http://plataformatec.com.br)
+* Maxim Chernyak (http://mediumexposure.com)
+
+== License
+
+(The MIT License)
+
+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.

data/Rakefile

@@ -3,3 +3,9 @@ Bundler::GemHelper.install_tasks
 
 require "rspec/core/rake_task"
 RSpec::Core::RakeTask.new
+
+require "rake/rdoctask"
+Rake::RDocTask.new do |rd|
+ rd.main = "README.rdoc"
+ rd.rdoc_files.include("README.rdoc", "lib/**/*.rb", "History.txt", "License.txt")
+end

data/lib/recurrence.rb

@@ -1,4 +1,22 @@
 require "recurrence/namespace"
 
+# The default namespace. If you already have Recurrence constant set on your codebase,
+# you can inherit from SimplesIdeias::Recurrence and have your own namespace.
+#
+#   require "recurrence/namespace"
+#
+#   class RecurrentEvent < SimplesIdeias::Recurrence
+#   end
+#
+#   r = RecurrentEvent.new(:every => :day)
+#
+# Remember require <tt>recurrence/namespace</tt> instead of just <tt>recurrence</tt>.
+# If you’re using Rails/Bundler or something like that, remember to override the
+# <tt>:require</tt> option.
+#
+#   # Gemfile
+#   source :rubygems
+#   gem "recurrence", :require => "recurrence/namespace"
+#
 class Recurrence < SimplesIdeias::Recurrence
 end

data/lib/recurrence/event.rb

@@ -1,6 +1,6 @@
 module SimplesIdeias
   class Recurrence
-    module Event
+    module Event # :nodoc: all
       autoload :Base,     "recurrence/event/base"
       autoload :Daily,    "recurrence/event/daily"
       autoload :Monthly,  "recurrence/event/monthly"

data/lib/recurrence/event/base.rb

@@ -1,6 +1,6 @@
 module SimplesIdeias
   class Recurrence
-    module Event
+    module Event # :nodoc: all
       class Base
         CARDINALS = %w(first second third fourth fifth)
         DAYS = %w(sunday monday tuesday wednesday thursday friday saturday)
@@ -8,7 +8,7 @@ module SimplesIdeias
         attr_accessor :start_date
 
         def initialize(options={})
-          every, options = nil, every if every.is_a?(Hash)
+          every, options = nil, every if every.kind_of?(Hash)
 
           @options    = options
           @date       = options[:starts]
@@ -59,7 +59,7 @@ module SimplesIdeias
 
         # Common validation for inherited classes.
         #
-        def valid_month_day?(day) #:nodoc:
+        def valid_month_day?(day)
           raise ArgumentError, "invalid day #{day}" unless (1..31).include?(day)
         end
 

data/lib/recurrence/event/daily.rb

@@ -1,7 +1,7 @@
 module SimplesIdeias
   class Recurrence
     module Event
-      class Daily < Base
+      class Daily < Base # :nodoc: all
         protected
         def next_in_recurrence
           date  = @date.to_date

data/lib/recurrence/event/monthly.rb

@@ -1,11 +1,11 @@
 module SimplesIdeias
   class Recurrence
     module Event
-      class Monthly < Base
+      class Monthly < Base # :nodoc: all
         INTERVALS = {
-          :monthly => 1,
-          :bimonthly => 2,
-          :quarterly => 3,
+          :monthly    => 1,
+          :bimonthly  => 2,
+          :quarterly  => 3,
           :semesterly => 6
         }
 
@@ -28,7 +28,7 @@ module SimplesIdeias
             valid_month_day?(@options[:on])
           end
 
-          if @options[:interval].is_a?(Symbol)
+          if @options[:interval].kind_of?(Symbol)
             valid_interval?(@options[:interval])
             @options[:interval] = INTERVALS[@options[:interval]]
           end
@@ -88,15 +88,15 @@ module SimplesIdeias
         end
 
         private
-        def valid_cardinal?(cardinal) #:nodoc:
+        def valid_cardinal?(cardinal)
           raise ArgumentError, "invalid cardinal #{cardinal}" unless CARDINALS.include?(cardinal.to_s)
         end
 
-        def valid_interval?(interval) #:nodoc:
+        def valid_interval?(interval)
           raise ArgumentError, "invalid cardinal #{interval}" unless INTERVALS.key?(interval)
         end
 
-        def valid_week?(week) #:nodoc:
+        def valid_week?(week)
           raise ArgumentError, "invalid week #{week}" unless (1..5).include?(week)
         end
       end

data/lib/recurrence/event/weekly.rb

@@ -1,7 +1,7 @@
 module SimplesIdeias
   class Recurrence
     module Event
-      class Weekly < Base
+      class Weekly < Base # :nodoc: all
         protected
         def validate
           @options[:on] = Array.wrap(@options[:on]).inject([]) do |days, value|

data/lib/recurrence/event/yearly.rb

@@ -1,7 +1,7 @@
 module SimplesIdeias
   class Recurrence
     module Event
-      class Yearly < Base
+      class Yearly < Base # :nodoc: all
         MONTHS = {
           "jan" => 1, "january" => 1,
           "feb" => 2, "february" => 2,
@@ -48,11 +48,11 @@ module SimplesIdeias
         end
 
         private
-        def valid_month?(month) #:nodoc:
+        def valid_month?(month)
           raise ArgumentError, "invalid month #{month}" unless (1..12).include?(month)
         end
 
-        def valid_month_name?(month) #:nodoc:
+        def valid_month_name?(month)
           raise ArgumentError, "invalid month #{month}" unless MONTHS.keys.include?(month.to_s)
         end
       end

data/lib/recurrence/namespace.rb

@@ -1,94 +1,167 @@
 require "date"
 require "active_support/all"
+require "enumerator"
 
 module SimplesIdeias
   class Recurrence
-    autoload :Event, "recurrence/event"
-    autoload :Version, "recurrence/version"
+    autoload :Event,    "recurrence/event"
+    autoload :Version,  "recurrence/version"
 
+    include Enumerable
+
+    # This is the available frequency options accepted by
+    # <tt>:every</tt> option.
     FREQUENCY = %w(day week month year)
 
     attr_reader :event, :options
 
+    # Return the default starting date.
+    #
+    #   Recurrence.default_starts_date
+    #   #=> <Date>
+    #
     def self.default_starts_date
-      if @default_starts_date
-        if @default_starts_date.is_a?(String)
-          eval(@default_starts_date)
-        else
-          @default_starts_date.call
-        end
+      case @default_starts_date
+      when String
+        eval(@default_starts_date)
+      when Proc
+        @default_starts_date.call
       else
         Date.today
       end
     end
 
+    # Set the default starting date globally.
+    # Can be a proc or a string.
+    #
+    #   Recurrence.default_starts_date = proc { Date.today }
+    #   Recurrence.default_starts_date = "Date.today"
+    #
     def self.default_starts_date=(date)
-      unless date.respond_to?(:call) || date.is_a?(String) || date == nil
+      unless date.respond_to?(:call) || date.kind_of?(String) || date == nil
         raise ArgumentError, 'default_starts_date must be a proc or an evaluatable string such as "Date.current"'
       end
 
       @default_starts_date = date
     end
 
+    # Return the default ending date. Defaults to 2037-12-31.
+    #
+    #   Recurrence.default_until_date
+    #
     def self.default_until_date
       @default_until_date ||= Date.new(2037, 12, 31)
     end
 
+    # Set the default ending date globally.
+    # Can be a date or a string recognized by Date#parse.
+    #
+    #   Recurrence.default_until_date = "2012-12-31"
+    #   Recurrence.default_until_date = Date.tomorrow
+    #
     def self.default_until_date=(date)
-      @default_until_date = if date.is_a?(String)
-        Date.parse(date)
-      else
-        date
-      end
+      @default_until_date = as_date(date)
     end
 
+    # Create a daily recurrence.
+    #
+    #   Recurrence.daily
+    #   Recurrence.daily(:interval => 2) #=> every 2 days
+    #   Recurrence.daily(:starts => 3.days.from_now)
+    #   Recurrence.daily(:until => 10.days.from_now)
+    #
     def self.daily(options = {})
       options[:every] = :day
       new(options)
     end
 
+    # Create a weekly recurrence.
+    #
+    #   Recurrence.weekly(:on => 5) #=> 0 = sunday, 1 = monday, ...
+    #   Recurrence.weekly(:on => :saturday)
+    #   Recurrence.weekly(:on => [sunday, :saturday])
+    #   Recurrence.weekly(:on => :saturday, :interval => 2)
+    #
     def self.weekly(options = {})
       options[:every] = :week
       new(options)
     end
 
+    # Create a monthly recurrence.
+    #
+    #   Recurrence.monthly(:on => 15) #=> every 15th day
+    #   Recurrence.monthly(:on => :first, :weekday => :sunday)
+    #   Recurrence.monthly(:on => :second, :weekday => :sunday)
+    #   Recurrence.monthly(:on => :third, :weekday => :sunday)
+    #   Recurrence.monthly(:on => :fourth, :weekday => :sunday)
+    #   Recurrence.monthly(:on => :fifth, :weekday => :sunday)
+    #   Recurrence.monthly(:on => :last, :weekday => :sunday)
+    #   Recurrence.monthly(:on => 15, :interval => 2)
+    #   Recurrence.monthly(:on => 15, :interval => :monthly)
+    #   Recurrence.monthly(:on => 15, :interval => :bimonthly)
+    #   Recurrence.monthly(:on => 15, :interval => :quarterly)
+    #   Recurrence.monthly(:on => 15, :interval => :semesterly)
+    #
     def self.monthly(options = {})
       options[:every] = :month
       new(options)
     end
 
+    # Create a yearly recurrence.
+    #
+    #   Recurrence.yearly(:on => [7, 14]) #=> every Jul 14
+    #   Recurrence.yearly(:on => [7, 14], :interval => 2) #=> every 2 years on Jul 14
+    #   Recurrence.yearly(:on => [:jan, 14], :interval => 2)
+    #   Recurrence.yearly(:on => [:january, 14], :interval => 2)
+    #
     def self.yearly(options = {})
       options[:every] = :year
       new(options)
     end
 
+    # Initialize a recurrence object. All options from shortcut methods
+    # (Recurrence.daily, Recurrence.monthly, and so on) and requires the <tt>:every</tt> option to
+    # be one of these options: <tt>:day</tt>, <tt>:week</tt>, <tt>:month</tt>, or <tt>:year</tt>.
+    #
+    #   Recurrence.new(:every => :day)
+    #   Recurrence.new(:every => :week, :on => :sunday)
+    #   Recurrence.new(:every => :month, :on => 14)
+    #   Recurrence.new(:every => :year, :on => [:jan, 14])
+    #
     def initialize(options)
       raise ArgumentError, ":every option is required" unless options.key?(:every)
       raise ArgumentError, "invalid :every option"     unless FREQUENCY.include?(options[:every].to_s)
 
-      @options = options.dup
-      @normalized_options = initialize_dates(options)
+      @options = options
+      @normalized_options = initialize_dates(options.dup)
       @normalized_options[:interval] ||= 1
 
       @event = case @normalized_options[:every].to_sym
         when :day
-          Recurrence::Event::Daily.new(@normalized_options)
+          Event::Daily.new(@normalized_options)
         when :week
-          Recurrence::Event::Weekly.new(@normalized_options)
+          Event::Weekly.new(@normalized_options)
         when :month
-          Recurrence::Event::Monthly.new(@normalized_options)
+          Event::Monthly.new(@normalized_options)
         when :year
-          Recurrence::Event::Yearly.new(@normalized_options)
+          Event::Yearly.new(@normalized_options)
       end
     end
 
+    # Reset the recurrence cache, returning to the first available date.
     def reset!
       @event.reset!
       @events = nil
     end
 
+    # Check if a given date can be retrieve from the current recurrence options.
+    #
+    #   r = Recurrence.weekly(:on => :sunday)
+    #   r.include?("2010-11-16")
+    #   #=> false, because "2010-11-16" is monday
+    #
     def include?(required_date)
-      required_date = Date.parse(required_date) if required_date.is_a?(String)
+      required_date = as_date(required_date)
 
       if required_date < @normalized_options[:starts] || required_date > @normalized_options[:until]
         false
@@ -98,20 +171,48 @@ module SimplesIdeias
         end
       end
 
-      return false
+      false
     end
 
+    # Return the next date in recurrence, without changing the internal date object.
+    #
+    #   r = Recurrence.weekly(:on => :sunday, :starts => "2010-11-15")
+    #   r.next #=> Sun, 21 Nov 2010
+    #   r.next #=> Sun, 21 Nov 2010
+    #
     def next
       @event.next
     end
 
+    # Return the next date in recurrence, and changes the internal date object.
+    #
+    #   r = Recurrence.weekly(:on => :sunday, :starts => "2010-11-15")
+    #   r.next! #=> Sun, 21 Nov 2010
+    #   r.next! #=> Sun, 28 Nov 2010
+    #
     def next!
       @event.next!
     end
 
+    # Return an array with all dates within a given recurrence, caching the result.
+    #
+    #   r = Recurrence.daily(:starts => "2010-11-15", :until => "2010-11-20")
+    #   r.events
+    #
+    # The return will be
+    #
+    #   [
+    #     [0] Mon, 15 Nov 2010,
+    #     [1] Tue, 16 Nov 2010,
+    #     [2] Wed, 17 Nov 2010,
+    #     [3] Thu, 18 Nov 2010,
+    #     [4] Fri, 19 Nov 2010,
+    #     [5] Sat, 20 Nov 2010
+    # ]
+    #
     def events(options={})
-      options[:starts] = Date.parse(options[:starts]) if options[:starts].is_a?(String)
-      options[:until]  = Date.parse(options[:until])  if options[:until].is_a?(String)
+      options[:starts] = as_date(options[:starts])
+      options[:until]  = as_date(options[:until])
 
       reset! if options[:starts] || options[:until]
 
@@ -134,26 +235,44 @@ module SimplesIdeias
       end
     end
 
+    # Works like SimplesIdeias::Recurrence::Namespace#events, but removes the cache first.
     def events!(options={})
       reset!
       events(options)
     end
 
+    # Iterate in all events between <tt>:starts</tt> and <tt>:until</tt> options.
+    #
+    #   r = Recurrence.daily(:starts => "2010-11-15", :until => "2010-11-17")
+    #   r.each do |date|
+    #     puts date
+    #   end
+    #
+    # This will print
+    #
+    #   Sun, 15 Nov 2010
+    #   Sun, 16 Nov 2010
+    #   Sun, 17 Nov 2010
+    #
+    # When called without a block, it will return a Enumerator.
+    #
+    #   r.each
+    #   #=> #<Enumerator: [Mon, 15 Nov 2010, Tue, 16 Nov 2010, Wed, 17 Nov 2010]:each>
+    #
+    def each(&block)
+      events.each(&block)
+    end
+
+    # Works like SimplesIdeias::Recurrence::Namespace#each, but removes the cache first.
     def each!(&block)
       reset!
       each(&block)
     end
 
-    def each(&block)
-      events.each do |item|
-        yield item
-      end
-    end
-
     private
-    def initialize_dates(options) #:nodoc:
+    def initialize_dates(options) # :nodoc:
       [:starts, :until].each do |name|
-        options[name] = Date.parse(options[name]) if options[name].is_a?(String)
+        options[name] = as_date(options[name])
       end
 
       options[:starts] ||= self.class.default_starts_date
@@ -161,5 +280,14 @@ module SimplesIdeias
 
       options
     end
+
+    def as_date(date) # :nodoc:
+      case date
+      when String
+        Date.parse(date)
+      else
+        date
+      end
+    end
   end
 end

data/lib/recurrence/version.rb

@@ -1,9 +1,9 @@
 module SimplesIdeias
   class Recurrence
     module Version
-      MAJOR = 0
-      MINOR = 1
-      PATCH = 5
+      MAJOR = 1
+      MINOR = 0
+      PATCH = 0
       STRING = "#{MAJOR}.#{MINOR}.#{PATCH}"
     end
   end

data/recurrence.gemspec

@@ -20,5 +20,6 @@ Gem::Specification.new do |s|
   s.require_paths = ["lib"]
 
   s.add_dependency "activesupport"
-  s.add_development_dependency "rspec-rails", ">= 2.0.0"
+  s.add_development_dependency "rspec", ">= 2.0.0"
+  s.add_development_dependency "ruby-debug19"
 end

data/spec/recurrence_spec.rb

@@ -1,6 +1,6 @@
 require "spec_helper"
 
-describe "recurrence" do
+describe Recurrence do
   it "should require :every option" do
     expect { recurrence({}) }.to raise_error(ArgumentError)
   end
@@ -13,58 +13,76 @@ describe "recurrence" do
     expect { recurrence(:every => :day, :interval => 0) }.to raise_error(ArgumentError)
   end
 
+  it "should return an enumerator when Recurrence#each is called without a block" do
+    recurrence(:every => :day).each.should be_instance_of(Enumerator)
+  end
+
+  it "should return an enumerator when Recurrence#each! is called without a block" do
+    recurrence(:every => :day).each!.should be_instance_of(Enumerator)
+  end
+
   Recurrence::Event::Monthly::INTERVALS.each do |interval|
     it "should accept valid :interval symbol for monthly recurrence (#{interval[0]})" do
-      expect { recurrence(:every => :month, :on => 10, :interval => interval[0]) }.to_not raise_error(ArgumentError)
+      expect {
+        recurrence(:every => :month, :on => 10, :interval => interval[0])
+      }.to_not raise_error(ArgumentError)
     end
   end
 
   Recurrence::Event::Yearly::MONTHS.each do |month_name, month_number|
     it "should accept month as symbol for yearly recurrence (#{month_name})" do
-      expect { recurrence(:every => :year, :on => [month_name, 10]) }.to_not raise_error(ArgumentError)
+      expect {
+        recurrence(:every => :year, :on => [month_name, 10])
+      }.to_not raise_error(ArgumentError)
     end
   end
 
   it "should require month to be a valid symbol for yearly recurrence" do
-    expect { recurrence(:every => :year, :on => [:invalid, 10]) }.to raise_error(ArgumentError)
+    expect {
+      recurrence(:every => :year, :on => [:invalid, 10])
+    }.to raise_error(ArgumentError)
   end
 
   it "should require :interval to be a valid symbol for monthly recurrence" do
-    expect { recurrence(:every => :month, :on => 10, :interval => :invalid) }.to raise_error(ArgumentError)
+    expect {
+      recurrence(:every => :month, :on => 10, :interval => :invalid)
+    }.to raise_error(ArgumentError)
   end
 
-  describe '.default_starts_date' do
-    it 'should return Date.today by default' do
+  describe ".default_starts_date" do
+    it "should return Date.today by default" do
       Recurrence.default_starts_date.should == Date.today
     end
 
-    it 'should require only strings and procs' do
-      expect { Recurrence.default_starts_date = Date.tomorrow }.to raise_error(ArgumentError)
+    it "should require only strings and procs" do
+      expect {
+        Recurrence.default_starts_date = Date.tomorrow
+      }.to raise_error(ArgumentError)
     end
 
-    context 'when .default_starts_date is reassigned to "Date.tomorrow" string' do
-      before { Recurrence.default_starts_date = 'Date.tomorrow' }
+    context "when .default_starts_date is reassigned to 'Date.tomorrow' string" do
+      before { Recurrence.default_starts_date = "Date.tomorrow" }
       after { Recurrence.default_starts_date = nil }
 
-      it 'should return Date.tomorrow' do
+      it "should return Date.tomorrow" do
         Recurrence.default_starts_date.should == Date.tomorrow
       end
 
-      it 'should have effect on generated events' do
+      it "should have effect on generated events" do
         r = Recurrence.new(:every => :day, :until => 3.days.from_now.to_date)
         r.events.first.should == Date.tomorrow
       end
     end
 
-    context 'when .default_starts_date is reassigned to lambda { Date.tomorrow } proc' do
+    context "when .default_starts_date is reassigned to lambda { Date.tomorrow } proc" do
       before { Recurrence.default_starts_date = lambda { Date.tomorrow } }
       after { Recurrence.default_starts_date = nil }
 
-      it 'should return Date.tomorrow' do
+      it "should return Date.tomorrow" do
         Recurrence.default_starts_date.should == Date.tomorrow
       end
 
-      it 'should have effect on generated events' do
+      it "should have effect on generated events" do
         r = Recurrence.new(:every => :day, :until => 3.days.from_now.to_date)
         r.events.first.should == Date.tomorrow
       end
@@ -106,7 +124,12 @@ describe "recurrence" do
     end
 
     it "should have a lacking day if the interval does not match the last day" do
-      @recurrence = recurrence(:every => :day, :starts => "2008-03-19", :until => "2008-04-25", :interval => 2)
+      @recurrence = recurrence(
+        :every    => :day,
+        :starts   => "2008-03-19",
+        :until    => "2008-04-25",
+        :interval => 2
+      )
       @recurrence.events[-1].to_s.should == "2008-04-24"
     end
   end
@@ -140,7 +163,12 @@ describe "recurrence" do
       starts = Date.parse("2008-02-29")
       ends = Date.parse("2008-03-14")
 
-      @recurrence = recurrence(:every => :week, :on => :friday, :starts => starts, :until => ends.to_date)
+      @recurrence = recurrence(
+        :every  => :week,
+        :on     => :friday,
+        :starts => starts,
+        :until  => ends.to_date
+      )
       @recurrence.events[0].to_s.should == "2008-02-29"
       @recurrence.events[1].to_s.should == "2008-03-07"
       @recurrence.events[-1].to_s.should == ends.to_s
@@ -148,7 +176,13 @@ describe "recurrence" do
 
     it "should use interval" do
       starts = Date.parse("2008-09-21")
-      @recurrence = recurrence(:every => :week, :on => starts.wday, :interval => 2, :starts => starts, :until => "2009-01-01")
+      @recurrence = recurrence(
+        :every    => :week,
+        :on       => starts.wday,
+        :interval => 2,
+        :starts   => starts,
+        :until    => "2009-01-01"
+      )
       @recurrence.events[0].to_s.should == "2008-09-21"
       @recurrence.events[1].to_s.should == "2008-10-05"
       @recurrence.events[2].to_s.should == "2008-10-19"
@@ -160,7 +194,13 @@ describe "recurrence" do
 
     it "should occur several times per week" do
       starts = Date.parse("2008-09-21") #=> sunday
-      @recurrence = recurrence(:every => :week, :on => [ :saturday, :sunday ], :interval => 2, :starts => starts, :until => "2009-01-01")
+      @recurrence = recurrence(
+        :every    => :week,
+        :on       => [:saturday, :sunday],
+        :interval => 2,
+        :starts   => starts,
+        :until    => "2009-01-01"
+      )
       @recurrence.events[0].to_s.should == "2008-09-21"
       @recurrence.events[1].to_s.should == "2008-09-27"
       @recurrence.events[2].to_s.should == "2008-10-05"
@@ -171,7 +211,12 @@ describe "recurrence" do
       @recurrence.events[7].to_s.should == "2008-11-08"
 
       starts = Date.parse("2008-09-21") #=> sunday
-      @recurrence = recurrence(:every => :week, :on => [ :monday, :wednesday, :friday ], :starts => starts, :until => "2009-01-01")
+      @recurrence = recurrence(
+        :every  => :week,
+        :on     => [:monday, :wednesday, :friday],
+        :starts => starts,
+        :until  => "2009-01-01"
+      )
       @recurrence.events[0].to_s.should == "2008-09-22"
       @recurrence.events[1].to_s.should == "2008-09-24"
       @recurrence.events[2].to_s.should == "2008-09-26"
@@ -182,7 +227,12 @@ describe "recurrence" do
 
     it "should run until next available saturday" do
       starts = Date.parse("2008-09-21") # => sunday
-      @recurrence = recurrence(:every => :week, :on => :saturday, :starts => starts, :until => "2009-01-01")
+      @recurrence = recurrence(
+        :every  => :week,
+        :on     => :saturday,
+        :starts => starts,
+        :until  => "2009-01-01"
+      )
       @recurrence.events[0].to_s.should == "2008-09-27"
     end
   end
@@ -211,7 +261,12 @@ describe "recurrence" do
         starts = Date.parse("2008-06-07")
         ends = Date.parse("2008-11-07")
 
-        @recurrence = recurrence(:every => :month, :on => starts.day, :starts => starts, :until => ends)
+        @recurrence = recurrence(
+          :every  => :month,
+          :on     => starts.day,
+          :starts => starts,
+          :until  => ends
+        )
         @recurrence.events[0].to_s.should == "2008-06-07"
         @recurrence.events[-1].to_s.should == "2008-11-07"
       end
@@ -219,13 +274,24 @@ describe "recurrence" do
       it "should run until next available 27th" do
         starts = Date.parse("2008-09-28")
 
-        @recurrence = recurrence(:every => :month, :on => 27, :starts => starts, :until => "2009-01-01")
+        @recurrence = recurrence(
+          :every  => :month,
+          :on     => 27,
+          :starts => starts,
+          :until  => "2009-01-01"
+        )
         @recurrence.events[0].to_s.should == "2008-10-27"
       end
 
       it "should use interval" do
         starts = Date.parse("2008-01-31")
-        @recurrence = recurrence(:every => :month, :on => 31, :interval => 2, :starts => starts, :until => "2010-01-01")
+        @recurrence = recurrence(
+          :every    => :month,
+          :on       => 31,
+          :interval => 2,
+          :starts   => starts,
+          :until    => "2010-01-01"
+        )
         @recurrence.events[0].to_s.should == "2008-01-31"
         @recurrence.events[1].to_s.should == "2008-03-31"
         @recurrence.events[2].to_s.should == "2008-05-31"
@@ -235,7 +301,13 @@ describe "recurrence" do
         @recurrence.events[6].to_s.should == "2009-01-31"
 
         starts = Date.parse("2008-01-31")
-        @recurrence = recurrence(:every => :month, :on => 29, :interval => 3, :starts => starts, :until => "2010-01-01")
+        @recurrence = recurrence(
+          :every    => :month,
+          :on       => 29,
+          :interval => 3,
+          :starts   => starts,
+          :until    => "2010-01-01"
+        )
         @recurrence.events[0].to_s.should == "2008-04-29"
         @recurrence.events[1].to_s.should == "2008-07-29"
         @recurrence.events[2].to_s.should == "2008-10-29"
@@ -244,7 +316,13 @@ describe "recurrence" do
         @recurrence.events[5].to_s.should == "2009-07-29"
 
         starts = Date.parse("2008-02-29")
-        @recurrence = recurrence(:every => :month, :on => 31, :interval => 4, :starts => starts, :until => "2010-01-01")
+        @recurrence = recurrence(
+          :every    => :month,
+          :on       => 31,
+          :interval => 4,
+          :starts   => starts,
+          :until    => "2010-01-01"
+        )
         @recurrence.events[0].to_s.should == "2008-02-29"
         @recurrence.events[1].to_s.should == "2008-06-30"
         @recurrence.events[2].to_s.should == "2008-10-31"
@@ -261,14 +339,24 @@ describe "recurrence" do
       it "should repeat until 8 months from now" do
         date = 8.months.from_now
         week = (date.day - 1) / 7 + 1
-        @recurrence = recurrence(:every => :month, :on => week, :weekday => date.wday, :until => date.to_date)
+        @recurrence = recurrence(
+          :every   => :month,
+          :on      => week,
+          :weekday => date.wday,
+          :until   => date.to_date
+        )
         @recurrence.events[-1].should == date.to_date
       end
 
       it "should start 9 months ago" do
         date = 9.months.ago
         week = (date.day - 1) / 7 + 1
-        @recurrence = recurrence(:every => :month, :on => week, :weekday => date.wday, :starts => date.to_date)
+        @recurrence = recurrence(
+          :every   => :month,
+          :on      => week,
+          :weekday => date.wday,
+          :starts  => date.to_date
+        )
         @recurrence.events[0].should == date.to_date
       end
 
@@ -276,7 +364,13 @@ describe "recurrence" do
         starts = Date.parse("2008-06-07")
         ends = Date.parse("2008-11-01")
 
-        @recurrence = recurrence(:every => :month, :on => :first, :weekday => :saturday, :starts => starts, :until => ends)
+        @recurrence = recurrence(
+          :every   => :month,
+          :on      => :first,
+          :weekday => :saturday,
+          :starts  => starts,
+          :until   => ends
+        )
         @recurrence.events[0].to_s.should == "2008-06-07"
         @recurrence.events[-1].to_s.should == "2008-11-01"
       end
@@ -285,14 +379,27 @@ describe "recurrence" do
         starts = Date.parse("2008-06-29")
         ends = Date.parse("2008-11-30")
 
-        @recurrence = recurrence(:every => :month, :on => :last, :weekday => :sunday, :starts => starts, :until => ends)
+        @recurrence = recurrence(
+          :every   => :month,
+          :on      => :last,
+          :weekday => :sunday,
+          :starts  => starts,
+          :until   => ends
+        )
         @recurrence.events[0].to_s.should == "2008-06-29"
         @recurrence.events[-1].to_s.should == "2008-11-30"
       end
 
       it "should use interval" do
         starts = Date.parse("2009-01-01")
-        @recurrence = recurrence(:every => :month, :on => :third, :weekday => :sunday, :interval => 2, :starts => starts, :until => "2010-02-01")
+        @recurrence = recurrence(
+          :every    => :month,
+          :on       => :third,
+          :weekday  => :sunday,
+          :interval => 2,
+          :starts   => starts,
+          :until    => "2010-02-01"
+        )
         @recurrence.events[0].to_s.should == "2009-01-18"
         @recurrence.events[1].to_s.should == "2009-03-15"
         @recurrence.events[2].to_s.should == "2009-05-17"
@@ -317,19 +424,34 @@ describe "recurrence" do
       end
 
       it "should accept monthly symbol" do
-        @recurrence = recurrence(:every => :month, :on => 10, :starts => @starts, :interval => :monthly)
+        @recurrence = recurrence(
+          :every    => :month,
+          :on       => 10,
+          :starts   => @starts,
+          :interval => :monthly
+        )
         @recurrence.events[0].to_s.should == "2008-09-10"
         @recurrence.events[1].to_s.should == "2008-10-10"
       end
 
       it "should accept bimonthly symbol" do
-        @recurrence = recurrence(:every => :month, :on => 10, :starts => @starts, :interval => :bimonthly)
+        @recurrence = recurrence(
+          :every    => :month,
+          :on       => 10,
+          :starts   => @starts,
+          :interval => :bimonthly
+        )
         @recurrence.events[0].to_s.should == "2008-09-10"
         @recurrence.events[1].to_s.should == "2008-11-10"
       end
 
       it "should accept quarterly symbol" do
-        @recurrence = recurrence(:every => :month, :on => 10, :starts => @starts, :interval => :quarterly)
+        @recurrence = recurrence(
+          :every    => :month,
+          :on       => 10,
+          :starts   => @starts,
+          :interval => :quarterly
+        )
         @recurrence.events[0].to_s.should == "2008-09-10"
         @recurrence.events[1].to_s.should == "2008-12-10"
       end
@@ -350,13 +472,21 @@ describe "recurrence" do
 
     it "should repeat until 7 years from now" do
       date = 7.years.from_now
-      @recurrence = recurrence(:every => :year, :on => [date.month, date.day], :until => date.to_date)
+      @recurrence = recurrence(
+        :every => :year,
+        :on    => [date.month, date.day],
+        :until => date.to_date
+      )
       @recurrence.events[-1].should == date.to_date
     end
 
     it "should start 2 years ago" do
       date = 2.years.ago
-      @recurrence = recurrence(:every => :year, :on => [date.month, date.day], :starts => date.to_date)
+      @recurrence = recurrence(
+        :every  => :year,
+        :on     => [date.month, date.day],
+        :starts => date.to_date
+      )
       @recurrence.events[0].should == date.to_date
     end
 
@@ -364,7 +494,12 @@ describe "recurrence" do
       starts = Date.parse("2003-06-07")
       ends = Date.parse("2018-06-07")
 
-      @recurrence = recurrence(:every => :year, :on => [starts.month, starts.day], :starts => starts, :until => ends)
+      @recurrence = recurrence(
+        :every  => :year,
+        :on     => [starts.month, starts.day],
+        :starts => starts,
+        :until  => ends
+      )
       @recurrence.events[0].to_s.should == "2003-06-07"
       @recurrence.events[-1].to_s.should == "2018-06-07"
     end
@@ -372,7 +507,12 @@ describe "recurrence" do
     it "should use interval" do
       starts = Date.parse("2008-09-21")
 
-      @recurrence = recurrence(:every => :year, :on => [starts.month, starts.day], :interval => 2, :starts => starts)
+      @recurrence = recurrence(
+        :every    => :year,
+        :on       => [starts.month, starts.day],
+        :interval => 2,
+        :starts   => starts
+      )
       @recurrence.events[0].to_s.should == "2008-09-21"
       @recurrence.events[1].to_s.should == "2010-09-21"
       @recurrence.events[2].to_s.should == "2012-09-21"

data/spec/spec_helper.rb

@@ -2,4 +2,4 @@ require "rspec"
 require "recurrence"
 
 Date::DATE_FORMATS[:date] = "%d/%m/%Y"
-Time::DATE_FORMATS[:date] = "%d/%m/%Y"
+Time::DATE_FORMATS[:date] = "%d/%m/%Y"

metadata

@@ -3,10 +3,10 @@ name: recurrence
 version: !ruby/object:Gem::Version 
   prerelease: false
   segments: 
-  - 0
   - 1
-  - 5
-  version: 0.1.5
+  - 0
+  - 0
+  version: 1.0.0
 platform: ruby
 authors: 
 - Nando Vieira
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-11-03 00:00:00 -02:00
+date: 2010-11-16 00:00:00 -02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -31,7 +31,7 @@ dependencies:
   type: :runtime
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
-  name: rspec-rails
+  name: rspec
   prerelease: false
   requirement: &id002 !ruby/object:Gem::Requirement 
     none: false
@@ -45,6 +45,19 @@ dependencies:
         version: 2.0.0
   type: :development
   version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: ruby-debug19
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
 description: A simple library to handle recurring events
 email: 
 - fnando.vieira@gmail.com
@@ -62,9 +75,8 @@ files:
 - Gemfile.lock
 - History.txt
 - License.txt
-- README.markdown
+- README.rdoc
 - Rakefile
-- init.rb
 - lib/recurrence.rb
 - lib/recurrence/event.rb
 - lib/recurrence/event/base.rb

data/README.markdown

@@ -1,138 +0,0 @@
-Recurrence
-==========
-
-* [http://github.com/fnando/recurrence](http://github.com/fnando/recurrence)
-
-DESCRIPTION:
-------------
-
-A simple library to handle recurring events.
-
-
-INSTALLATION:
--------------
-
-Recurrence can be installed by running
-
-	gem install recurrence
-
-USAGE:
-------
-
-	require 'rubygems'
-	require 'recurrence'
-
-	# Daily
-	r = Recurrence.new(:every => :day)
-	r = Recurrence.new(:every => :day, :interval => 9)
-	r = Recurrence.daily(options = {})
-
-	# Weekly
-	r = Recurrence.new(:every => :week, :on => 5)
-	r = Recurrence.new(:every => :week, :on => :monday)
-	r = Recurrence.new(:every => :week, :on => [:monday, :friday])
-	r = Recurrence.new(:every => :week, :on => [:monday, :wednesday, :friday])
-	r = Recurrence.new(:every => :week, :on => :friday, :interval => 2)
-	r = Recurrence.weekly(:on => :thursday)
-
-	# Monthly by month day
-	r = Recurrence.new(:every => :month, :on => 15)
-	r = Recurrence.new(:every => :month, :on => 31)
-	r = Recurrence.new(:every => :month, :on => 7, :interval => 2)
-	r = Recurrence.new(:every => :month, :on => 7, :interval => :monthly)
-	r = Recurrence.new(:every => :month, :on => 7, :interval => :bimonthly)
-	r = Recurrence.monthly(:on => 31)
-
-	# Monthly by week day
-	r = Recurrence.new(:every => :month, :on => :first, :weekday => :sunday)
-	r = Recurrence.new(:every => :month, :on => :third, :weekday => :monday)
-	r = Recurrence.new(:every => :month, :on => :last,  :weekday => :friday)
-	r = Recurrence.new(:every => :month, :on => :last,  :weekday => :friday, :interval => 2)
-	r = Recurrence.new(:every => :month, :on => :last,  :weekday => :friday, :interval => :quarterly)
-	r = Recurrence.new(:every => :month, :on => :last,  :weekday => :friday, :interval => :semesterly)
-
-	# Yearly
-	r = Recurrence.new(:every => :year, :on => [7, 4]) # => [month, day]
-	r = Recurrence.new(:every => :year, :on => [10, 31], :interval => 3)
-	r = Recurrence.new(:every => :year, :on => [:jan, 31])
-	r = Recurrence.new(:every => :year, :on => [:january, 31])
-	r = Recurrence.yearly(:on => [:january, 31])
-
-	# Limit recurrence
-	# :starts defaults to Date.today
-	# :until defaults to 2037-12-31
-	r = Recurrence.new(:every => :day, :starts => Date.today)
-	r = Recurrence.new(:every => :day, :until => '2010-01-31')
-	r = Recurrence.new(:every => :day, :starts => Date.today, :until => '2010-01-31')
-
-	# Getting an array with all events
-	r.events.each {|date| puts date.to_s }  # => Memoized array
-	r.events!.each {|date| puts date.to_s } # => reset items cache and re-execute it
-	r.events(:starts => '2009-01-01').each {|date| puts date.to_s }
-	r.events(:until => '2009-01-10').each {|date| puts date.to_s }
-	r.events(:starts => '2009-01-05', :until => '2009-01-10').each {|date| puts date.to_s }
-
-	# Iterating events
-	r.each { |date| puts date.to_s } # => Use items method
-	r.each! { |date| puts date.to_s } # => Use items! method
-
-	# Check if a date is included
-	r.include?(Date.today) # => true or false
-	r.include?('2008-09-21')
-
-	# Get next available date
-	r.next 	# => Keep the original date object
-	r.next! # => Change the internal date object to the next available date
-
-TROUBLESHOOTING
----------------
-
-If you're having problems because already have a class/module called Recurrence that is conflicting with this gem, you can require the namespace and create a class that inherits from `SimplesIdeias::Recurrence`.
-
-	require "recurrence/namespace"
-
-	class RecurrentEvent < SimplesIdeias::Recurrence
-	end
-
-	r = RecurrentEvent.new(:every => :day)
-
-If you're using Rails/Bundler or something like that, remember to override the `:require` option.
-
-	# Gemfile
-	source :rubygems
-
-	gem "recurrence", :require => "recurrence/namespace"
-
-MAINTAINER
-----------
-
-* Nando Vieira (<http://simplesideias.com.br/>)
-
-CONTRIBUTORS
-------------
-
-* José Valim (<http://josevalim.blogspot.com/>)
-
-LICENSE:
---------
-
-(The MIT License)
-
-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.

data/init.rb

@@ -1,2 +0,0 @@
-require "recurrence"
-warn "Using Recurrence as a Rails plugin is deprecated and won't be supported in future versions."