chronic 0.4.1 → 0.6.0

data/lib/chronic/repeaters/repeater_season_name.rb

@@ -9,14 +9,12 @@ module Chronic
     end
 
     def this(pointer = :future)
-      # super
-
       direction = pointer == :future ? 1 : -1
 
-      today = Time.construct(@now.year, @now.month, @now.day)
+      today = Chronic.construct(@now.year, @now.month, @now.day)
       goal_ssn_start = today + direction * num_seconds_til_start(@type, direction)
       goal_ssn_end = today + direction * num_seconds_til_end(@type, direction)
-      curr_ssn = find_current_season(@now.to_minidate)
+      curr_ssn = find_current_season(MiniDate.from_time(@now))
       case pointer
       when :past
         this_ssn_start = goal_ssn_start

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)
@@ -22,7 +21,7 @@ module Chronic
       direction = pointer == :future ? 1 : -1
 
       if !@current_weekday_start
-        @current_weekday_start = Time.construct(@now.year, @now.month, @now.day)
+        @current_weekday_start = Chronic.construct(@now.year, @now.month, @now.day)
         @current_weekday_start += direction * DAY_SECONDS
 
         until is_weekday?(@current_weekday_start.wday)

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)
@@ -13,16 +12,16 @@ module Chronic
       if !@current_year_start
         case pointer
         when :future
-          @current_year_start = Time.construct(@now.year + 1)
+          @current_year_start = Chronic.construct(@now.year + 1)
         when :past
-          @current_year_start = Time.construct(@now.year - 1)
+          @current_year_start = Chronic.construct(@now.year - 1)
         end
       else
         diff = pointer == :future ? 1 : -1
-        @current_year_start = Time.construct(@current_year_start.year + diff)
+        @current_year_start = Chronic.construct(@current_year_start.year + diff)
       end
 
-      Span.new(@current_year_start, Time.construct(@current_year_start.year + 1))
+      Span.new(@current_year_start, Chronic.construct(@current_year_start.year + 1))
     end
 
     def this(pointer = :future)
@@ -30,14 +29,14 @@ module Chronic
 
       case pointer
       when :future
-        this_year_start = Time.construct(@now.year, @now.month, @now.day) + RepeaterDay::DAY_SECONDS
-        this_year_end = Time.construct(@now.year + 1, 1, 1)
+        this_year_start = Chronic.construct(@now.year, @now.month, @now.day) + RepeaterDay::DAY_SECONDS
+        this_year_end = Chronic.construct(@now.year + 1, 1, 1)
       when :past
-        this_year_start = Time.construct(@now.year, 1, 1)
-        this_year_end = Time.construct(@now.year, @now.month, @now.day)
+        this_year_start = Chronic.construct(@now.year, 1, 1)
+        this_year_end = Chronic.construct(@now.year, @now.month, @now.day)
       when :none
-        this_year_start = Time.construct(@now.year, 1, 1)
-        this_year_end = Time.construct(@now.year + 1, 1, 1)
+        this_year_start = Chronic.construct(@now.year, 1, 1)
+        this_year_end = Chronic.construct(@now.year + 1, 1, 1)
       end
 
       Span.new(this_year_start, this_year_end)
@@ -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
+      Chronic.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, :summer, :autumn, :winter]
+      next_season_num = (lookup.index(season) + 1 * pointer) % 4
+      lookup[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
@@ -26,6 +35,8 @@ module Chronic
         end
         nil
       end
+
     end
+
   end
 end

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,84 @@
-#=============================================================================
+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.6.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/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/separator'
+require 'chronic/time_zone'
+require 'chronic/numerizer'
+require 'chronic/season'
 
 require 'chronic/repeater'
 require 'chronic/repeaters/repeater_year'
@@ -47,88 +98,14 @@ 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
-      minute += second / 60
-      second = second % 60
-    end
-
-    if minute >= 60
-      hour += minute / 60
-      minute = minute % 60
-    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 = (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]
-      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
-
-    Chronic.time_class.local(year, month, day, hour, minute, second)
+    warn "Chronic.construct will be deprecated in version 0.7.0. Please use Chronic.construct instead"
+    Chronic.construct(year, month, day, hour, minute, second)
   end
 
   def to_minidate
-    Chronic::MiniDate.new(self.month, self.day)
+    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)
   end
 end