chronic 0.4.1 → 0.4.3

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 A 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,82 @@
-#=============================================================================
+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.4.3"
 
   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/repeater'
 require 'chronic/repeaters/repeater_year'
@@ -47,42 +96,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

data/test/test_Chronic.rb

@@ -21,7 +21,7 @@ class TestChronic < Test::Unit::TestCase
 
     assert_equal :morning, tokens[1].tags[0].type
 
-    tokens = Chronic.dealias_and_disambiguate_times(tokens, {})
+    tokens = Chronic::Handlers.dealias_and_disambiguate_times(tokens, {})
 
     assert_equal :am, tokens[1].tags[0].type
     assert_equal 2, tokens.size
@@ -34,7 +34,7 @@ class TestChronic < Test::Unit::TestCase
 
     assert_equal :morning, tokens[1].tags[0].type
 
-    tokens = Chronic.dealias_and_disambiguate_times(tokens, {})
+    tokens = Chronic::Handlers.dealias_and_disambiguate_times(tokens, {})
 
     assert_equal :morning, tokens[1].tags[0].type
     assert_equal 2, tokens.size
@@ -51,4 +51,54 @@ class TestChronic < Test::Unit::TestCase
     assert_equal Time.local(2006, 11, 16), Chronic.guess(span)
   end
 
+  def test_now
+    Chronic.parse('now', :now => Time.local(2006, 01))
+    assert_equal Time.local(2006, 01), Chronic.now
+
+    Chronic.parse('now', :now => Time.local(2007, 01))
+    assert_equal Time.local(2007, 01), Chronic.now
+  end
+
+  def test_endian_definitions
+    # middle, little
+    endians = [
+      Chronic::Handler.new([:scalar_month, :separator_slash_or_dash, :scalar_day, :separator_slash_or_dash, :scalar_year, :separator_at?, 'time?'], :handle_sm_sd_sy),
+      Chronic::Handler.new([:scalar_day, :separator_slash_or_dash, :scalar_month, :separator_slash_or_dash, :scalar_year, :separator_at?, 'time?'], :handle_sd_sm_sy)
+    ]
+
+    assert_equal endians, Chronic.definitions[:endian]
+
+    defs = Chronic.definitions(:endian_precedence => :little)
+    assert_equal endians.reverse, defs[:endian]
+
+    defs = Chronic.definitions(:endian_precedence => [:little, :middle])
+    assert_equal endians.reverse, defs[:endian]
+
+    assert_raises(Chronic::InvalidArgumentException) do
+      Chronic.definitions(:endian_precedence => :invalid)
+    end
+  end
+
+  def test_passing_options
+    assert_raises(Chronic::InvalidArgumentException) do
+      Chronic.parse('now', :invalid => :option)
+    end
+
+    assert_raises(Chronic::InvalidArgumentException) do
+      Chronic.parse('now', :context => :invalid_context)
+    end
+  end
+
+  def test_debug
+    require 'stringio'
+    $stdout = StringIO.new
+    Chronic.debug = true
+
+    Chronic.parse 'now'
+    assert $stdout.string.include?('this(grabber-this)')
+  ensure
+    $stdout = STDOUT
+    Chronic.debug = false
+  end
+
 end

data/test/test_RepeaterMonth.rb

@@ -23,6 +23,10 @@ class TestRepeaterMonth < Test::Unit::TestCase
 
     time = Chronic::RepeaterMonth.new(:month).offset_by(@now, 10, :past)
     assert_equal Time.local(2005, 10, 16, 14), time
+
+    time = Chronic::RepeaterMonth.new(:month).offset_by(Time.local(2010, 3, 29), 1, :past)
+    assert_equal 2, time.month
+    assert_equal 28, time.day
   end
 
   def test_offset

data/test/test_parsing.rb

@@ -274,6 +274,12 @@ class TestParsing < Test::Unit::TestCase
     time = parse_now("13:45")
     assert_equal Time.local(2006, 8, 17, 13, 45), time
 
+    time = parse_now("1:01pm")
+    assert_equal Time.local(2006, 8, 16, 13, 01), time
+
+    time = parse_now("2:01pm")
+    assert_equal Time.local(2006, 8, 16, 14, 01), time
+
     time = parse_now("november")
     assert_equal Time.local(2006, 11, 16), time
   end

metadata

@@ -1,8 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: chronic
 version: !ruby/object:Gem::Version 
-  prerelease: 
-  version: 0.4.1
+  hash: 9
+  prerelease: false
+  segments: 
+  - 0
+  - 4
+  - 3
+  version: 0.4.3
 platform: ruby
 authors: 
 - Tom Preston-Werner
@@ -11,7 +16,8 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-06-05 00:00:00 Z
+date: 2011-06-08 00:00:00 +01:00
+default_executable: 
 dependencies: []
 
 description: Chronic is a natural language date/time parser written in pure Ruby.
@@ -27,6 +33,8 @@ extra_rdoc_files:
 - HISTORY.md
 - LICENSE
 files: 
+- .gitignore
+- .yardopts
 - HISTORY.md
 - LICENSE
 - Manifest.txt
@@ -86,6 +94,7 @@ files:
 - test/test_Time.rb
 - test/test_Token.rb
 - test/test_parsing.rb
+has_rdoc: true
 homepage: http://github.com/mojombo/chronic
 licenses: []
 
@@ -99,21 +108,28 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
       version: "0"
 requirements: []
 
 rubyforge_project: chronic
-rubygems_version: 1.8.2
+rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
 summary: Natural language date/time parsing.
 test_files: 
+- test/helper.rb
 - test/test_Chronic.rb
 - test/test_DaylightSavings.rb
 - test/test_Handler.rb