temporals 2.0.0

data/History.txt

@@ -0,0 +1,13 @@
+=== 2.0.0 / 2009-11-21
+
+* Moved gem to gemcutter.org
+* Added several examples and specs
+* Made them all work properly
+* The parsing engine is a bit smarter and more flexible
+
+=== 1.0.0 / 2009-08-21
+
+* 1 major enhancement
+
+  * Initial release
+

data/Manifest.txt

@@ -0,0 +1,10 @@
+History.txt
+lib/temporals.rb
+lib/temporals/parser.rb
+lib/temporals/patterns.rb
+lib/temporals/ruby_ext.rb
+lib/temporals/types.rb
+Manifest.txt
+Rakefile
+README.txt
+spec/temporals_spec.rb

data/README.txt

@@ -0,0 +1,98 @@
+= temporals
+
+* Homepage: http://dcparker.github.com/temporals
+* Code: http://github.com/dcparker/temporals
+
+== DESCRIPTION:
+
+"We could develop some interpreter that would be able to parse and process a range of expressions that we might want to deal with. This would be quite flexible, but also pretty hard" (Martin Fowler, http://martinfowler.com/apsupp/recurring.pdf). Temporals is a Ruby parser for just that.
+
+== FEATURES:
+
+Temporals can parse the following expressions:
+
+  * "2-4pm every thursday"
+  * "2:30-3p every mon and wed and 3-3:30 on friday"
+  * "Thursdays in 2009 and 9 January 2009"
+  * "Third Wednesday and Thursday Aug at 3pm"
+  * "2pm Fridays in January 2009 and Thursdays in 2009"
+  * "1st Thursdays at 4-5pm and First - Fourth of March at 2-3:30pm"
+  * "1st-2nd and last Thursdays of March and April 5-6:30pm and March 16th - 24th at 2-2:30pm"
+  * ...and probably more that you are going to waste your time thinking of.
+
+Temporals is NOT GUARANTEED to parse anything you give it. It has a limited, though rather large and flexible, vocabulary.
+If you come across something that doesn't parse properly, please write a spec test for it and send it to me: gems@behindlogic.com.
+
+== PROBLEMS:
+
+* Should add support for "4th of the month" or "4th month"
+
+== SYNOPSIS:
+
+Temporals works to follow the true spirit of the TimePoint pattern -- the idea that every expression of time in fact has a certain level of intended precision. For example, if I say "March 5, 2000", I simply mean any time within that day -- all day. However, if I say "2:05pm March 5, 2000", I mean any second within that specific minute. But if I say "2:00pm Fridays" I really mean every Friday, and that expression is precise to the day-of-week and to the hour and minute, but the second, week, month, or year don't matter.
+The main usage of Temporals, as it currently has been built for, is Temporals.parse and Temporals#include?. Here are several examples:
+
+Example Expressions:
+	# All day Tuesday, every week
+	  t1 = Temporals.parse('Tuesday')
+	
+	# Every Feb 24, all day long
+	  t2 = Temporals.parse("February 24th")
+	
+	# Feb 24 in 2001, all day long
+	  t3 = Temporals.parse("24 February 2001")
+	
+	# every Thursday in 2009, and the 9th of January 2009 too
+	  t4 = Temporals.parse("9 January 2009 and Thursday 2009")
+	
+	# default duration of ONE of the most specific piece mentioned: 2-3pm every
+	# friday in January of '09, and also all day every thursday all year in 2009
+	  t5 = Temporals.parse("2pm Fridays in January 2009 and Thursdays in 2009")
+
+	# first thursday of every month, forever, from 4 to 5 pm;
+	# also 2 to 3:30 pm on the 1st, 2nd, 3rd, and 4th of March (every year!)
+	  t6 = Temporals.parse("1st Thursdays at 4-5pm and 1st - 4th of March at 2pm")
+	
+	# you can figure this one out for yourself... Then figure out how the parsing knows exactly what this means! :P
+	  t7 = Temporals.parse("1st-2nd and 4th Thursdays of March and April 5-6:30pm and March 16th - 24th at 2-2:30pm")
+	
+More methods available (referencing some of the above examples):
+	t5.include?(Time.parse('2009-02-05 19:00:00')) => true
+	t5.include?(Time.parse('2009-01-09 2:31pm')) => true
+	t5.include?(Time.parse('February 5, 2010')) => false
+	t5.include?(Time.parse('January 16, 2007')) => false
+	t6.occurrances_on_day(Time.parse('2009-04-02')) => [{:start_time=>Thu Apr 02 16:00:00 2009, :end_time=>Thu Apr 02 17:00:00 2009}, {:start_time=>Thu Apr 02 14:00:00 2009, :end_time=>Thu Apr 02 15:30:00 2009}]
+	t7.occurs_on_day?(Time.parse('2009-03-05')) => true
+
+== REQUIREMENTS:
+
+* Just Ruby!
+
+== INSTALL
+
+* gem install temporals -s http://gemcutter.org
+
+## License ##
+
+(The MIT License)
+
+Copyright (c) 2009 BehindLogic <gems@behindlogic.com>
+
+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

@@ -0,0 +1,9 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+
+Hoe.spec 'temporals' do
+  developer 'Daniel Parker', 'gems@behindlogic.com'
+  self.url = "http://dcparker.github.com/temporals"
+end

data/lib/temporals.rb

@@ -0,0 +1,116 @@
+
+require 'date'
+require 'time'
+require 'temporals/ruby_ext'
+require 'temporals/types'
+require 'temporals/patterns'
+require 'temporals/parser'
+
+class Temporal
+  VERSION = '2.0.0'
+
+  def initialize(options)
+    options.each do |key,value|
+      instance_variable_set(:"@#{key}", value)
+    end
+  end
+
+  def [](key)
+    instance_variable_get(:"@#{key}")
+  end
+
+  def start_pm?
+    if @start_time =~ /([ap])m$/ || @end_time =~ /([ap])m$/
+      $1 == 'p'
+    else
+      nil
+    end
+  end
+
+  def include?(datetime)
+    return false unless occurs_on_day?(datetime)
+    if @type =~ /timerange/
+      test_date = datetime.strftime("%Y-%m-%d")
+      test_start_time = Time.parse("#{test_date} #{@start_time.gsub(/([ap]m)$/,'')}#{start_pm? ? 'pm' : 'am'}")
+      test_end_time = Time.parse("#{test_date} #{@end_time}")
+      test_end_time = test_end_time+59 if test_end_time == test_start_time # If they're equal, they are assumed to be to the minute precision
+      puts "TimeRange: date:#{test_date} test_start:#{test_start_time} test_end:#{test_end_time} <=> #{datetime}" if $DEBUG
+      return false unless datetime.between?(test_start_time, test_end_time)
+    end
+    return true
+    puts "#{datetime} Included!" if $DEBUG
+  end
+
+  def occurs_on_day?(datetime)
+    puts "#{datetime} IN? #{inspect}" if $DEBUG
+    if @type =~ /month/
+      puts "Month #{Month.order[datetime.month-1].inspect} == #{@month.inspect} >> #{Month.order[datetime.month-1].value_in?(@month)}" if $DEBUG
+      return false unless Month.order[datetime.month-1].value_in?(@month)
+    end
+    if @type =~ /ord_wday/
+      puts "Weekday: #{WDay.order[datetime.wday].inspect} in? #{@wday.inspect} == #{WDay.order[datetime.wday].value_in?(@wday)}" if $DEBUG
+      return false unless WDay.order[datetime.wday].value_in?(@wday)
+      puts "WeekdayOrd: #{datetime.wday_ord} in? #{@ord.inspect} == #{datetime.wday_ord.value_in?(@ord)}" if $DEBUG
+      puts "WeekdayLast: #{datetime.wday_last} in? #{@ord.inspect} == #{datetime.wday_last.value_in?(@ord)}" if $DEBUG
+      return false unless datetime.wday_ord.value_in?(@ord) || datetime.wday_last.value_in?(@ord)
+    end
+    if @type =~ /month_ord/
+      puts "Day #{datetime.day} == #{@ord.inspect} >> #{datetime.day.value_in?(@ord)}" if $DEBUG
+      return false unless datetime.day.value_in?(@ord)
+    end
+    if @type =~ /year/
+      puts "Year #{datetime.year} == #{@year.inspect} >> #{datetime.year.value_in?(@year)}" if $DEBUG
+      return false unless datetime.year.value_in?(@year)
+    end
+    if @type =~ /wday/
+      puts "Weekday: #{WDay.order[datetime.wday].inspect} in? #{@wday.inspect} == #{WDay.order[datetime.wday].value_in?(@wday)}" if $DEBUG
+      return false unless WDay.order[datetime.wday].value_in?(@wday)
+    end
+    puts "Occurs on #{datetime}!" if $DEBUG
+    return true
+  end
+
+  def occurrances_on_day(date)
+    occurs_on_day?(date) ? [{:start_time => start_time(date), :end_time => end_time(date)}] : []
+  end
+
+  def start_time(date=nil)
+    if date
+      @start_time.sub!(/^(\d+)/,'\1:00') if @start_time =~ /^(\d+)[^:]/
+      puts "#{date.strftime("%Y-%m-%d")} #{@start_time}" if $DEBUG
+      Time.parse("#{date.strftime("%Y-%m-%d")} #{@start_time}")
+    else
+      @start_time
+    end
+  end
+  def end_time(date=nil)
+    if date
+      @end_time.sub!(/^(\d+)/,'\1:00') if @end_time =~ /^(\d+)[^:]/
+      puts "#{date.strftime("%Y-%m-%d")} #{@end_time}" if $DEBUG
+      Time.parse("#{date.strftime("%Y-%m-%d")} #{@end_time}")
+    else
+      @end_time
+    end
+  end
+
+  def to_natural
+    @type.split(/_/).collect {|w|
+      case w
+      # when 'ord'
+      #   if @ord.respond_to?(:to_natural)
+      #     @ord.to_natural('ord')
+      #   end
+      #   if @ord.is_a?(Range)
+      #     @ord.begin + 'th-' + @ord.end
+      #   elsif @ord.is_a?(Array)
+      #     
+      #   else
+      #     @ord + 'th'
+      #   end
+      when 'dummy'
+      else
+        instance_variable_get('@'+w)
+      end
+    }.join(' ')
+  end
+end

data/lib/temporals/parser.rb

@@ -0,0 +1,140 @@
+class Temporal
+  class << self
+    def parse(expression)
+      puts "Parsing expression: #{expression.inspect}" if $DEBUG
+      # 1. Normalize the expression
+      # TODO: re-create normalize: ' -&| ', 'time-time'
+      expression.gsub!(/\s+/,' ').gsub!(/([\-\&\|])/,' \1 ')
+      expression.gsub!(/(#{TimeRegexp}?) +- +(#{TimeRegexp})/,'\1-\2')
+      expression.gsub!(/in ([09]\d|\d{4})/) {|s|
+        y = $1
+        y.length == 2 ? (y =~ /^0/ ? '20'+y : '19'+y) : y
+      }
+      expression.gsub!(/(^| )(#{TimeRegexp})( |$)/i) {|s|
+        b = $1
+        time = $2
+        a = $3
+        if s =~ /[:m]/ # If it really looks like a lone piece of time, it'll have either a am/pm or a ':' in it.
+          # Converting a floating time into a timerange that spans the appropriate duration
+          puts "Converting Time to TimeRange: #{time.inspect}" if $DEBUG
+          # Figure out what precision we're at
+          newtime = time + '-'
+          if time =~ /(\d+):(\d+)([ap]m?|$)?/
+            end_hr = $1.to_i
+            end_mn = $2.to_i + 1
+            if end_mn > 59
+              end_mn -= 60
+              end_hr += 1
+            end
+            end_hr -= 12 if end_hr > 12
+            newtime += "#{end_hr}:#{end_mn}#{$3}" # end-time is 1 minute later
+          elsif time =~ /(\d+)([ap]m?|$)?/
+            end_hr = $1.to_i + 1
+            end_hr -= 12 if end_hr > 12
+            newtime += "#{end_hr}#{$2}" # end-time is 1 hour later
+          end
+          puts "Converted! #{newtime}" if $DEBUG
+          b+newtime+a
+        else
+          s
+        end
+      }
+      puts "Normalized expression: #{expression.inspect}" if $DEBUG
+
+      # 2. Analyze the expression
+      words = expression.split(/\s+/)
+      puts words.inspect if $DEBUG
+      analyzed_expression = words.inject([]) do |a,word|
+        a << case word
+        when WordTypes[:ord]
+          {:type => 'ord', :ord => $1}
+        when WordTypes[:word_ord]
+          ord = WordOrds.include?(word.downcase) ? WordOrds.index(word.downcase)+1 : 'last'
+          puts "WordOrd: #{ord}" if $DEBUG
+          {:type => 'ord', :ord => ord}
+        when WordTypes[:wday]
+          {:type => 'wday', :wday => WDay.normalize($1)}
+        when WordTypes[:year]
+          {:type => 'year', :year => word}
+        when WordTypes[:month]
+          {:type => 'month', :month => Month.normalize(word)}
+        when WordTypes[:union]
+          {:type => 'union'}
+        when WordTypes[:range]
+          {:type => 'range'}
+        when WordTypes[:timerange]
+          # determine and inject am/pm
+          start_at = $1
+          end_at = $2
+          start_at_p = $1 if start_at =~ /([ap])m?$/
+          end_at_p = $1 if end_at =~ /([ap])m?$/
+          start_hr = start_at.split(/:/)[0].to_i
+            start_hr = '0' if start_hr == '12' # this is used only for > & < comparisons, so converting it to 0 makes everything easier.
+          end_hr = end_at.split(/:/)[0].to_i
+          if start_at_p && !end_at_p
+            # If end-time is a lower hour number than start-time, then we've crossed noon or midnight, and the end-time a/pm should be opposite.
+            end_at = end_at + (start_hr <= end_hr ? start_at_p : (start_at_p=='a' ? 'p' : 'a'))
+          elsif end_at_p && !start_at_p
+            # If end-time is a lower hour number than start-time, then we've crossed noon or midnight, and the start-time a/pm should be opposite.
+            start_at = start_at + (start_hr <= end_hr ? end_at_p : (end_at_p=='a' ? 'p' : 'a'))
+          elsif !end_at_p && !start_at_p
+            # If neither had am/pm attached, assume am if after 7, pm if 12 or before 7.
+            start_at_p = (start_hr < 8 ? 'p' : 'a')
+            start_at = start_at + start_at_p
+            # If end-time is a lower hour number than start-time, then we've crossed noon or midnight, and the end-time a/pm should be opposite.
+            end_at = end_at + (start_hr <= end_hr ? start_at_p : (start_at_p=='a' ? 'p' : 'a'))
+          end
+          start_at += 'm' unless start_at =~ /m$/
+          end_at += 'm' unless end_at =~ /m$/
+          {:type => 'timerange', :start_time => start_at, :end_time => end_at}
+        end
+      end.compact
+      def analyzed_expression.collect_types
+        collect {|e|
+          puts "E: #{e.inspect}" if $DEBUG
+          e[:type]
+          }
+      end
+
+      # 3. Combine common patterns
+      puts analyzed_expression.inspect if $DEBUG
+      puts analyzed_expression.collect_types.inspect if $DEBUG
+
+      something_was_modified = true
+      while something_was_modified
+        something_was_modified = false
+        before_length = analyzed_expression.length
+        CommonPatterns.each do |pattern|
+          while i = analyzed_expression.collect_types.includes_sequence?(pattern.split(/ /))
+            CommonPatternActions[pattern].call(analyzed_expression,i)
+          end
+        end
+        after_length = analyzed_expression.length
+        something_was_modified = true if before_length != after_length
+      end
+      
+      puts analyzed_expression.inspect if $DEBUG
+      puts analyzed_expression.collect_types.inspect if $DEBUG
+
+      # What remains should be simply sections of boolean logic
+      # 4. Parse boolean logic
+      analyzed_expression.each_index do |i|
+        analyzed_expression[i] = Temporal.new(analyzed_expression[i]) unless analyzed_expression[i][:type].in?('union', 'range')
+      end
+
+      BooleanPatterns.each do |pattern|
+        while i = analyzed_expression.collect_types.includes_sequence?(pattern.split(/ /))
+          BooleanPatternActions[pattern].call(analyzed_expression,i)
+          break if analyzed_expression.length == 1
+        end
+      end
+
+      # This is how we know if the expression couldn't quite be figured out. It should have been condensed down to a single Temporal or Temporal::Set
+      if analyzed_expression.length > 1
+        raise RuntimeError, "Could not parse Temporal Expression: check to make sure it is clear and has only one possible meaning."
+      end
+
+      return analyzed_expression[0]
+    end
+  end
+end

data/lib/temporals/patterns.rb

@@ -0,0 +1,167 @@
+class Temporal
+  TimeRegexp = '\d{1,2}(?::\d\d)?(?::\d{1,2})?(?:[ap]m?)?'
+  WordOrds = %w(first second third fourth fifth)
+  WordTypes = {
+    :ord => /^([1-3]?\d)(?:st|nd|rd|th)?$/i, # Should be able to distinguish
+    :word_ord => /^(first|second|third|fourth|fifth|last)$/i,
+    :wday => /^(#{(WDay.order + WDay.translations.keys).join('|')})s?$/i,
+    :month => /^#{(Month.order + Month.translations.keys).join('|')}$/i,
+    :year => /^([09]\d|\d{4})$/, # A year will be either 2 digits starting with a 9 or a 0, or 4 digits.
+    :union => /^(?:and)$/i,
+    :range => /^(?:-|to|through)$/i,
+    :timerange => /^(#{TimeRegexp}?)-(#{TimeRegexp})$/i,
+    # :from => /^from$/i,
+    # :to => /^to$/i,
+    # :between => /^between$/i
+  }
+
+  # These are in a specific order
+  CommonPatterns = [
+    'ord range ord',
+    'ord union ord',
+    'year range year',
+    'year union year',
+    'wday range wday',
+    'wday union wday',
+    # 'timerange union timerange', # Not quite figured out yet, I'd need to implement new code into the question methods.
+    'month ord',
+    'ord month',
+    'ord wday',
+    'month_ord timerange',
+    'month union month',
+    'month range month',
+    'ord_wday month',
+    'ord_wday timerange',
+    'ord_wday_month timerange',
+    'timerange wday',
+    'month_ord year',
+    'month year',
+    'wday year',
+    "wday_timerange month",
+    "wday_timerange year",
+    "wday_timerange month_year"
+  ]
+  CommonPatternActions = {
+    'ord range ord' => lambda {|words,i|
+      words[i][:ord] = (words[i][:ord].to_i..words[i+2][:ord].to_i)
+      words.slice!(i+1,2)
+    },
+    'ord union ord' => lambda {|words,i|
+      words[i][:ord] = ArrayOfRanges.new(words[i][:ord], words[i+2][:ord])
+      words.slice!(i+1,2)
+    },
+    'year range year' => lambda {|words,i|
+      words[i][:year] = (words[i][:year].to_i..words[i+2][:year].to_i)
+      words.slice!(i+1,2)
+    },
+    'year union year' => lambda {|words,i|
+      words[i][:year] = ArrayOfRanges.new(words[i][:year], words[i+2][:year])
+      words.slice!(i+1,2)
+    },
+    'wday range wday' => lambda {|words,i|
+      words[i][:wday] = (words[i][:wday].to_i..words[i+2][:wday].to_i)
+      words.slice!(i+1,2)
+    },
+    'wday union wday' => lambda {|words,i|
+      words[i][:wday] = ArrayOfRanges.new(words[i][:wday], words[i+2][:wday])
+      words.slice!(i+1,2)
+    },
+    # 'timerange union timerange' => lambda {|words,i|
+    #   words[i][:wday] = ArrayOfRanges.new(words[i][:wday], words[i+2][:wday])
+    #   words.slice!(i+1,2)
+    # },
+    'month ord' => lambda {|words,i|
+      words[i][:type] = 'month_ord'
+      words[i][:ord] = words[i+1][:ord]
+      words.slice!(i+1,1)
+    },
+    'ord month' => lambda {|words,i|
+      words[i][:type] = 'month_ord'
+      words[i][:month] = words[i+1][:month]
+      words.slice!(i+1,1)
+    },
+    'ord wday' => lambda {|words,i|
+      words[i][:type] = 'ord_wday'
+      words[i][:wday] = words[i+1][:wday]
+      words.slice!(i+1,1)
+    },
+    'month_ord timerange' => lambda {|words,i|
+      words[i][:type] = 'month_ord_timerange'
+      words[i][:start_time] = words[i+1][:start_time]
+      words[i][:end_time] = words[i+1][:end_time]
+      words.slice!(i+1,1)
+    },
+    'month union month' => lambda {|words,i|
+      words[i][:month] = ArrayOfRanges.new(words[i][:month], words[i+2][:month])
+      words.slice!(i+1,2)
+    },
+    'month range month' => lambda {|words,i|
+      raise "Not Implemented Yet!"
+    },
+    'ord_wday month' => lambda {|words,i|
+      words[i][:type] = 'ord_wday_month'
+      words[i][:month] = words[i+1][:month]
+      words.slice!(i+1,1)
+    },
+    'ord_wday timerange' => lambda {|words,i|
+      words[i][:type] = 'ord_wday_timerange'
+      words[i][:start_time] = words[i+1][:start_time]
+      words[i][:end_time] = words[i+1][:end_time]
+      words.slice!(i+1,1)
+    },
+    'timerange wday' => lambda {|words,i|
+      words[i][:type] = 'wday_timerange'
+      words[i][:wday] = words[i+1][:wday]
+      words.slice!(i+1,1)
+    },
+    'ord_wday_month timerange' => lambda {|words,i|
+      words[i][:type] = 'ord_wday_month_timerange'
+      words[i][:start_time] = words[i+1][:start_time]
+      words[i][:end_time] = words[i+1][:end_time]
+      words.slice!(i+1,1)
+    },
+    'month_ord year' => lambda {|words,i|
+      words[i][:type] = 'ord_month_year'
+      words[i][:year] = words[i+1][:year]
+      words.slice!(i+1,1)
+    },
+    'wday year' => lambda {|words,i|
+      words[i][:type] = 'wday_year'
+      words[i][:year] = words[i+1][:year]
+      words.slice!(i+1,1)
+    },
+    'month year' => lambda {|words,i|
+      words[i][:type] = 'month_year'
+      words[i][:year] = words[i+1][:year]
+      words.slice!(i+1,1)
+    },
+    'wday_timerange month' => lambda {|words,i|
+      words[i][:type] = 'wday_timerange_month'
+      words[i][:month] = words[i+1][:month]
+      words.slice!(i+1,1)
+    },
+    'wday_timerange year' => lambda {|words,i|
+      words[i][:type] = 'wday_timerange_year'
+      words[i][:year] = words[i+1][:year]
+      words.slice!(i+1,1)
+    },
+    'wday_timerange month_year' => lambda {|words,i|
+      words[i][:type] = 'wday_timerange_month_year'
+      words[i][:month] = words[i+1][:month]
+      words[i][:year] = words[i+1][:year]
+      words.slice!(i+1,1)
+    }
+  }
+
+  BooleanPatterns = [
+    'union'
+  ]
+
+  BooleanPatternActions = {
+    'union' => lambda {|words,i|
+      words[i-1] = Temporal::Union.new(words[i-1], words[i+1])
+      words.slice!(i,2)
+      puts "Boolean-connected: " + words.inspect if $DEBUG
+    }
+  }
+end

data/lib/temporals/ruby_ext.rb

@@ -0,0 +1,59 @@
+class Array
+  def includes_sequence?(sequence)
+    first_exists = []
+    each_index do |i|
+      first_exists << i if self[i] == sequence[0]
+    end
+    first_exists.any? do |i|
+      return i if self[i...(i+sequence.length)] == sequence
+    end
+  end
+
+  def include_value?(v)
+    any? do |iv|
+      case iv
+      when Range || Array
+        v.to_i.in?(iv)
+      else
+        if iv.to_s =~ /^\d+$/ && v.to_s =~ /^\d+$/
+          iv.to_i == v.to_i
+        else
+          iv.to_s == v.to_s
+        end
+      end
+    end
+  end
+end
+
+class Range
+  alias :include_value? :include?
+end
+
+class Object
+  def value_in?(*arg)
+    arg = arg[0] if arg.length == 1 && arg[0].respond_to?(:include_value?)
+    arg.include_value?(self)
+  end
+  def in?(*arg)
+    arg = arg[0] if arg.length == 1 && arg[0].respond_to?(:include?)
+    arg.include?(self)
+  end
+  def my_methods
+    methods.sort - Object.methods
+  end
+end
+
+module WdayOrd
+  def wday_ord
+    (day.to_f / 7).ceil
+  end
+  def wday_last
+    'last' if day.to_i + 7 > Date.new(year, month, -1).day
+  end
+end
+class DateTime
+  include WdayOrd
+end
+class Time
+  include WdayOrd
+end

data/lib/temporals/types.rb

@@ -0,0 +1,125 @@
+class Temporal
+  class ArrayOfRanges < Array
+    def self.new(*values)
+      n = allocate
+      n.push(*values)
+      n
+    end
+  end
+
+  class Classification
+    class << self
+      attr_reader :order, :translations
+
+      def abbreviations
+        @abbreviations ||= translations.inject({}) do |h,(k,v)|
+          h[v] = k unless h.has_key?(v) && h[v].length < k.length
+          h
+        end
+      end
+
+      def normalize(word)
+        word = word.capitalize
+        order.include?(word) ? word : (translations.has_key?(word) ? translations[word] : nil)
+      end
+    end
+  end
+
+  class WDay < Classification
+    @order = %w(Sunday Monday Tuesday Wednesday Thursday Friday)
+    @translations = {
+      'S' => 'Sunday',
+      'M' => 'Monday',
+      'T' => 'Tuesday',
+      'W' => 'Wednesday',
+      'Th' => 'Thursday',
+      'F' => 'Friday',
+      'Sa' => 'Saturday',
+      'Sun' => 'Sunday',
+      'Mo' => 'Monday',
+      'Mon' => 'Monday',
+      'Tu' => 'Tuesday',
+      'Tue' => 'Tuesday',
+      'Tues' => 'Tuesday',
+      'Wed' => 'Wednesday',
+      'Thu' => 'Thursday',
+      'Thur' => 'Thursday',
+      'Thurs' => 'Thursday',
+      'Fri' => 'Friday',
+      'Sat' => 'Saturday'
+    }
+  end
+  class Month < Classification
+    @order = %w(January February March April May June July August September October November December)
+    @translations = {
+      'Jan' => 'January',
+      'Feb' => 'February',
+      'Mar' => 'March',
+      'Apr' => 'April',
+      'Jun' => 'June',
+      'Jul' => 'July',
+      'Aug' => 'August',
+      'Sep' => 'September',
+      'Oct' => 'October',
+      'Nov' => 'November',
+      'Dec' => 'December'
+    }
+  end
+
+  class Set
+    def set
+      @set ||= []
+    end
+
+    def [](key)
+      instance_variable_get(:"@#{key}")
+    end
+
+    def initialize(*args)
+      # @set = args.select {|e| e.is_a?(Temporal) || e.is_a?(Range)}
+      @set = args.select {|e| e.is_a?(Temporal)}
+    end
+  end
+  class Union < Set
+    def initialize(*args)
+      @type = 'UNION'
+      super
+    end
+
+    def include?(other)
+      set.any? {|tp| tp.include?(other)}
+    end
+
+    def occurs_on_day?(other)
+      set.any? {|tp| tp.occurs_on_day?(other)}
+    end
+
+    def occurrances_on_day(other)
+      set.inject([]) {|a,tp| a.concat(tp.occurrances_on_day(other)); a}
+    end
+
+    def eql?(other)
+      if other.is_a?(Temporal::Union)
+        set.length == other.length && set.length.times { |i| return false unless set[i].eql? other[i] }
+      else
+        # what else can we compare to?
+        raise "Comparison of Temporal::Union with something different (#{other.class.name})."
+      end
+    end
+
+    def to_natural
+      set.inject([]) {|a,tp| a << tp.to_natural}.join(' and ')
+    end
+
+    private
+    # Sends all other methods to the set array.
+    def method_missing(name, *args, &block)
+      if set.respond_to?(name)
+        args << block if block_given?
+        set.send(name, *args)
+      else
+        super
+      end
+    end
+  end
+end

data/spec/temporals_spec.rb

@@ -0,0 +1,103 @@
+require 'rubygems'
+require 'spec'
+require File.dirname(__FILE__) + '/../lib/temporals'
+
+describe Temporal do
+  it "1st-2nd and last Thursdays of March and April 5-6:30pm and March 16th - 24th at 2-2:30pm" do
+    t = Temporal.parse("1st-2nd and last Thursdays of March and April 5-6:30pm and March 16th - 24th at 2-2:30pm")
+    t.include?(Time.parse('2009-03-05 17:54')).should eql(true)
+    t.include?(Time.parse('2009-03-05 18:24')).should eql(true)
+    t.include?(Time.parse('2009-03-05 18:30')).should eql(true)
+    t.include?(Time.parse('2009-03-05 18:31')).should eql(false)
+    t.include?(Time.parse('2009-04-26 18:31')).should eql(false)
+    t.occurs_on_day?(Time.parse('2009-03-04')).should eql(false)
+    t.occurs_on_day?(Time.parse('2009-03-11')).should eql(false)
+    t.occurs_on_day?(Time.parse('2009-03-25')).should eql(false)
+    t.occurs_on_day?(Time.parse('2009-04-01')).should eql(false)
+    t.occurs_on_day?(Time.parse('2009-04-08')).should eql(false)
+    t.occurs_on_day?(Time.parse('2009-04-22')).should eql(false)
+    t.occurs_on_day?(Time.parse('2009-03-05')).should eql(true)
+    t.occurs_on_day?(Time.parse('2009-03-12')).should eql(true)
+    t.occurs_on_day?(Time.parse('2009-03-26')).should eql(true)
+    t.occurs_on_day?(Time.parse('2009-04-02')).should eql(true)
+    t.occurs_on_day?(Time.parse('2009-04-09')).should eql(true)
+    t.occurs_on_day?(Time.parse('2009-04-30')).should eql(true)
+    t.occurs_on_day?(Time.parse('2009-03-06')).should eql(false)
+    t.occurs_on_day?(Time.parse('2009-03-13')).should eql(false)
+    t.occurs_on_day?(Time.parse('2009-03-27')).should eql(false)
+    t.occurs_on_day?(Time.parse('2009-04-03')).should eql(false)
+    t.occurs_on_day?(Time.parse('2009-04-10')).should eql(false)
+    t.occurs_on_day?(Time.parse('2009-04-24')).should eql(false)
+    t.occurrances_on_day(Time.parse('2009-04-23')).length.should eql(0)
+    t.occurrances_on_day(Time.parse('2009-04-30')).length.should eql(1)
+  end
+
+  it "1st Thursdays at 4-5pm and First - Fourth of March at 2-3:30pm" do
+    t = Temporal.parse("1st Tuesdays at 4-5pm and First - Fourth of March at 2-3:30pm")
+    t.occurs_on_day?(Time.parse('2009-04-07')).should eql(true)
+    t.occurrances_on_day(Time.parse('2009-03-01')).length.should eql(1)
+    t.occurrances_on_day(Time.parse('2009-03-03')).length.should eql(2)
+    t.occurrances_on_day(Time.parse('2009-05-05')).length.should eql(1)
+    t.occurrances_on_day(Time.parse('2009-05-12')).length.should eql(0)
+  end
+
+  it "should FAIL on 1st Thursdays at 4-5pm and First - Fourth of March and April at 2-3:30pm" do
+    lambda {
+      # This could be grouped in two different ways. The first is more likely what is meant, but
+      # the second is possible so the patterns are not set up to match the first option for sure.
+      #  (1st Thursdays at 4-5pm) and ((First - Fourth of March and April) at 2-3:30pm)
+      #  (1st Thursdays at 4-5pm) and (First - Fourth of March) and (April at 2-3:30pm)
+      Temporal.parse("1st Thursdays at 4-5pm and First - Fourth of March and April at 2-3:30pm")
+    }.should raise_error(RuntimeError, "Could not parse Temporal Expression: check to make sure it is clear and has only one possible meaning.")
+  end
+
+  it "2pm Tuesdays" do
+    t = Temporal.parse("2pm Tuesdays")
+    t.occurs_on_day?(Time.parse('2009-04-28')).should eql(true)
+    t.occurrances_on_day(Time.parse('2009-04-28')).length.should eql(1)
+    t.occurrances_on_day(Time.parse('2009-04-28'))[0][:start_time].should eql(Time.parse('2009-04-28 2:00pm'))
+    t.occurrances_on_day(Time.parse('2009-04-28'))[0][:end_time].should eql(Time.parse('2009-04-28 3pm'))
+    t.include?(Time.parse('2009-04-21 14:52')).should eql(true)
+    t.include?(Time.parse('2009-04-21 14:59:59')).should eql(true)
+  end
+
+  it "2:30pm Tuesdays" do
+    t = Temporal.parse("2:30pm Tuesdays")
+    t.occurs_on_day?(Time.parse('2009-04-28')).should eql(true)
+    t.occurrances_on_day(Time.parse('2009-04-28')).length.should eql(1)
+    t.occurrances_on_day(Time.parse('2009-04-28'))[0][:start_time].should eql(Time.parse('2009-04-28 2:30pm'))
+    t.occurrances_on_day(Time.parse('2009-04-28'))[0][:end_time].should eql(Time.parse('2009-04-28 2:31pm'))
+    t.include?(Time.parse('2009-04-21 14:30')).should eql(true)
+    t.include?(Time.parse('2009-04-21 14:30:59')).should eql(true)
+    t.include?(Time.parse('2009-04-21 14:31')).should eql(true)
+    t.include?(Time.parse('2009-04-21 14:31:01')).should eql(false)
+  end
+
+  it "2:30-3p every mon and wed and 3-3:30 on friday" do
+    t = Temporal.parse("2:30-3p every mon and wed and 3-3:30 on friday")
+    t.occurs_on_day?(Time.parse('2009-11-20')).should eql(true)
+    t.occurs_on_day?(Time.parse('2009-11-19')).should eql(false)
+    t.occurs_on_day?(Time.parse('2009-11-18')).should eql(true)
+    t.occurrances_on_day(Time.parse('2009-11-20'))[0][:start_time].should eql(Time.parse('2009-11-20 3pm'))
+    t.occurrances_on_day(Time.parse('2009-11-18'))[0][:end_time].should eql(Time.parse('2009-11-18 3pm'))
+    t.include?(Time.parse('2009-11-20 3:14pm')).should eql(true)
+  end
+
+  it "Thursdays in 2009 and 9 January 2009" do
+    t = Temporal.parse("Thursdays in 2009 and 9 January 2009")
+    t.occurs_on_day?(Time.parse('January 9, 2009')).should eql(true)
+    t.occurs_on_day?(Time.parse('November 19, 2009')).should eql(true)
+    t.occurs_on_day?(Time.parse('October 19, 2009')).should eql(false)
+    t.include?(Time.parse('2009-01-08 3:14pm')).should eql(true)
+  end
+
+  it "2pm Fridays in January 2009 and Thursdays in 2009" do
+    t = Temporal.parse("2pm Fridays in January 2009 and Thursdays in 2009")
+    t.occurs_on_day?(Time.parse('November 19, 2009')).should eql(true)
+    t.occurs_on_day?(Time.parse('January 9, 2009')).should eql(true)
+    t.occurs_on_day?(Time.parse('October 19, 2009')).should eql(false)
+    t.include?(Time.parse('2009-01-08 3:14pm')).should eql(true)
+    t.include?(Time.parse('2009-01-09 2:14pm')).should eql(true)
+    t.include?(Time.parse('2009-01-09 3:14pm')).should eql(false)
+  end
+end

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification 
+name: temporals
+version: !ruby/object:Gem::Version 
+  version: 2.0.0
+platform: ruby
+authors: 
+- Daniel Parker
+autorequire: 
+bindir: bin
+cert_chain: 
+- |
+  -----BEGIN CERTIFICATE-----
+  MIIDNjCCAh6gAwIBAgIBADANBgkqhkiG9w0BAQUFADBBMQ0wCwYDVQQDDARnZW1z
+  MRswGQYKCZImiZPyLGQBGRYLYmVoaW5kbG9naWMxEzARBgoJkiaJk/IsZAEZFgNj
+  b20wHhcNMDkxMTE5MDQ0NzIzWhcNMTAxMTE5MDQ0NzIzWjBBMQ0wCwYDVQQDDARn
+  ZW1zMRswGQYKCZImiZPyLGQBGRYLYmVoaW5kbG9naWMxEzARBgoJkiaJk/IsZAEZ
+  FgNjb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDs+2PvSoBC5mCz
+  Nm95RXKOb/u+CmPA70DoG9cF0zipCie003Vm0DYL3Rtobcr32eMvHxkWoJ6xoz0I
+  h74yNKtHjTTCxj86HWBPsE6xVMxVCftClndjCyKsiMiqvvp1wDNO0FFK+6LijmL3
+  2Xkp4brWq1JO92y9vYct34R7o2X//+nwZs+sss+EYhNdvdUJfWy7tA5dghGdLvRn
+  UhJJSAtTefkBCwO7bufLEt+n7wIRbiJJ5dDCwE3NIX4wUSrNeYwXGXA/Ybki+BUl
+  3KJF9IC0XR9fY9DGF0FXBKrkfDlZRrnQOem2aIxeuln0KQLJXXJuDTQPHO+mK3EG
+  UPhR7IAHAgMBAAGjOTA3MAkGA1UdEwQCMAAwCwYDVR0PBAQDAgSwMB0GA1UdDgQW
+  BBQn32ZStKmqwFqs2vuglYzkvDzBZjANBgkqhkiG9w0BAQUFAAOCAQEAe3Z+iMmy
+  IX9ChQW4hNNb1HOpgCMc2RL+vUwku9WE95dZ+BE4A6mOYTj5JXdYf4R4Z2vavr+d
+  nwJWtXPeIBWxireb8gUU0DwqodYTpsmkj5LD1zIaZ59rXlwDA9O0V4fwE1iRG5MD
+  mB7m8fT8WNOeg4AfjH4aSiHI1+HX1RQkc7KFdLotKnCevzYU6Jza5VUbXyJ+yCEH
+  DFARN3mkfGI+18MRDEi39nK2O/bBd6Wf0cYPEKsGQjNNAIBtv9belepSMd1KKfQ2
+  L7j8CnNDCrsHDe7/251D85wSvTH4Q/41NE5ahdCkkHwzDJeyhXpmNuUSswdn7woz
+  teST6sOe8lUhZQ==
+  -----END CERTIFICATE-----
+
+date: 2009-11-21 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 2.3.3
+    version: 
+description: "\"We could develop some interpreter that would be able to parse and process a range of expressions that we might want to deal with. This would be quite flexible, but also pretty hard\" (Martin Fowler, http://martinfowler.com/apsupp/recurring.pdf). Temporals is a Ruby parser for just that."
+email: 
+- gems@behindlogic.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- History.txt
+- Manifest.txt
+- README.txt
+files: 
+- History.txt
+- lib/temporals.rb
+- lib/temporals/parser.rb
+- lib/temporals/patterns.rb
+- lib/temporals/ruby_ext.rb
+- lib/temporals/types.rb
+- Manifest.txt
+- Rakefile
+- README.txt
+- spec/temporals_spec.rb
+has_rdoc: true
+homepage: http://dcparker.github.com/temporals
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README.txt
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: temporals
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: "\"We could develop some interpreter that would be able to parse and process a range of expressions that we might want to deal with"
+test_files: []
+