chronic 0.8.0 → 0.9.0

data/HISTORY.md

@@ -1,3 +1,14 @@
+# 0.9.0 / 2012-12-21
+
+* Implement Chronic::Parser class and create an instance of this class
+  instead of leaving all data in the class level of Chronic
+* Various bug fixes
+* Add support for excel date formats (#149, @jmondo)
+* Added support for time expressions such as '10 till' or 'half
+  past two' (#146, @chicagogrooves)
+* Add support for RepeaterDayName, RepeaterMonthName,
+  Ordinal/ScalarDay and Time (#153, @kareemk)
+
 # 0.8.0 / 2012-09-16
 
 * Support parsing "<ordinal> of this month" (#109)

data/README.md

@@ -1,60 +1,47 @@
 Chronic
 =======
 
-## DESCRIPTION
-
 Chronic is a natural language date/time parser written in pure Ruby. See below
 for the wide variety of formats Chronic will parse.
 
+## Installation
 
-## INSTALLATION
-
-### RubyGems
-
-    $ [sudo] gem install chronic
-
-### GitHub
+```
+$ gem install chronic
+```
 
-    $ git clone git://github.com/mojombo/chronic.git
-    $ cd chronic && gem build chronic.gemspec
-    $ gem install chronic-<version>.gem
+## Usage
 
+```ruby
+require 'chronic'
 
-## USAGE
+Time.now   #=> Sun Aug 27 23:18:25 PDT 2006
 
-You can parse strings containing a natural language date using the
-`Chronic.parse` method.
+Chronic.parse('tomorrow')
+  #=> Mon Aug 28 12:00:00 PDT 2006
 
-    require 'chronic'
+Chronic.parse('monday', :context => :past)
+  #=> Mon Aug 21 12:00:00 PDT 2006
 
-    Time.now   #=> Sun Aug 27 23:18:25 PDT 2006
+Chronic.parse('this tuesday 5:00')
+  #=> Tue Aug 29 17:00:00 PDT 2006
 
-    Chronic.parse('tomorrow')
-      #=> Mon Aug 28 12:00:00 PDT 2006
+Chronic.parse('this tuesday 5:00', :ambiguous_time_range => :none)
+  #=> Tue Aug 29 05:00:00 PDT 2006
 
-    Chronic.parse('monday', :context => :past)
-      #=> Mon Aug 21 12:00:00 PDT 2006
+Chronic.parse('may 27th', :now => Time.local(2000, 1, 1))
+  #=> Sat May 27 12:00:00 PDT 2000
 
-    Chronic.parse('this tuesday 5:00')
-      #=> Tue Aug 29 17:00:00 PDT 2006
+Chronic.parse('may 27th', :guess => false)
+  #=> Sun May 27 00:00:00 PDT 2007..Mon May 28 00:00:00 PDT 2007
 
-    Chronic.parse('this tuesday 5:00', :ambiguous_time_range => :none)
-      #=> Tue Aug 29 05:00:00 PDT 2006
-
-    Chronic.parse('may 27th', :now => Time.local(2000, 1, 1))
-      #=> Sat May 27 12:00:00 PDT 2000
-
-    Chronic.parse('may 27th', :guess => false)
-      #=> Sun May 27 00:00:00 PDT 2007..Mon May 28 00:00:00 PDT 2007
-      
-    Chronic.parse('6/4/2012', :endian_precedence => :little)
-      #=> Fri Apr 06 00:00:00 PDT 2012
-      
+Chronic.parse('6/4/2012', :endian_precedence => :little)
+  #=> Fri Apr 06 00:00:00 PDT 2012
+```
 
 See `Chronic.parse` for detailed usage instructions.
 
-
-## EXAMPLES
+## Examples
 
 Chronic can parse a huge variety of date and time formats. Following is a
 small sample of strings that will be properly parsed. Parsing is case
@@ -68,12 +55,17 @@ Simple
 * friday 13:00
 * mon 2:35
 * 4pm
+* 10 to 8
+* 10 past 2
+* half past 2
 * 6 in the morning
 * friday 1pm
 * sat 7 in the evening
 * yesterday
 * today
 * tomorrow
+* last week
+* next week
 * this tuesday
 * next month
 * last winter
@@ -139,7 +131,7 @@ Specific Times (many of the above with an added time)
 * etc
 
 
-## TIME ZONES
+## Time Zones
 
 Chronic allows you to set which Time class to use when constructing times. By
 default, the built in Ruby time class creates times in your system's local
@@ -147,13 +139,14 @@ time zone. You can set this to something like ActiveSupport's
 [TimeZone](http://api.rubyonrails.org/classes/ActiveSupport/TimeZone.html)
 class to get full time zone support.
 
-    >> Time.zone = "UTC"
-    >> Chronic.time_class = Time.zone
-    >> Chronic.parse("June 15 2006 at 5:45 AM")
-    => Thu, 15 Jun 2006 05:45:00 UTC +00:00
-
+```
+>> Time.zone = "UTC"
+>> Chronic.time_class = Time.zone
+>> Chronic.parse("June 15 2006 at 5:45 AM")
+=> Thu, 15 Jun 2006 05:45:00 UTC +00:00
+```
 
-## LIMITATIONS
+## Limitations
 
 Chronic uses Ruby's built in Time class for all time storage and computation.
 Because of this, only times that the Time class can handle will be properly
@@ -161,7 +154,7 @@ parsed. Parsing for times outside of this range will simply return nil.
 Support for a wider range of times is planned for a future release.
 
 
-## CONTRIBUTE
+## Contribute
 
 If you'd like to hack on Chronic, start by forking the repo on GitHub:
 

data/lib/chronic.rb

@@ -1,6 +1,42 @@
 require 'time'
 require 'date'
 
+require 'chronic/parser'
+
+require 'chronic/handler'
+require 'chronic/handlers'
+require 'chronic/mini_date'
+require 'chronic/tag'
+require 'chronic/span'
+require 'chronic/token'
+require 'chronic/grabber'
+require 'chronic/pointer'
+require 'chronic/scalar'
+require 'chronic/ordinal'
+require 'chronic/ordinal'
+require 'chronic/separator'
+require 'chronic/time_zone'
+require 'chronic/numerizer'
+require 'chronic/season'
+
+require 'chronic/repeater'
+require 'chronic/repeaters/repeater_year'
+require 'chronic/repeaters/repeater_season'
+require 'chronic/repeaters/repeater_season_name'
+require 'chronic/repeaters/repeater_month'
+require 'chronic/repeaters/repeater_month_name'
+require 'chronic/repeaters/repeater_fortnight'
+require 'chronic/repeaters/repeater_week'
+require 'chronic/repeaters/repeater_weekend'
+require 'chronic/repeaters/repeater_weekday'
+require 'chronic/repeaters/repeater_day'
+require 'chronic/repeaters/repeater_day_name'
+require 'chronic/repeaters/repeater_day_portion'
+require 'chronic/repeaters/repeater_hour'
+require 'chronic/repeaters/repeater_minute'
+require 'chronic/repeaters/repeater_second'
+require 'chronic/repeaters/repeater_time'
+
 # Parse natural language dates and times into Time or Chronic::Span objects.
 #
 # Examples:
@@ -14,20 +50,8 @@ require 'date'
 #
 #   Chronic.parse('monday', :context => :past)
 #     #=> Mon Aug 21 12:00:00 PDT 2006
-#
-#   Chronic.parse('this tuesday 5:00')
-#     #=> Tue Aug 29 17:00:00 PDT 2006
-#
-#   Chronic.parse('this tuesday 5:00', :ambiguous_time_range => :none)
-#     #=> Tue Aug 29 05:00:00 PDT 2006
-#
-#   Chronic.parse('may 27th', :now => Time.local(2000, 1, 1))
-#     #=> Sat May 27 12:00:00 PDT 2000
-#
-#   Chronic.parse('may 27th', :guess => false)
-#     #=> Sun May 27 00:00:00 PDT 2007..Mon May 28 00:00:00 PDT 2007
 module Chronic
-  VERSION = "0.8.0"
+  VERSION = "0.9.0"
 
   class << self
 
@@ -46,72 +70,76 @@ module Chronic
     #
     # Returns The Time class Chronic uses internally.
     attr_accessor :time_class
-
-    # The current Time Chronic is using to base from.
-    #
-    # Examples:
-    #
-    #   Time.now #=> 2011-06-06 14:13:43 +0100
-    #   Chronic.parse('yesterday') #=> 2011-06-05 12:00:00 +0100
-    #
-    #   now = Time.local(2025, 12, 24)
-    #   Chronic.parse('tomorrow', :now => now) #=> 2025-12-25 12:00:00 +0000
-    #
-    # Returns a Time object.
-    attr_accessor :now
   end
 
   self.debug = false
   self.time_class = Time
 
-  autoload :Handler, 'chronic/handler'
-  autoload :Handlers, 'chronic/handlers'
-  autoload :MiniDate, 'chronic/mini_date'
-  autoload :Tag, 'chronic/tag'
-  autoload :Span, 'chronic/span'
-  autoload :Token, 'chronic/token'
-  autoload :Grabber, 'chronic/grabber'
-  autoload :Pointer, 'chronic/pointer'
-  autoload :Scalar, 'chronic/scalar'
-  autoload :Ordinal, 'chronic/ordinal'
-  autoload :OrdinalDay, 'chronic/ordinal'
-  autoload :Separator, 'chronic/separator'
-  autoload :TimeZone, 'chronic/time_zone'
-  autoload :Numerizer, 'chronic/numerizer'
-  autoload :Season, 'chronic/season'
-
-  autoload :Repeater, 'chronic/repeater'
-  autoload :RepeaterYear, 'chronic/repeaters/repeater_year'
-  autoload :RepeaterSeason, 'chronic/repeaters/repeater_season'
-  autoload :RepeaterSeasonName, 'chronic/repeaters/repeater_season_name'
-  autoload :RepeaterMonth, 'chronic/repeaters/repeater_month'
-  autoload :RepeaterMonthName, 'chronic/repeaters/repeater_month_name'
-  autoload :RepeaterFortnight, 'chronic/repeaters/repeater_fortnight'
-  autoload :RepeaterWeek, 'chronic/repeaters/repeater_week'
-  autoload :RepeaterWeekend, 'chronic/repeaters/repeater_weekend'
-  autoload :RepeaterWeekday, 'chronic/repeaters/repeater_weekday'
-  autoload :RepeaterDay, 'chronic/repeaters/repeater_day'
-  autoload :RepeaterDayName, 'chronic/repeaters/repeater_day_name'
-  autoload :RepeaterDayPortion, 'chronic/repeaters/repeater_day_portion'
-  autoload :RepeaterHour, 'chronic/repeaters/repeater_hour'
-  autoload :RepeaterMinute, 'chronic/repeaters/repeater_minute'
-  autoload :RepeaterSecond, 'chronic/repeaters/repeater_second'
-  autoload :RepeaterTime, 'chronic/repeaters/repeater_time'
 
-end
+  # Parses a string containing a natural language date or time.
+  #
+  # If the parser can find a date or time, either a Time or Chronic::Span
+  # will be returned (depending on the value of `:guess`). If no
+  # date or time can be found, `nil` will be returned.
+  #
+  # text - The String text to parse.
+  # opts - An optional Hash of configuration options passed to Parser::new.
+  def self.parse(text, options = {})
+    Parser.new(options).parse(text)
+  end
 
-require 'chronic/chronic'
+  # Construct a new time object determining possible month overflows
+  # and leap years.
+  #
+  # year   - Integer year.
+  # month  - Integer month.
+  # day    - Integer day.
+  # hour   - Integer hour.
+  # minute - Integer minute.
+  # second - Integer second.
+  #
+  # Returns a new Time object constructed from these params.
+  def self.construct(year, month = 1, day = 1, hour = 0, minute = 0, second = 0)
+    if second >= 60
+      minute += second / 60
+      second = second % 60
+    end
 
-class Time
+    if minute >= 60
+      hour += minute / 60
+      minute = minute % 60
+    end
 
-  def self.construct(year, month = 1, day = 1, hour = 0, minute = 0, second = 0)
-    warn "Time.construct will be deprecated in version 0.7.0. Please use Chronic.construct instead"
-    Chronic.construct(year, month, day, hour, minute, second)
-  end
+    if hour >= 24
+      day += hour / 24
+      hour = hour % 24
+    end
+
+    # determine if there is a day overflow. this is complicated by our crappy calendar
+    # system (non-constant number of days per month)
+    day <= 56 || raise("day must be no more than 56 (makes month resolution easier)")
+    if day > 28
+      # no month ever has fewer than 28 days, so only do this if necessary
+      leap_year_month_days = [31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]
+      common_year_month_days = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]
+      days_this_month = Date.leap?(year) ? leap_year_month_days[month - 1] : common_year_month_days[month - 1]
+      if day > days_this_month
+        month += day / days_this_month
+        day = day % days_this_month
+      end
+    end
+
+    if month > 12
+      if month % 12 == 0
+        year += (month - 12) / 12
+        month = 12
+      else
+        year += month / 12
+        month = month % 12
+      end
+    end
 
-  def to_minidate
-    warn "Time.to_minidate will be deprecated in version 0.7.0. Please use Chronic::MiniDate.from_time(time) instead"
-    Chronic::MiniDate.from_time(self)
+    Chronic.time_class.local(year, month, day, hour, minute, second)
   end
 
 end

data/lib/chronic/handler.rb

@@ -6,8 +6,8 @@ module Chronic
     attr_reader :handler_method
 
     # pattern        - An Array of patterns to match tokens against.
-    # handler_method - A Symbole representing the method to be invoked
-    #   when patterns are matched.
+    # handler_method - A Symbol representing the method to be invoked
+    #   when a pattern matches.
     def initialize(pattern, handler_method)
       @pattern = pattern
       @handler_method = handler_method
@@ -43,14 +43,14 @@ module Chronic
           if definitions.key?(name.to_sym)
             sub_handlers = definitions[name.to_sym]
           else
-            raise ChronicPain, "Invalid subset #{name} specified"
+            raise "Invalid subset #{name} specified"
           end
 
           sub_handlers.each do |sub_handler|
             return true if sub_handler.match(tokens[token_index..tokens.size], definitions)
           end
         else
-          raise ChronicPain, "Invalid match type: #{element.class}"
+          raise "Invalid match type: #{element.class}"
         end
       end
 
@@ -58,13 +58,13 @@ module Chronic
       return true
     end
 
-    def invoke(type, tokens, options)
+    def invoke(type, tokens, parser, options)
       if Chronic.debug
         puts "-#{type}"
         puts "Handler: #{@handler_method}"
       end
 
-      Handlers.send(@handler_method, tokens, options)
+      parser.send(@handler_method, tokens, options)
     end
 
     # other - The other Handler object to compare.
@@ -85,4 +85,4 @@ module Chronic
     end
 
   end
-end
+end

data/lib/chronic/handlers.rb

@@ -4,7 +4,7 @@ module Chronic
 
     # Handle month/day
     def handle_m_d(month, day, time_tokens, options)
-      month.start = Chronic.now
+      month.start = self.now
       span = month.this(options[:context])
       year, month = span.begin.year, span.begin.month
       day_start = Chronic.time_class.local(year, month, day)
@@ -17,7 +17,7 @@ module Chronic
       month = tokens[0].get_tag(RepeaterMonthName)
       day = tokens[1].get_tag(ScalarDay).type
 
-      return if month_overflow?(Chronic.now.year, month.index, day)
+      return if month_overflow?(self.now.year, month.index, day)
 
       handle_m_d(month, day, tokens[2..tokens.size], options)
     end
@@ -34,7 +34,7 @@ module Chronic
         token_range = 0..0
       end
 
-      return if month_overflow?(Chronic.now.year, month.index, day)
+      return if month_overflow?(self.now.year, month.index, day)
 
       handle_m_d(month, day, tokens[token_range], options)
     end
@@ -44,7 +44,7 @@ module Chronic
       month = tokens[0].get_tag(RepeaterMonthName)
       day = tokens[1].get_tag(OrdinalDay).type
 
-      return if month_overflow?(Chronic.now.year, month.index, day)
+      return if month_overflow?(self.now.year, month.index, day)
 
       handle_m_d(month, day, tokens[2..tokens.size], options)
     end
@@ -61,7 +61,7 @@ module Chronic
       month = tokens[1].get_tag(RepeaterMonthName)
       day = tokens[0].get_tag(OrdinalDay).type
 
-      return if month_overflow?(Chronic.now.year, month.index, day)
+      return if month_overflow?(self.now.year, month.index, day)
 
       handle_m_d(month, day, tokens[2..tokens.size], options)
     end
@@ -87,7 +87,7 @@ module Chronic
       month = tokens[1].get_tag(RepeaterMonthName)
       day = tokens[0].get_tag(ScalarDay).type
 
-      return if month_overflow?(Chronic.now.year, month.index, day)
+      return if month_overflow?(self.now.year, month.index, day)
 
       handle_m_d(month, day, tokens[2..tokens.size], options)
     end
@@ -104,7 +104,7 @@ module Chronic
         token_range = 0..0
       end
 
-      return if month_overflow?(Chronic.now.year, month.index, day)
+      return if month_overflow?(self.now.year, month.index, day)
 
       handle_m_d(month, day, tokens[token_range], options)
     end
@@ -229,13 +229,14 @@ module Chronic
     def handle_sm_sd(tokens, options)
       month = tokens[0].get_tag(ScalarMonth).type
       day = tokens[1].get_tag(ScalarDay).type
-      year = Chronic.now.year
+      year = self.now.year
       time_tokens = tokens.last(tokens.size - 2)
 
       return if month_overflow?(year, month, day)
 
       begin
         day_start = Chronic.time_class.local(year, month, day)
+        day_start = Chronic.time_class.local(year + 1, month, day) if options[:context] == :future && day_start < now
         day_or_time(day_start, time_tokens, options)
       rescue ArgumentError
         nil
@@ -274,14 +275,46 @@ module Chronic
     def handle_rdn_rmn_od(tokens, options)
       month = tokens[1].get_tag(RepeaterMonthName)
       day = tokens[2].get_tag(OrdinalDay).type
-      year = Chronic.now.year
+      time_tokens = tokens.last(tokens.size - 3)
+      year = self.now.year
 
       return if month_overflow?(year, month.index, day)
 
       begin
-        start_time = Chronic.time_class.local(year, month.index, day)
-        end_time = time_with_rollover(year, month.index, day + 1)
-        Span.new(start_time, end_time)
+        if time_tokens.empty?
+          start_time = Chronic.time_class.local(year, month.index, day)
+          end_time = time_with_rollover(year, month.index, day + 1)
+          Span.new(start_time, end_time)
+        else
+          day_start = Chronic.time_class.local(year, month.index, day)
+          day_or_time(day_start, time_tokens, options)
+        end
+      rescue ArgumentError
+        nil
+      end
+    end
+
+    # Handle RepeaterDayName OrdinalDay
+    def handle_rdn_od(tokens, options)
+      day = tokens[1].get_tag(OrdinalDay).type
+      time_tokens = tokens.last(tokens.size - 2)
+      year = self.now.year
+      month = self.now.month
+      if options[:context] == :future
+        self.now.day > day ? month += 1 : month
+      end
+
+      return if month_overflow?(year, month, day)
+
+      begin
+        if time_tokens.empty?
+          start_time = Chronic.time_class.local(year, month, day)
+          end_time = time_with_rollover(year, month, day + 1)
+          Span.new(start_time, end_time)
+        else
+          day_start = Chronic.time_class.local(year, month, day)
+          day_or_time(day_start, time_tokens, options)
+        end
       rescue ArgumentError
         nil
       end
@@ -291,14 +324,20 @@ module Chronic
     def handle_rdn_rmn_sd(tokens, options)
       month = tokens[1].get_tag(RepeaterMonthName)
       day = tokens[2].get_tag(ScalarDay).type
-      year = Chronic.now.year
+      time_tokens = tokens.last(tokens.size - 3)
+      year = self.now.year
 
       return if month_overflow?(year, month.index, day)
 
       begin
-        start_time = Chronic.time_class.local(year, month.index, day)
-        end_time = time_with_rollover(year, month.index, day + 1)
-        Span.new(start_time, end_time)
+        if time_tokens.empty?
+          start_time = Chronic.time_class.local(year, month.index, day)
+          end_time = time_with_rollover(year, month.index, day + 1)
+          Span.new(start_time, end_time)
+        else
+          day_start = Chronic.time_class.local(year, month.index, day)
+          day_or_time(day_start, time_tokens, options)
+        end
       rescue ArgumentError
         nil
       end
@@ -332,7 +371,8 @@ module Chronic
         end_time = Chronic.time_class.local(year, month, day + 1, h, m, s)
       else
         time = Chronic.time_class.local(year, month, day)
-        end_time = Chronic.time_class.local(year, month, day + 1)
+        day += 1 unless day >= 31
+        end_time = Chronic.time_class.local(year, month, day)
       end
       Span.new(time, end_time)
     end
@@ -365,7 +405,7 @@ module Chronic
     # Handle scalar/repeater/pointer
     def handle_s_r_p(tokens, options)
       repeater = tokens[1].get_tag(Repeater)
-      span = Span.new(Chronic.now, Chronic.now + 1)
+      span = Span.new(self.now, self.now + 1)
 
       handle_srp(tokens, span, options)
     end
@@ -382,6 +422,13 @@ module Chronic
       handle_srp(tokens, anchor_span, options)
     end
 
+    def handle_s_r_a_s_r_p_a(tokens, options)
+      anchor_span = get_anchor(tokens[4..tokens.size - 1], options)
+
+      span = handle_srp(tokens[0..1]+tokens[4..6], anchor_span, options)
+      handle_srp(tokens[2..3]+tokens[4..6], span, options)
+    end
+
     # narrows
 
     # Handle oridinal repeaters
@@ -421,7 +468,7 @@ module Chronic
       outer_span = Span.new(day_start, day_start + (24 * 60 * 60))
 
       if !time_tokens.empty?
-        Chronic.now = outer_span.begin
+        self.now = outer_span.begin
         get_anchor(dealias_and_disambiguate_times(time_tokens, options), options)
       else
         outer_span
@@ -439,7 +486,7 @@ module Chronic
       end
 
       head = repeaters.shift
-      head.start = Chronic.now
+      head.start = self.now
 
       case grabber.type
       when :last
@@ -453,7 +500,7 @@ module Chronic
       when :next
         outer_span = head.next(:future)
       else
-        raise ChronicPain, "Invalid grabber"
+        raise "Invalid grabber"
       end
 
       if Chronic.debug