hiccup 0.2.1 → 0.3.0

data/README.mdown

@@ -0,0 +1,82 @@
+# Hiccup
+
+Hiccup mixes a-la-cart recurrence features into your recurring model. It doesn't dictate the data structure of your model, just the interface. It works just like Devise does for authenticatable models.
+
+Hiccup does provide an extremely lightweight `Schedule` class that mixes in all of Hiccup's feature, but you don't have to use Hiccup's Schedul if you don't want to.
+
+### Usage
+
+```ruby
+class Schedule
+  extend Hiccup
+  
+  hiccup :enumerable,
+         :validatable,
+         :humanizable,
+         :inferrable,
+         :serializable => [:ical]
+  
+end
+```
+
+### Interface
+
+Hiccup requires that a recurring object expose the following properties
+
+  - **kind**: one of `:never`, `:weekly`, `:monthly`, `:annually`
+  - **start_date**: the date when the recurrence should start
+  - **ends**: either `true` or `false`, indicating whether the recurrence has an end date
+  - **end_date**: the date when the recurrence should end
+  - **skip**: the number of instances to skip (You'd set `skip` to 2 to specify an event that occurs every _other_ week, for example)
+  - **weekly_pattern**: an array of weekdays on which a weekly event should recur
+  - **monthly_pattern**: an array of recurrence rules for a monthly event
+
+### Examples
+
+
+```ruby
+# Every other Monday
+Schedule.new(:kind => :weekly, :weekly_pattern => ["Monday"])
+
+# Every year on June 21 (starting in 1999)
+Schedule.new(:kind => :yearly, :start_date => Date.new(1999, 6, 21))
+
+# The second and fourth Sundays of the month
+Schedule.new(:kind => :monthly, :monthly_pattern => [[2, "Sunday"], [4, "Sunday"]])
+```
+
+
+# Modules
+
+### Enumerable
+
+Supplies methods for creating instances of a recurring pattern
+
+### Validatable
+
+Mixes in ActiveModel validations for recurrence models
+
+### Humanizable
+
+Represents a recurring pattern in a human-readable string
+
+### Inferrable
+
+Infers a schedule from an array of dates
+
+Examples:
+
+```ruby
+schedule = Schedule.infer %w{2012-7-9 2012-8-13 2012-9-10}
+schedule.humanize # => "The second Monday of every month"
+
+schedule = Schedule.infer %w{2010-3-4 2011-3-4 2012-3-4}
+schedule.humanize # => "Every year on March 4"
+
+schedule = Schedule.infer %w{2012-3-6 2012-3-8 2012-3-15 2012-3-20 2012-3-27 2012-3-29}
+schedule.humanize # => "Every Tuesday and Thursday"
+```
+
+### Serializable
+
+Supports serializing and deserializing a recurrence pattern to an array of formats

data/hiccup.gemspec

@@ -8,17 +8,19 @@ Gem::Specification.new do |s|
   s.authors     = ["Bob Lail"]
   s.email       = ["bob.lailfamily@gmail.com"]
   s.homepage    = "http://boblail.github.com/hiccup/"
-  s.summary     = %q{Recurrence features a-la-cart}
-  s.description = %q{Recurrence features a-la-cart}
+  s.summary     = %q{A library for working with things that recur}
+  s.description = %q{Hiccup mixes a-la-cart recurrence features into your data structure. It doesn't dictate the data structure, just the interface.}
   
   s.rubyforge_project = "hiccup"
   
-  s.add_dependency "activesupport"
+  s.add_dependency "activesupport", "~> 3.2.8"
+  s.add_dependency "builder"
   
   s.add_development_dependency "ri_cal"
-  s.add_development_dependency "rails"
+  s.add_development_dependency "rails", "~> 3.2.8"
   s.add_development_dependency "turn"
   s.add_development_dependency "simplecov"
+  s.add_development_dependency "pry"
   
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")

data/lib/hiccup/core_ext/date.rb

@@ -21,6 +21,17 @@ module Hiccup
       end
       
       
+      
+      def get_nth_wday_of_month
+        (day - 1) / 7 + 1
+      end
+      
+      def get_nth_wday_string
+        "#{get_nth_wday_of_month} #{::Date::DAYNAMES[wday]}"
+      end
+      
+      
+      
     end
   end
 end

data/lib/hiccup/core_ext/enumerable.rb

@@ -0,0 +1,17 @@
+module Hiccup
+  module CoreExt
+    module EnumerableExtensions
+      
+      def to_histogram
+        self.each_with_object(Hash.new { 0 }) do |item, histogram|
+          pattern = block_given? ? yield(item) : item
+          histogram[pattern] += 1
+        end
+      end
+      
+    end
+  end
+end
+
+Enumerable.send(:include, Hiccup::CoreExt::EnumerableExtensions)
+Array.send(:include, Hiccup::CoreExt::EnumerableExtensions)

data/lib/hiccup/core_ext/hash.rb

@@ -0,0 +1,16 @@
+module Hiccup
+  module CoreExt
+    module HashExtensions
+      
+      def group_by_value
+        each_with_object({}) do |(key, value), new_hash|
+          (new_hash[value]||=[]).push(key)
+        end
+      end
+      alias :flip :group_by_value
+      
+    end
+  end
+end
+
+Hash.send(:include, Hiccup::CoreExt::HashExtensions)

data/lib/hiccup/enumerable.rb

@@ -66,7 +66,8 @@ module Hiccup
           next unless temp
           
           remainder = months_between(temp, start_date) % skip
-          temp = monthly_occurrence_to_date(occurrence, (skip - remainder).months.after(temp)) if (remainder > 0)        
+          temp = monthly_occurrence_to_date(occurrence, (skip - remainder).months.after(temp)) if (remainder > 0)
+          next unless temp
           
           result = temp if !result || (temp < result)
         end
@@ -135,7 +136,8 @@ module Hiccup
           next unless temp
           
           remainder = months_between(temp, start_date) % skip
-          temp = monthly_occurrence_to_date(occurrence, remainder.months.before(temp)) if (remainder > 0)        
+          temp = monthly_occurrence_to_date(occurrence, remainder.months.before(temp)) if (remainder > 0)
+          next unless temp
           
           result = temp if !result || (temp > result)
         end
@@ -178,6 +180,22 @@ module Hiccup
     
     
     
+    def n_occurrences_before(limit, date)
+      n_occurrences_on_or_before(limit, 1.day.before(date))
+    end
+    
+    def n_occurrences_on_or_before(limit, date)
+      occurrences = []
+      occurrence = first_occurrence_on_or_before(date)
+      while occurrence && occurrences.length < limit
+        occurrences << occurrence
+        occurrence = first_occurrence_before(occurrence)
+      end
+      occurrences
+    end
+    
+    
+    
     def monthly_occurrence_to_date(occurrence, date)
       year, month = date.year, date.month
       

data/lib/hiccup/humanizable.rb

@@ -39,7 +39,7 @@ module Hiccup
     end
     
     def yearly_humanize
-      sentence("Every", ordinal, "year on", self.start_date.strftime('%B %d'))
+      sentence("Every", ordinal, "year on", self.start_date.strftime('%B'), self.start_date.strftime('%e').strip)
     end
     
     

data/lib/hiccup/inferrable.rb

@@ -0,0 +1,249 @@
+require 'active_support/concern'
+require 'active_support/core_ext/date/conversions'
+require 'hiccup/core_ext/enumerable'
+require 'hiccup/core_ext/hash'
+
+
+module Hiccup
+  module Inferrable
+    extend ActiveSupport::Concern
+    
+    module ClassMethods
+      
+      
+      
+      def infer(dates, options={})
+        @verbose = options.fetch(:verbose, false)
+        dates = extract_array_of_dates!(dates)
+        guesses = generate_guesses(dates)
+        guess, score = pick_best_guess(guesses, dates)
+        guess
+      end
+      
+      
+      
+      def generate_guesses(dates)
+        @start_date = dates.min
+        @end_date = dates.max
+        [].tap do |guesses|
+          guesses.concat generate_yearly_guesses(dates)
+          guesses.concat generate_monthly_guesses(dates)
+          guesses.concat generate_weekly_guesses(dates)
+        end
+      end
+      
+      def generate_yearly_guesses(dates)
+        histogram_of_patterns = dates.to_histogram do |date|
+          [date.month, date.day]
+        end
+        patterns_by_popularity = histogram_of_patterns.flip # => {1 => [...], 2 => [...], 5 => [a, b]}
+        highest_popularity = patterns_by_popularity.keys.max # => 5
+        most_popular = patterns_by_popularity[highest_popularity].first # => a
+        start_date = Date.new(@start_date.year, *most_popular)
+
+        [].tap do |guesses|
+          (1...5).each do |skip|
+            guesses << self.new.tap do |schedule|
+              schedule.kind = :annually
+              schedule.start_date = start_date
+              schedule.end_date = @end_date
+              schedule.skip = skip
+            end
+          end
+        end
+      end
+      
+      def generate_monthly_guesses(dates)
+        histogram_of_patterns = dates.to_histogram do |date|
+          [date.get_nth_wday_of_month, Date::DAYNAMES[date.wday]]
+        end
+        patterns_by_popularity = histogram_of_patterns.flip
+        
+        histogram_of_days = dates.to_histogram(&:day)
+        days_by_popularity = histogram_of_days.flip
+        
+        if @verbose
+          puts "",
+               "  monthly analysis:",
+               "    input: #{dates.inspect}",
+               "    histogram (weekday): #{histogram_of_patterns.inspect}",
+               "    by_popularity (weekday): #{patterns_by_popularity.inspect}",
+               "    histogram (day): #{histogram_of_days.inspect}",
+               "    by_popularity (day): #{days_by_popularity.inspect}"
+        end
+        
+        [].tap do |guesses|
+          (1...5).each do |skip|
+            enumerate_by_popularity(days_by_popularity) do |days|
+              guesses << self.new.tap do |schedule|
+                schedule.kind = :monthly
+                schedule.start_date = @start_date
+                schedule.end_date = @end_date
+                schedule.skip = skip
+                schedule.monthly_pattern = days
+              end
+            end
+            
+            enumerate_by_popularity(patterns_by_popularity) do |patterns|
+              guesses << self.new.tap do |schedule|
+                schedule.kind = :monthly
+                schedule.start_date = @start_date
+                schedule.end_date = @end_date
+                schedule.skip = skip
+                schedule.monthly_pattern = patterns
+              end
+            end
+          end
+        end
+      end
+      
+      def generate_weekly_guesses(dates)
+        [].tap do |guesses|
+          histogram_of_wdays = dates.to_histogram do |date|
+            Date::DAYNAMES[date.wday]
+          end
+          wdays_by_popularity = histogram_of_wdays.flip
+          
+          if @verbose
+            puts "",
+                 "  weekly analysis:",
+                 "    input: #{dates.inspect}",
+                 "    histogram: #{histogram_of_wdays.inspect}",
+                 "    by_popularity: #{wdays_by_popularity.inspect}"
+          end
+          
+          (1...5).each do |skip|
+            enumerate_by_popularity(wdays_by_popularity) do |wdays|
+              guesses << self.new.tap do |schedule|
+                schedule.kind = :weekly
+                schedule.start_date = @start_date
+                schedule.end_date = @end_date
+                schedule.skip = skip
+                schedule.weekly_pattern = wdays
+              end
+            end
+          end
+        end
+      end
+      
+      
+      
+      # Expects a hash of values grouped by popularity
+      # Yields the most popular values first, and then
+      # increasingly less popular values
+      def enumerate_by_popularity(values_by_popularity)
+        popularities = values_by_popularity.keys.sort.reverse
+        popularities.length.times do |i|
+          at_popularities = popularities.take(i + 1)
+          yield values_by_popularity.values_at(*at_popularities).flatten(1)
+        end
+      end
+      
+      
+      
+      def pick_best_guess(guesses, dates)
+        scored_guesses = guesses \
+          .map { |guess| [guess, score_guess(guess, dates)] } \
+          .sort_by { |(guess, score)| -score.to_f }
+        
+        if @verbose
+          puts "\nGUESSES FOR #{dates}:"
+          scored_guesses.each do |(guess, score)|
+            puts "  (%.3f p/%.3f b/%.3f c/%.3f) #{guess.humanize}" % [
+              score.to_f,
+              score.prediction_rate,
+              score.brick_penalty,
+              score.complexity_penalty]
+          end
+          puts ""
+        end
+        
+        best_guess = scored_guesses.reject { |(guess, score)| score.to_f < 0.333 }.first
+        best_guess || Schedule.new(kind: :never)
+      end
+      
+      def score_guess(guess, input_dates)
+        predicted_dates = guess.occurrences_between(guess.start_date, guess.end_date)
+        
+        # prediction_rate is the percent of input dates predicted
+        predictions = (predicted_dates & input_dates).length
+        prediction_rate = Float(predictions) / Float(input_dates.length)
+        
+        # bricks are dates predicted by this guess but not in the input
+        bricks = (predicted_dates - input_dates).length
+        
+        # brick_rate is the percent of bricks to predictions
+        # A brick_rate >= 1 means that this guess bricks more than it predicts
+        brick_rate = Float(bricks) / Float(input_dates.length)
+        
+        # complexity measures how many rules are necesary
+        # to describe the pattern
+        complexity = complexity_of(guess)
+        
+        # complexity_rate is the number of rules per inputs
+        complexity_rate = Float(complexity) / Float(input_dates.length)
+        
+        Score.new(prediction_rate, brick_rate, complexity_rate)
+      end
+      
+      def complexity_of(schedule)
+        return schedule.weekly_pattern.length if schedule.weekly?
+        return schedule.monthly_pattern.length if schedule.monthly?
+        1
+      end
+      
+      
+      
+      def extract_array_of_dates!(dates)
+        raise_invalid_dates_error! unless dates.respond_to?(:each)
+        dates.map { |date| assert_date!(date) }.sort
+      end
+      
+      def assert_date!(date)
+        return date if date.is_a?(Date)
+        date.to_date rescue raise_invalid_dates_error!
+      end
+      
+      def raise_invalid_dates_error!
+        raise ArgumentError.new("Inferrable.infer expects to receive a collection of dates")
+      end
+      
+      
+      
+      class Score < Struct.new(:prediction_rate, :brick_rate, :complexity_rate)
+        
+        # as brick rate rises, our confidence in this guess drops
+        def brick_penalty
+          brick_penalty = brick_rate * 0.33
+          brick_penalty = 1 if brick_penalty > 1
+          brick_penalty
+        end
+        
+        # as the complexity rises, our confidence in this guess drops
+        # this hash table is a stand-in for a proper formala
+        #
+        # A complexity of 1 means that 1 rule is required per input
+        # date. This means we haven't really discovered a pattern.
+        def complexity_penalty
+          complexity_rate
+        end
+        
+        # our confidence is weakened by bricks and complexity
+        def confidence
+          confidence = 1.0
+          confidence *= (1 - brick_penalty)
+          confidence *= (1 - complexity_penalty)
+          confidence
+        end
+        
+        # a number between 0 and 1
+        def to_f
+          prediction_rate * confidence
+        end
+        
+      end
+      
+      
+    end
+  end
+end

data/lib/hiccup/schedule.rb

@@ -11,6 +11,7 @@ module Hiccup
     hiccup :enumerable,
            :validatable,
            :humanizable,
+           :inferrable,
            :serializable => [:ical]
     
     

data/lib/hiccup/serializers/ical.rb

@@ -37,7 +37,7 @@ module Hiccup
         component = RiCal.parse_string(component_ics).first
         
         @obj = @klass.new
-        @obj.start_date = component.dtstart_property.to_datetime
+        @obj.start_date = component.dtstart_property.try(:to_datetime)
         component.rrule_property.each do |rule|
           case rule.freq
           when "WEEKLY";    parse_weekly_rule(rule)

data/lib/hiccup/version.rb

@@ -1,3 +1,3 @@
 module Hiccup
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

data/test/core_ext_date_test.rb

@@ -0,0 +1,32 @@
+require "test_helper"
+
+
+class CoreExtDateTest < ActiveSupport::TestCase
+  
+  
+  test "should correctly identify the nth weekday of the month of a date" do
+    assert_equal 1, Date.new(2012, 7, 1).get_nth_wday_of_month
+    assert_equal 1, Date.new(2012, 7, 7).get_nth_wday_of_month
+    assert_equal 2, Date.new(2012, 7, 8).get_nth_wday_of_month
+    assert_equal 2, Date.new(2012, 7, 14).get_nth_wday_of_month
+    assert_equal 3, Date.new(2012, 7, 15).get_nth_wday_of_month
+    assert_equal 3, Date.new(2012, 7, 21).get_nth_wday_of_month
+    assert_equal 4, Date.new(2012, 7, 22).get_nth_wday_of_month
+    assert_equal 4, Date.new(2012, 7, 28).get_nth_wday_of_month
+    assert_equal 5, Date.new(2012, 7, 29).get_nth_wday_of_month
+  end
+  
+  test "should correctly identify the nth weekday of the month of a date as a string" do
+    assert_equal "1 Sunday", Date.new(2012, 7, 1).get_nth_wday_string
+    assert_equal "1 Saturday", Date.new(2012, 7, 7).get_nth_wday_string
+    assert_equal "2 Sunday", Date.new(2012, 7, 8).get_nth_wday_string
+    assert_equal "2 Saturday", Date.new(2012, 7, 14).get_nth_wday_string
+    assert_equal "3 Sunday", Date.new(2012, 7, 15).get_nth_wday_string
+    assert_equal "3 Saturday", Date.new(2012, 7, 21).get_nth_wday_string
+    assert_equal "4 Sunday", Date.new(2012, 7, 22).get_nth_wday_string
+    assert_equal "4 Saturday", Date.new(2012, 7, 28).get_nth_wday_string
+    assert_equal "5 Sunday", Date.new(2012, 7, 29).get_nth_wday_string
+  end
+  
+  
+end

data/test/enumerable_test.rb

@@ -55,7 +55,7 @@ class EnumerableTest < ActiveSupport::TestCase
     dates = schedule.occurrences_during_month(2008,7).map {|date| date.day}
     expected_dates = []
     assert_equal expected_dates, dates,                 "occurrences_during_month should generate no occurrences if before start_date"
-
+    
     schedule = Schedule.new({
       :kind => :weekly,
       :weekly_pattern => %w{Monday},
@@ -99,6 +99,37 @@ class EnumerableTest < ActiveSupport::TestCase
   
   
   
+  def test_n_occurrences_before
+    schedule = Schedule.new({
+      :kind => :weekly,
+      :weekly_pattern => %w{Monday Wednesday Friday},
+      :start_date => Date.new(2009,3,15),
+      :ends => true,
+      :end_date => Date.new(2009,11,30)})
+    dates = schedule.n_occurrences_before(10, Date.new(2009, 10, 31)).map { |date| date.strftime("%Y-%m-%d") }
+    
+    expected_dates = ["2009-10-30", "2009-10-28", "2009-10-26",
+                      "2009-10-23", "2009-10-21", "2009-10-19",
+                      "2009-10-16", "2009-10-14", "2009-10-12",
+                      "2009-10-09" ]
+    assert_equal expected_dates, dates
+  end
+  
+  test "n_occurrences_before should return a shorter array if no events exist before the given date" do
+    schedule = Schedule.new({
+      :kind => :weekly,
+      :weekly_pattern => %w{Monday Wednesday Friday},
+      :start_date => Date.new(2009,3,15),
+      :ends => true,
+      :end_date => Date.new(2009,11,30)})
+    dates = schedule.n_occurrences_before(10, Date.new(2009, 3, 20)).map { |date| date.strftime("%Y-%m-%d") }
+    
+    expected_dates = ["2009-03-18", "2009-03-16"]
+    assert_equal expected_dates, dates
+  end
+  
+  
+  
   def test_how_contains_handles_parameter_types
     date = Date.new(1981,4,23)
     schedule = Schedule.new({:kind => :annually, :start_date => date})
@@ -127,6 +158,24 @@ class EnumerableTest < ActiveSupport::TestCase
   
   
   
+  test "should not throw an exception when calculating monthly recurrence and skip causes a guess to be discarded" do
+    schedule = Schedule.new({
+      :kind => :monthly,
+      :monthly_pattern => [
+        [1, "Tuesday"],
+        [2, "Thursday"],
+        [3, "Thursday"],
+        [3, "Tuesday"],
+        [4, "Tuesday"],
+        [5, "Thursday"] ],
+      :skip => 3,
+      :start_date => Date.new(2012,3,6),
+      :end_date => Date.new(2012,3,29)})
+    schedule.occurrences_between(schedule.start_date, schedule.end_date)
+  end
+  
+  
+  
   def test_weekly_recurrence_and_skip
     schedule = Schedule.new({
       :kind => :weekly,

data/test/humanizable_test.rb

@@ -54,16 +54,30 @@ class HumanizableTest < ActiveSupport::TestCase
     {:kind => :monthly, :monthly_pattern => [[1, "Monday"], [3, "Monday"]], :skip => 2})
     
   test_humanize(
-    "Every year on #{Date.today.strftime('%B %d')}",
-    {:kind => :annually})
+    "Every year on October 1",
+    {:kind => :annually, start_date: Date.new(2012, 10, 1)})
     
   test_humanize(
-    "Every other year on #{Date.today.strftime('%B %d')}",
-    {:kind => :annually, :skip => 2})
+    "Every year on October 10",
+    {:kind => :annually, start_date: Date.new(2012, 10, 10)})
     
   test_humanize(
-    "Every fourth year on #{Date.today.strftime('%B %d')}",
-    {:kind => :annually, :skip => 4})
+    "Every other year on August 12",
+    {:kind => :annually, :skip => 2, start_date: Date.new(2012, 8, 12)})
+    
+  test_humanize(
+    "Every fourth year on January 31",
+    {:kind => :annually, :skip => 4, start_date: Date.new(1888, 1, 31)})
+  
+  
+  
+  test "should not have spaces in front of day numbers" do
+    independence_day = Schedule.new({
+      :kind => :annually,
+      :start_date => Date.new(2012, 7, 4)
+    })
+    assert_equal "Every year on July 4", independence_day.humanize
+  end
   
   
   

data/test/ical_serializable_test.rb

@@ -17,6 +17,20 @@ class IcalSerializableTest < ActiveSupport::TestCase
   end
   
   
+  def test_parsing_empty_recurrence
+    schedule = Schedule.from_ical("")
+    assert_equal :never, schedule.kind
+  end
+  
+  
+  test_roundtrip(
+    "No recurrence",
+    "DTSTART;VALUE=DATE-TIME:20090101T000000Z\n",
+    { :kind => :never,
+      :start_date => DateTime.new(2009, 1, 1)
+    })
+  
+  
   test_roundtrip(
     "Simple weekly recurrence",
     "DTSTART;VALUE=DATE-TIME:20090101T000000Z\nRRULE:FREQ=WEEKLY;BYDAY=SU\n",
@@ -26,6 +40,17 @@ class IcalSerializableTest < ActiveSupport::TestCase
     })
   
   
+  test_roundtrip(
+    "Simple weekly recurrence (with an end date)",
+    "DTSTART;VALUE=DATE-TIME:20090101T000000Z\nRRULE:FREQ=WEEKLY;UNTIL=20091231T000000Z;BYDAY=SU\n",
+    { :kind => :weekly,
+      :weekly_pattern => %w{Sunday},
+      :start_date => DateTime.new(2009, 1, 1),
+      :end_date => DateTime.new(2009, 12, 31),
+      :ends => true
+    })
+  
+  
   test_roundtrip(
     "Complex weekly recurrence (with an interval)",
     "DTSTART;VALUE=DATE-TIME:20090101T000000Z\nRRULE:FREQ=WEEKLY;INTERVAL=2;BYDAY=TU,TH\n",

data/test/inferrable_test.rb

@@ -0,0 +1,244 @@
+require "test_helper"
+
+# Ideas: see 3/4/10, 3/5/11, 3/4/12 as closer to
+#        a pattern than 3/4/10, 9/15/11, 3/4/12.
+
+class InferrableTest < ActiveSupport::TestCase
+  include Hiccup
+  
+  
+  
+  test "should raise an error if not given an array of dates" do
+    assert_raises ArgumentError do
+      Schedule.infer(["what's this?"])
+    end
+  end
+  
+  test "extract_array_of_dates! should interpret date-like things as dates" do
+    datelike_things = [Date.today, Time.now, DateTime.new(2012, 8, 17)]
+    dates = Schedule.extract_array_of_dates!(datelike_things)
+    assert_equal datelike_things.length, dates.length
+    assert dates.all? { |date| date.is_a?(Date) }, "Expected these to all be dates, but they were #{dates.map(&:class)}"
+  end
+  
+  test "extract_array_of_dates! should put dates in order" do
+    input_dates = %w{2014-01-01 2007-01-01 2009-01-01}
+    expected_dates = %w{2007-01-01 2009-01-01 2014-01-01}
+    dates = Schedule.extract_array_of_dates!(input_dates)
+    assert_equal expected_dates, dates.map(&:to_s)
+  end
+  
+  
+  
+  test "should prefer guesses that predict too many results over guesses that predict too few" do
+    
+    # In this stream of dates, we could guess an annual recurrence on 1/15
+    # or a monthly recurrence on the 15th.
+    #
+    #  - The annual recurrence would have zero bricks (no unfulfilled predictions), 
+    #    but it would fail to predict 5 of the dates in this list.
+    #
+    #  - The monthly recurrence would have zero failures (there's nothing in
+    #    in the list it _wouldn't_ predict), but it would have 6 bricks.
+    #
+    dates = %w{2011-1-15 2011-2-15 2011-5-15 2011-7-15 2011-8-15 2011-11-15 2012-1-15}
+    
+    # If bricks and fails were equal, the annual recurrence would be the
+    # preferred guess, but the monthly one makes more sense.
+    # It is better to brick than to fail.
+    schedule = Schedule.infer(dates)
+    assert_equal :monthly, schedule.kind
+  end
+  
+  
+  
+  
+  
+  # Infers annual schedules
+  
+  test "should infer an annual" do
+    dates = %w{2010-3-4 2011-3-4 2012-3-4}
+    schedule = Schedule.infer(dates)
+    assert_equal "Every year on March 4", schedule.humanize
+  end
+  
+  
+  # ... with skips
+  
+  test "should infer a schedule that occurs every other year" do
+    dates = %w{2010-3-4 2012-3-4 2014-3-4}
+    schedule = Schedule.infer(dates)
+    assert_equal "Every other year on March 4", schedule.humanize
+  end
+  
+  # ... where some of the input is wrong
+  
+  test "should infer a yearly schedule when one of the dates was rescheduled" do
+    dates = %w{2010-3-4 2011-9-15 2012-3-4 2013-3-4}
+    schedule = Schedule.infer(dates)
+    assert_equal "Every year on March 4", schedule.humanize
+  end
+  
+  test "should infer a yearly schedule when the first date was rescheduled" do
+    dates = %w{2010-3-6 2011-3-4 2012-3-4 2013-3-4}
+    schedule = Schedule.infer(dates)
+    assert_equal "Every year on March 4", schedule.humanize
+  end
+  
+  
+  
+  
+  
+  # Infers monthly schedules
+  
+  test "should infer a monthly schedule that occurs on a date" do
+    dates = %w{2012-2-4 2012-3-4 2012-4-4}
+    schedule = Schedule.infer(dates)
+    assert_equal "The 4th of every month", schedule.humanize
+    
+    dates = %w{2012-2-17 2012-3-17 2012-4-17}
+    schedule = Schedule.infer(dates)
+    assert_equal "The 17th of every month", schedule.humanize
+  end
+  
+  test "should infer a monthly schedule that occurs on a weekday" do
+    dates = %w{2012-7-9 2012-8-13 2012-9-10}
+    schedule = Schedule.infer(dates)
+    assert_equal "The second Monday of every month", schedule.humanize
+  end
+  
+  test "should infer a schedule that occurs several times a month" do
+    dates = %w{2012-7-9 2012-7-23 2012-8-13 2012-8-27 2012-9-10 2012-9-24}
+    schedule = Schedule.infer(dates)
+    assert_equal "The second Monday and fourth Monday of every month", schedule.humanize
+  end
+  
+  
+  # ... with skips
+  
+  test "should infer a schedule that occurs every third month" do
+    dates = %w{2012-2-4 2012-5-4 2012-8-4}
+    schedule = Schedule.infer(dates)
+    assert_equal "The 4th of every third month", schedule.humanize
+  end
+  
+  
+  # ... when some dates are wrong in the input group
+  
+  test "should infer a monthly (by day) schedule when one day was rescheduled" do
+    dates = %w{2012-10-02 2012-11-02 2012-12-03}
+    schedule = Schedule.infer(dates)
+    assert_equal "The 2nd of every month", schedule.humanize
+  end
+  
+  test "should infer a monthly (by day) schedule when the first day was rescheduled" do
+    dates = %w{2012-10-03 2012-11-02 2012-12-02}
+    schedule = Schedule.infer(dates)
+    assert_equal "The 2nd of every month", schedule.humanize
+  end
+  
+  
+  test "should infer a monthly (by weekday) schedule when one day was rescheduled" do
+    dates = %w{2012-10-02 2012-11-06 2012-12-05} # 1st Tuesday, 1st Tuesday, 1st Wednesday
+    schedule = Schedule.infer(dates)
+    assert_equal "The first Tuesday of every month", schedule.humanize
+  end
+  
+  test "should infer a monthly (by weekday) schedule when the first day was rescheduled" do
+    dates = %w{2012-10-03 2012-11-01 2012-12-06} # 1st Wednesday, 1st Thursday, 1st Thursday
+    schedule = Schedule.infer(dates)
+    assert_equal "The first Thursday of every month", schedule.humanize
+  end
+  
+  test "should infer a monthly (by weekday) schedule when the first day was rescheduled 2" do
+    dates = %w{2012-10-11 2012-11-01 2012-12-06} # 2nd Thursday, 1st Thursday, 1st Thursday
+    schedule = Schedule.infer(dates)
+    assert_equal "The first Thursday of every month", schedule.humanize
+  end
+  
+  
+  
+  
+  
+  # Infers weekly schedules
+  
+  test "should infer a weekly schedule" do
+    dates = %w{2012-3-4 2012-3-11 2012-3-18}
+    schedule = Schedule.infer(dates)
+    assert_equal "Every Sunday", schedule.humanize
+  end
+  
+  test "should infer a schedule that occurs several times a week" do
+    dates = %w{2012-3-6 2012-3-8 2012-3-13 2012-3-15 2012-3-20 2012-3-22}
+    schedule = Schedule.infer(dates)
+    assert_equal "Every Tuesday and Thursday", schedule.humanize
+  end
+  
+  
+  # ... with skips
+  
+  test "should infer weekly recurrence for something that occurs every other week" do
+    dates = %w{2012-3-6 2012-3-8 2012-3-20 2012-3-22}
+    schedule = Schedule.infer(dates)
+    assert_equal "Tuesday and Thursday of every other week", schedule.humanize
+  end
+  
+  
+  # ... when some dates are missing from the input array
+  
+  test "should infer a weekly schedule (missing dates)" do
+    dates = %w{2012-3-4 2012-3-11 2012-3-25}
+    schedule = Schedule.infer(dates)
+    assert_equal "Every Sunday", schedule.humanize
+  end
+  
+  test "should infer a schedule that occurs several times a week (missing dates)" do
+    dates = %w{2012-3-6 2012-3-8 2012-3-15 2012-3-20 2012-3-27 2012-3-29}
+    schedule = Schedule.infer(dates)
+    assert_equal "Every Tuesday and Thursday", schedule.humanize
+  end
+  
+  
+  # ... when some dates are wrong in the input group
+  
+  test "should infer a weekly schedule when one day was rescheduled" do
+    dates = %w{2012-10-02 2012-10-09 2012-10-15} # a Tuesday, a Tuesday, and a Monday
+    schedule = Schedule.infer(dates)
+    assert_equal "Every Tuesday", schedule.humanize
+  end
+  
+  test "should infer a weekly schedule when the first day was rescheduled" do
+    dates = %w{2012-10-07 2012-10-10 2012-10-17} # a Sunday, a Wednesday, and a Wednesday
+    schedule = Schedule.infer(dates)
+    assert_equal "Every Wednesday", schedule.humanize
+  end
+  
+  
+  
+  
+  # Correctly identifies scenarios where there is no pattern
+  
+  test "should not try to guess a pattern for input where there is none" do
+    arbitrary_date_ranges = [
+      %w{2013-01-01 2013-03-30 2014-08-19},
+      %w{2012-10-01 2012-10-09 2012-10-17}, # a Monday, a Tuesday, and a Wednesday
+    ]
+    
+    arbitrary_date_ranges.each do |dates|
+      schedule = Schedule.infer(dates)
+      fail "There should be no pattern to the dates #{dates}, but Hiccup guessed \"#{schedule.humanize}\"" unless schedule.never?
+    end
+  end
+  
+  
+  
+  test "should diabolically complex schedules" do
+    dates = %w{2012-11-06 2012-11-08 2012-11-15 2012-11-20 2012-11-27 2012-11-29 2013-02-05 2013-02-14 2013-02-21 2013-02-19 2013-02-26 2013-05-07 2013-05-09 2013-05-16 2013-05-28 2013-05-21 2013-05-30}
+    schedule = Schedule.infer(dates)
+    assert_equal "The first Tuesday, second Thursday, third Thursday, third Tuesday, fourth Tuesday, and fifth Thursday of every third month", schedule.humanize
+  end
+  
+  
+  
+  
+end

data/test/test_helper.rb

@@ -5,3 +5,4 @@ require "rails/test_help"
 require "active_support/core_ext"
 require "turn"
 require "hiccup/schedule"
+require "pry"

metadata

@@ -1,138 +1,201 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: hiccup
-version: !ruby/object:Gem::Version 
+version: !ruby/object:Gem::Version
+  version: 0.3.0
   prerelease: 
-  version: 0.2.1
 platform: ruby
-authors: 
+authors:
 - Bob Lail
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-09-18 00:00:00 -05:00
-default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2012-11-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.2.8
+  type: :runtime
   prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.2.8
+- !ruby/object:Gem::Dependency
+  name: builder
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: ri_cal
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ri_cal
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id002
-- !ruby/object:Gem::Dependency 
-  name: rails
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  version_requirements: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.2.8
   type: :development
-  version_requirements: *id003
-- !ruby/object:Gem::Dependency 
-  name: turn
   prerelease: false
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  version_requirements: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.2.8
+- !ruby/object:Gem::Dependency
+  name: turn
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id004
-- !ruby/object:Gem::Dependency 
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
   name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
   prerelease: false
-  requirement: &id005 !ruby/object:Gem::Requirement 
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id005
-description: Recurrence features a-la-cart
-email: 
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Hiccup mixes a-la-cart recurrence features into your data structure.
+  It doesn't dictate the data structure, just the interface.
+email:
 - bob.lailfamily@gmail.com
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - .gitignore
 - .simplecov
 - Gemfile
+- README.mdown
 - Rakefile
 - hiccup.gemspec
 - lib/hiccup.rb
 - lib/hiccup/convenience.rb
 - lib/hiccup/core_ext/date.rb
 - lib/hiccup/core_ext/duration.rb
+- lib/hiccup/core_ext/enumerable.rb
 - lib/hiccup/core_ext/fixnum.rb
+- lib/hiccup/core_ext/hash.rb
 - lib/hiccup/enumerable.rb
 - lib/hiccup/humanizable.rb
+- lib/hiccup/inferrable.rb
 - lib/hiccup/schedule.rb
 - lib/hiccup/serializable/ical.rb
 - lib/hiccup/serializers/ical.rb
 - lib/hiccup/validatable.rb
 - lib/hiccup/version.rb
+- test/core_ext_date_test.rb
 - test/duration_ext_test.rb
 - test/enumerable_test.rb
 - test/humanizable_test.rb
 - test/ical_serializable_test.rb
+- test/inferrable_test.rb
 - test/test_helper.rb
 - test/validatable_test.rb
-has_rdoc: true
 homepage: http://boblail.github.com/hiccup/
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -955647137280487206
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -955647137280487206
 requirements: []
-
 rubyforge_project: hiccup
-rubygems_version: 1.6.2
+rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
-summary: Recurrence features a-la-cart
-test_files: 
+summary: A library for working with things that recur
+test_files:
+- test/core_ext_date_test.rb
 - test/duration_ext_test.rb
 - test/enumerable_test.rb
 - test/humanizable_test.rb
 - test/ical_serializable_test.rb
+- test/inferrable_test.rb
 - test/test_helper.rb
 - test/validatable_test.rb