chronic 0.4.1 → 0.5.0

data/lib/chronic/repeaters/repeater_minute.rb

@@ -4,7 +4,6 @@ module Chronic
 
     def initialize(type)
       super
-      @current_minute_start = nil
     end
 
     def next(pointer = :future)

data/lib/chronic/repeaters/repeater_month.rb

@@ -2,10 +2,11 @@ module Chronic
   class RepeaterMonth < Repeater #:nodoc:
     MONTH_SECONDS = 2_592_000 # 30 * 24 * 60 * 60
     YEAR_MONTHS = 12
+    MONTH_DAYS = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]
+    MONTH_DAYS_LEAP = [31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]
 
     def initialize(type)
       super
-      @current_month_start = nil
     end
 
     def next(pointer)
@@ -54,7 +55,11 @@ module Chronic
         new_year += 1
         new_month -= YEAR_MONTHS
       end
-      Time.construct(new_year, new_month, time.day, time.hour, time.min, time.sec)
+
+      days = month_days(new_year, new_month)
+      new_day = time.day > days ? days : time.day
+
+      Time.construct(new_year, new_month, new_day, time.hour, time.min, time.sec)
     end
 
     def width
@@ -64,5 +69,11 @@ module Chronic
     def to_s
       super << '-month'
     end
+
+    private
+
+    def month_days(year, month)
+      Date.leap?(year) ? MONTH_DAYS_LEAP[month - 1] : MONTH_DAYS[month - 1]
+    end
   end
 end

data/lib/chronic/repeaters/repeater_month_name.rb

@@ -18,32 +18,30 @@ module Chronic
 
     def initialize(type)
       super
-      @current_month_begin = nil
     end
 
     def next(pointer)
       super
 
       if !@current_month_begin
-        target_month = symbol_to_number(@type)
         case pointer
         when :future
-          if @now.month < target_month
-            @current_month_begin = Time.construct(@now.year, target_month)
-          elsif @now.month > target_month
-            @current_month_begin = Time.construct(@now.year + 1, target_month)
+          if @now.month < index
+            @current_month_begin = Time.construct(@now.year, index)
+          elsif @now.month > index
+            @current_month_begin = Time.construct(@now.year + 1, index)
           end
         when :none
-          if @now.month <= target_month
-            @current_month_begin = Time.construct(@now.year, target_month)
-          elsif @now.month > target_month
-            @current_month_begin = Time.construct(@now.year + 1, target_month)
+          if @now.month <= index
+            @current_month_begin = Time.construct(@now.year, index)
+          elsif @now.month > index
+            @current_month_begin = Time.construct(@now.year + 1, index)
           end
         when :past
-          if @now.month >= target_month
-            @current_month_begin = Time.construct(@now.year, target_month)
-          elsif @now.month < target_month
-            @current_month_begin = Time.construct(@now.year - 1, target_month)
+          if @now.month >= index
+            @current_month_begin = Time.construct(@now.year, index)
+          elsif @now.month < index
+            @current_month_begin = Time.construct(@now.year - 1, index)
           end
         end
         @current_month_begin || raise("Current month should be set by now")
@@ -86,17 +84,11 @@ module Chronic
     end
 
     def index
-      symbol_to_number(@type)
+      @index ||= MONTHS[@type]
     end
 
     def to_s
       super << '-monthname-' << @type.to_s
     end
-
-    private
-
-    def symbol_to_number(sym)
-      MONTHS[sym] || raise("Invalid symbol specified")
-    end
   end
 end

data/lib/chronic/repeaters/repeater_season.rb

@@ -1,22 +1,4 @@
 module Chronic
-  class Season
-    attr_reader :start, :end
-
-    def initialize(myStart, myEnd)
-      @start = myStart
-      @end = myEnd
-    end
-
-    def self.find_next_season(season, pointer)
-      lookup = {:spring => 0, :summer => 1, :autumn => 2, :winter => 3}
-      next_season_num = (lookup[season]+1*pointer) % 4
-      lookup.invert[next_season_num]
-    end
-
-    def self.season_after(season); find_next_season(season, +1); end
-    def self.season_before(season); find_next_season(season, -1); end
-  end
-
   class RepeaterSeason < Repeater #:nodoc:
     SEASON_SECONDS = 7_862_400 # 91 * 24 * 60 * 60
     SEASONS = {
@@ -28,7 +10,6 @@ module Chronic
 
     def initialize(type)
       super
-      @next_season_start = nil
     end
 
     def next(pointer)

data/lib/chronic/repeaters/repeater_season_name.rb

@@ -9,8 +9,6 @@ module Chronic
     end
 
     def this(pointer = :future)
-      # super
-
       direction = pointer == :future ? 1 : -1
 
       today = Time.construct(@now.year, @now.month, @now.day)

data/lib/chronic/repeaters/repeater_second.rb

@@ -4,7 +4,6 @@ module Chronic
 
     def initialize(type)
       super
-      @second_start = nil
     end
 
     def next(pointer = :future)

data/lib/chronic/repeaters/repeater_time.rb

@@ -27,7 +27,6 @@ module Chronic
     end
 
     def initialize(time)
-      @current_time = nil
       t = time.gsub(/\:/, '')
 
       @type =
@@ -37,7 +36,7 @@ module Chronic
           hours == 12 ? Tick.new(0 * 60 * 60, true) : Tick.new(hours * 60 * 60, true)
         when 3
           hours = t[0..0].to_i
-          ambiguous = hours > 1
+          ambiguous = hours > 0
           Tick.new((hours * 60 * 60) + (t[1..2].to_i * 60), ambiguous)
         when 4
           ambiguous = time =~ /:/ && t[0..0].to_i != 0 && t[0..1].to_i <= 12

data/lib/chronic/repeaters/repeater_week.rb

@@ -4,7 +4,6 @@ module Chronic
 
     def initialize(type)
       super
-      @current_week_start = nil
     end
 
     def next(pointer)

data/lib/chronic/repeaters/repeater_weekday.rb

@@ -13,7 +13,6 @@ module Chronic
 
     def initialize(type)
       super
-      @current_weekday_start = nil
     end
 
     def next(pointer)

data/lib/chronic/repeaters/repeater_weekend.rb

@@ -4,7 +4,6 @@ module Chronic
 
     def initialize(type)
       super
-      @current_week_start = nil
     end
 
     def next(pointer)

data/lib/chronic/repeaters/repeater_year.rb

@@ -4,7 +4,6 @@ module Chronic
 
     def initialize(type)
       super
-      @current_year_start = nil
     end
 
     def next(pointer)
@@ -45,13 +44,8 @@ module Chronic
 
     def offset(span, amount, pointer)
       direction = pointer == :future ? 1 : -1
-
-      sb = span.begin
-      new_begin = Time.construct(sb.year + (amount * direction), sb.month, sb.day, sb.hour, sb.min, sb.sec)
-
-      se = span.end
-      new_end = Time.construct(se.year + (amount * direction), se.month, se.day, se.hour, se.min, se.sec)
-
+      new_begin = build_offset_time(span.begin, amount, direction)
+      new_end   = build_offset_time(span.end, amount, direction)
       Span.new(new_begin, new_end)
     end
 
@@ -62,5 +56,22 @@ module Chronic
     def to_s
       super << '-year'
     end
+
+    private
+
+    def build_offset_time(time, amount, direction)
+      year = time.year + (amount * direction)
+      days = month_days(year, time.month)
+      day = time.day > days ? days : time.day
+      Time.construct(year, time.month, day, time.hour, time.min, time.sec)
+    end
+
+    def month_days(year, month)
+      if Date.leap?(year)
+        RepeaterMonth::MONTH_DAYS_LEAP[month - 1]
+      else
+        RepeaterMonth::MONTH_DAYS[month - 1]
+      end
+    end
   end
 end

data/lib/chronic/scalar.rb

@@ -1,7 +1,13 @@
 module Chronic
-  class Scalar < Tag #:nodoc:
+  class Scalar < Tag
     DAY_PORTIONS = %w( am pm morning afternoon evening night )
 
+    # Scan an Array of {Token}s and apply any necessary Scalar tags to
+    # each token
+    #
+    # @param [Array<Token>] tokens Array of tokens to scan
+    # @param [Hash] options Options specified in {Chronic.parse}
+    # @return [Array] list of tokens
     def self.scan(tokens, options)
       tokens.each_index do |i|
         if t = scan_for_scalars(tokens[i], tokens[i + 1]) then tokens[i].tag(t) end
@@ -11,6 +17,9 @@ module Chronic
       end
     end
 
+    # @param [Token] token
+    # @param [Token] post_token
+    # @return [Scalar, nil]
     def self.scan_for_scalars(token, post_token)
       if token.word =~ /^\d*$/
         unless post_token && DAY_PORTIONS.include?(post_token.word)
@@ -19,6 +28,9 @@ module Chronic
       end
     end
 
+    # @param [Token] token
+    # @param [Token] post_token
+    # @return [ScalarDay, nil]
     def self.scan_for_days(token, post_token)
       if token.word =~ /^\d\d?$/
         toi = token.word.to_i
@@ -28,6 +40,9 @@ module Chronic
       end
     end
 
+    # @param [Token] token
+    # @param [Token] post_token
+    # @return [ScalarMonth, nil]
     def self.scan_for_months(token, post_token)
       if token.word =~ /^\d\d?$/
         toi = token.word.to_i
@@ -37,6 +52,10 @@ module Chronic
       end
     end
 
+    # @param [Token] token
+    # @param [Token] post_token
+    # @param [Hash] options Options specified in {Chronic.parse}
+    # @return [ScalarYear, nil]
     def self.scan_for_years(token, post_token, options)
       if token.word =~ /^([1-9]\d)?\d\d?$/
         unless post_token && DAY_PORTIONS.include?(post_token.word)
@@ -47,6 +66,15 @@ module Chronic
     end
 
     # Build a year from a 2 digit suffix
+    #
+    # @example
+    #   make_year(96, 50) #=> 1996
+    #   make_year(79, 20) #=> 2079
+    #   make_year(00, 50) #=> 2000
+    #
+    # @param [Integer] year The two digit year to build from
+    # @param [Integer] bias The amount of future years to bias
+    # @return [Integer] The 4 digit year
     def self.make_year(year, bias)
       return year if year.to_s.size > 2
       start_year = Chronic.time_class.now.year - bias

data/lib/chronic/season.rb

@@ -0,0 +1,37 @@
+module Chronic
+  class Season
+    # @return [MiniDate]
+    attr_reader :start
+
+    # @return [MiniDate]
+    attr_reader :end
+
+    # @param [MiniDate] start_date
+    # @param [MiniDate] end_date
+    def initialize(start_date, end_date)
+      @start = start_date
+      @end = end_date
+    end
+
+    # @param [Symbol]  season  The season name
+    # @param [Integer] pointer The direction (-1 for past, 1 for future)
+    # @return [Symbol] The new season name
+    def self.find_next_season(season, pointer)
+      lookup = {:spring => 0, :summer => 1, :autumn => 2, :winter => 3}
+      next_season_num = (lookup[season] + 1 * pointer) % 4
+      lookup.invert[next_season_num]
+    end
+
+    # @param [Symbol] season The season name
+    # @return [Symbol] The new season name
+    def self.season_after(season)
+      find_next_season(season, +1)
+    end
+
+    # @param [Symbol] season The season name
+    # @return [Symbol] The new season name
+    def self.season_before(season)
+      find_next_season(season, -1)
+    end
+  end
+end

data/lib/chronic/separator.rb

@@ -1,19 +1,30 @@
 module Chronic
-  class Separator < Tag #:nodoc:
+  class Separator < Tag
+
+    # Scan an Array of {Token}s and apply any necessary Separator tags to
+    # each token
+    #
+    # @param [Array<Token>] tokens Array of tokens to scan
+    # @param [Hash] options Options specified in {Chronic.parse}
+    # @return [Array] list of tokens
     def self.scan(tokens, options)
-      tokens.each_index do |i|
-        if t = scan_for_commas(tokens[i]) then tokens[i].tag(t); next end
-        if t = scan_for_slash_or_dash(tokens[i]) then tokens[i].tag(t); next end
-        if t = scan_for_at(tokens[i]) then tokens[i].tag(t); next end
-        if t = scan_for_in(tokens[i]) then tokens[i].tag(t); next end
-        if t = scan_for_on(tokens[i]) then tokens[i].tag(t); next end
+      tokens.each do |token|
+        if t = scan_for_commas(token) then token.tag(t); next end
+        if t = scan_for_slash_or_dash(token) then token.tag(t); next end
+        if t = scan_for_at(token) then token.tag(t); next end
+        if t = scan_for_in(token) then token.tag(t); next end
+        if t = scan_for_on(token) then token.tag(t); next end
       end
     end
 
+    # @param [Token] token
+    # @return [SeparatorComma, nil]
     def self.scan_for_commas(token)
       scan_for token, SeparatorComma, { /^,$/ => :comma }
     end
 
+    # @param [Token] token
+    # @return [SeparatorSlashOrDash, nil]
     def self.scan_for_slash_or_dash(token)
       scan_for token, SeparatorSlashOrDash,
       {
@@ -22,14 +33,20 @@ module Chronic
       }
     end
 
+    # @param [Token] token
+    # @return [SeparatorAt, nil]
     def self.scan_for_at(token)
       scan_for token, SeparatorAt, { /^(at|@)$/ => :at }
     end
 
+    # @param [Token] token
+    # @return [SeparatorIn, nil]
     def self.scan_for_in(token)
       scan_for token, SeparatorIn, { /^in$/ => :in }
     end
 
+    # @param [Token] token
+    # @return [SeparatorOn, nil]
     def self.scan_for_on(token)
       scan_for token, SeparatorOn, { /^on$/ => :on }
     end

data/lib/chronic/tag.rb

@@ -1,13 +1,17 @@
 module Chronic
   # Tokens are tagged with subclassed instances of this class when
   # they match specific criteria
-  class Tag #:nodoc:
+  class Tag
+
+    # @return [Symbol]
     attr_accessor :type
 
+    # @param [Symbol] type
     def initialize(type)
       @type = type
     end
 
+    # @param [Time] s Set the start timestamp for this Tag
     def start=(s)
       @now = s
     end
@@ -15,6 +19,11 @@ module Chronic
     class << self
       private
 
+      # @param [Token] token
+      # @param [Class] klass The class instance to create
+      # @param [Regexp, Hash] items
+      # @return [Object, nil] either a new instance of `klass` or `nil` if
+      #   no match is found
       def scan_for(token, klass, items={})
         case items
         when Regexp

data/lib/chronic/time_zone.rb

@@ -1,11 +1,20 @@
 module Chronic
-  class TimeZone < Tag #:nodoc:
+  class TimeZone < Tag
+
+    # Scan an Array of {Token}s and apply any necessary TimeZone tags to
+    # each token
+    #
+    # @param [Array<Token>] tokens Array of tokens to scan
+    # @param [Hash] options Options specified in {Chronic.parse}
+    # @return [Array] list of tokens
     def self.scan(tokens, options)
-      tokens.each_index do |i|
-        if t = scan_for_all(tokens[i]) then tokens[i].tag(t); next end
+      tokens.each do |token|
+        if t = scan_for_all(token) then token.tag(t); next end
       end
     end
 
+    # @param [Token] token
+    # @return [TimeZone, nil]
     def self.scan_for_all(token)
       scan_for token, self,
       {

data/lib/chronic/token.rb

@@ -1,6 +1,11 @@
 module Chronic
-  class Token #:nodoc:
-    attr_accessor :word, :tags
+  class Token
+
+    # @return [String] The word this Token represents
+    attr_accessor :word
+
+    # @return [Array] A list of tag associated with this Token
+    attr_accessor :tags
 
     def initialize(word)
       @word = word
@@ -8,21 +13,26 @@ module Chronic
     end
 
     # Tag this token with the specified tag
+    #
+    # @param [Tag] new_tag An instance of {Tag} or one of its subclasses
     def tag(new_tag)
       @tags << new_tag
     end
 
     # Remove all tags of the given class
+    #
+    # @param [Class] The tag class to remove
     def untag(tag_class)
       @tags.delete_if { |m| m.kind_of? tag_class }
     end
 
-    # Return true if this token has any tags
+    # @return [Boolean] true if this token has any tags
     def tagged?
       @tags.size > 0
     end
 
-    # Return the Tag that matches the given class
+    # @param [Class] tag_class The tag class to search for
+    # @return [Tag] The first Tag that matches the given class
     def get_tag(tag_class)
       @tags.find { |m| m.kind_of? tag_class }
     end

data/lib/chronic.rb

@@ -1,33 +1,83 @@
-#=============================================================================
+require 'time'
+require 'date'
+
+# Parse natural language dates and times into Time or {Chronic::Span} objects
 #
-#  Name:       Chronic
-#  Author:     Tom Preston-Werner
-#  Purpose:    Parse natural language dates and times into Time or
-#              Chronic::Span objects
+# @example
+#   require 'chronic'
 #
-#=============================================================================
-
+#   Time.now   #=> Sun Aug 27 23:18:25 PDT 2006
+#
+#   Chronic.parse('tomorrow')
+#     #=> Mon Aug 28 12:00:00 PDT 2006
+#
+#   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
+#
+# @author Tom Preston-Werner, Lee Jarvis
 module Chronic
-  VERSION = "0.4.1"
+  VERSION = "0.5.0"
 
   class << self
+
+    # @return [Boolean] true when debug mode is enabled
     attr_accessor :debug
+
+    # @example
+    #   require 'chronic'
+    #   require 'active_support/time'
+    #
+    #   Time.zone = 'UTC'
+    #   Chronic.time_class = Time.zone
+    #   Chronic.parse('June 15 2006 at 5:54 AM')
+    #     # => Thu, 15 Jun 2006 05:45:00 UTC +00:00
+    #
+    # @return [Time] The time class Chronic uses internally
     attr_accessor :time_class
+
+    # The current Time Chronic is using to base from
+    #
+    # @example
+    #   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
+    #
+    # @return [Time, nil]
+    attr_accessor :now
   end
 
   self.debug = false
   self.time_class = Time
 end
 
-require 'time'
-require 'date'
-
 require 'chronic/chronic'
 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/separator'
+require 'chronic/time_zone'
+require 'chronic/numerizer'
+require 'chronic/season'
 
 require 'chronic/repeater'
 require 'chronic/repeaters/repeater_year'
@@ -47,42 +97,6 @@ require 'chronic/repeaters/repeater_minute'
 require 'chronic/repeaters/repeater_second'
 require 'chronic/repeaters/repeater_time'
 
-require 'chronic/grabber'
-require 'chronic/pointer'
-require 'chronic/scalar'
-require 'chronic/ordinal'
-require 'chronic/separator'
-require 'chronic/time_zone'
-
-require 'chronic/numerizer'
-
-# class Time
-#   def self.construct(year, month = 1, day = 1, hour = 0, minute = 0, second = 0)
-#     # extra_seconds = second > 60 ? second - 60 : 0
-#     # extra_minutes = minute > 59 ? minute - 59 : 0
-#     # extra_hours = hour > 23 ? hour - 23 : 0
-#     # extra_days = day >
-#
-#     if month > 12
-#       if month % 12 == 0
-#         year += (month - 12) / 12
-#         month = 12
-#       else
-#         year += month / 12
-#         month = month % 12
-#       end
-#     end
-#
-#     base = Time.local(year, month)
-#     puts base
-#     offset = ((day - 1) * 24 * 60 * 60) + (hour * 60 * 60) + (minute * 60) + second
-#     puts offset.to_s
-#     date = base + offset
-#     puts date
-#     date
-#   end
-# end
-
 class Time
   def self.construct(year, month = 1, day = 1, hour = 0, minute = 0, second = 0)
     if second >= 60
@@ -105,10 +119,9 @@ class Time
     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 = (year % 4 == 0) && !(year % 100 == 0)
       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 = leap_year ? leap_year_month_days[month - 1] : common_year_month_days[month - 1]
+      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