chronic 0.4.1 → 0.4.3

data/.gitignore

@@ -0,0 +1,4 @@
+pkg
+*.rbc
+rdoc
+.yardoc

data/.yardopts

@@ -0,0 +1,3 @@
+-m markdown
+--main README.md
+--title "Chronic - Natural language date/time parsing"

data/HISTORY.md

@@ -1,4 +1,11 @@
-# 0.4.1
+# 0.4.2 / 2011-06-07
+
+* Fix MonthRepeater for fetching past month offsets when current day is
+  later than the last day of a past month (ie on 29th of March when parsing
+  `last month` Chronic would return March instead of February. Now Chronic
+  returns the last day of the past month)
+
+# 0.4.1 / 2011-06-05
 
 * Fix MiniDate ranges for parsing seasons (Thomas Walpole)
 
@@ -27,7 +34,7 @@
 * Fix undefined variable in RepeaterHour (Ryan Garver)
 * Added support for parsing 'Fourty' as another mis-spelling (Lee Reilly)
 * Added ordinal format support: ie 'February 14th, 2004' (Jeff Felchner)
-* Fix dates when working with daylight saving times Mike Mangino
+* Fix dates when working with daylight saving times (Mike Mangino)
 
 # 0.3.0 / 2010-10-22
 

data/Rakefile

@@ -1,44 +1,10 @@
 require 'date'
 
-#############################################################################
-#
-# Helper functions
-#
-#############################################################################
-
-def name
-  @name ||= Dir['*.gemspec'].first.split('.').first
-end
-
 def version
-  line = File.read("lib/#{name}.rb")[/^\s*VERSION\s*=\s*.*/]
-  line.match(/.*VERSION\s*=\s*['"](.*)['"]/)[1]
-end
-
-def rubyforge_project
-  name
-end
-
-def gemspec_file
-  "#{name}.gemspec"
+  contents = File.read File.expand_path('../lib/chronic.rb', __FILE__)
+  contents[/VERSION = "([^"]+)"/, 1]
 end
 
-def gem_file
-  "#{name}-#{version}.gem"
-end
-
-def replace_header(head, header_name)
-  head.sub!(/(\.#{header_name}\s*= ').*'/) { "#{$1}#{send(header_name)}'"}
-end
-
-#############################################################################
-#
-# Standard tasks
-#
-#############################################################################
-
-task :default => :test
-
 require 'rake/testtask'
 Rake::TestTask.new(:test) do |test|
   test.libs << 'lib' << 'test'
@@ -54,33 +20,12 @@ task :coverage do
   sh "open coverage/index.html"
 end
 
-require 'rake/rdoctask'
-Rake::RDocTask.new do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "#{name} #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
-
 desc "Open an irb session preloaded with this library"
 task :console do
   sh "irb -Ilib -rchronic"
 end
 
-#############################################################################
-#
-# Custom tasks (add your own tasks here)
-#
-#############################################################################
-
-
-
-#############################################################################
-#
-# Packaging tasks
-#
-#############################################################################
-
+desc "Release Chronic version #{version}"
 task :release => :build do
   unless `git branch` =~ /^\* master$/
     puts "You must be on the master branch to release!"
@@ -90,51 +35,14 @@ task :release => :build do
   sh "git tag v#{version}"
   sh "git push origin master"
   sh "git push origin v#{version}"
-  sh "gem push pkg/#{name}-#{version}.gem"
+  sh "gem push pkg/chronic-#{version}.gem"
 end
 
-task :build => :gemspec do
+desc "Build a gem from the gemspec"
+task :build do
   sh "mkdir -p pkg"
-  sh "gem build #{gemspec_file}"
-  sh "mv #{gem_file} pkg"
-end
-
-task :gemspec => :validate do
-  # read spec file and split out manifest section
-  spec = File.read(gemspec_file)
-  head, manifest, tail = spec.split("  # = MANIFEST =\n")
-
-  # replace name version and date
-  replace_header(head, :name)
-  replace_header(head, :version)
-
-  #comment this out if your rubyforge_project has a different name
-  replace_header(head, :rubyforge_project)
-
-  # determine file list from git ls-files
-  files = `git ls-files`.
-    split("\n").
-    sort.
-    reject { |file| file =~ /^\./ }.
-    reject { |file| file =~ /^(rdoc|pkg)/ }.
-    map { |file| "    #{file}" }.
-    join("\n")
-
-  # piece file back together and write
-  manifest = "  s.files = %w[\n#{files}\n  ]\n"
-  spec = [head, manifest, tail].join("  # = MANIFEST =\n")
-  File.open(gemspec_file, 'w') { |io| io.write(spec) }
-  puts "Updated #{gemspec_file}"
+  sh "gem build chronic.gemspec"
+  sh "mv chronic-#{version}.gem pkg"
 end
 
-task :validate do
-  libfiles = Dir['lib/*'] - ["lib/#{name}.rb", "lib/#{name}"]
-  unless libfiles.empty?
-    puts "Directory `lib` should only contain a `#{name}.rb` file and `#{name}` dir."
-    exit!
-  end
-  unless Dir['VERSION*'].empty?
-    puts "A `VERSION` file at root level violates Gem best practices."
-    exit!
-  end
-end
+task :default => :test

data/chronic.gemspec

@@ -1,83 +1,17 @@
+$:.unshift File.expand_path('../lib', __FILE__)
+require 'chronic'
+
 Gem::Specification.new do |s|
-  s.name              = 'chronic'
-  s.version           = '0.4.1'
+  s.name = 'chronic'
+  s.version = Chronic::VERSION
   s.rubyforge_project = 'chronic'
-
-  s.summary     = "Natural language date/time parsing."
-  s.description = "Chronic is a natural language date/time parser written in pure Ruby."
-
-  s.authors  = ["Tom Preston-Werner", "Lee Jarvis"]
+  s.summary     = 'Natural language date/time parsing.'
+  s.description = 'Chronic is a natural language date/time parser written in pure Ruby.'
+  s.authors  = ['Tom Preston-Werner', 'Lee Jarvis']
   s.email    = ['tom@mojombo.com', 'lee@jarvis.co']
   s.homepage = 'http://github.com/mojombo/chronic'
-
-  s.rdoc_options = ["--charset=UTF-8"]
+  s.rdoc_options = ['--charset=UTF-8']
   s.extra_rdoc_files = %w[README.md HISTORY.md LICENSE]
-
-  # = MANIFEST =
-  s.files = %w[
-    HISTORY.md
-    LICENSE
-    Manifest.txt
-    README.md
-    Rakefile
-    benchmark/benchmark.rb
-    chronic.gemspec
-    lib/chronic.rb
-    lib/chronic/chronic.rb
-    lib/chronic/grabber.rb
-    lib/chronic/handlers.rb
-    lib/chronic/mini_date.rb
-    lib/chronic/numerizer.rb
-    lib/chronic/ordinal.rb
-    lib/chronic/pointer.rb
-    lib/chronic/repeater.rb
-    lib/chronic/repeaters/repeater_day.rb
-    lib/chronic/repeaters/repeater_day_name.rb
-    lib/chronic/repeaters/repeater_day_portion.rb
-    lib/chronic/repeaters/repeater_fortnight.rb
-    lib/chronic/repeaters/repeater_hour.rb
-    lib/chronic/repeaters/repeater_minute.rb
-    lib/chronic/repeaters/repeater_month.rb
-    lib/chronic/repeaters/repeater_month_name.rb
-    lib/chronic/repeaters/repeater_season.rb
-    lib/chronic/repeaters/repeater_season_name.rb
-    lib/chronic/repeaters/repeater_second.rb
-    lib/chronic/repeaters/repeater_time.rb
-    lib/chronic/repeaters/repeater_week.rb
-    lib/chronic/repeaters/repeater_weekday.rb
-    lib/chronic/repeaters/repeater_weekend.rb
-    lib/chronic/repeaters/repeater_year.rb
-    lib/chronic/scalar.rb
-    lib/chronic/separator.rb
-    lib/chronic/span.rb
-    lib/chronic/tag.rb
-    lib/chronic/time_zone.rb
-    lib/chronic/token.rb
-    test/helper.rb
-    test/test_Chronic.rb
-    test/test_DaylightSavings.rb
-    test/test_Handler.rb
-    test/test_MiniDate.rb
-    test/test_Numerizer.rb
-    test/test_RepeaterDayName.rb
-    test/test_RepeaterFortnight.rb
-    test/test_RepeaterHour.rb
-    test/test_RepeaterMinute.rb
-    test/test_RepeaterMonth.rb
-    test/test_RepeaterMonthName.rb
-    test/test_RepeaterTime.rb
-    test/test_RepeaterWeek.rb
-    test/test_RepeaterWeekday.rb
-    test/test_RepeaterWeekend.rb
-    test/test_RepeaterYear.rb
-    test/test_Span.rb
-    test/test_Time.rb
-    test/test_Token.rb
-    test/test_parsing.rb
-  ]
-  # = MANIFEST =
-
-  ## Test files will be grabbed from the file list. Make sure the path glob
-  ## matches what you actually use.
-  s.test_files = s.files.select { |path| path =~ /^test\/test_.*\.rb/ }
-end
+  s.files = `git ls-files`.split("\n")
+  s.test_files = `git ls-files -- test`.split("\n")
+end

data/lib/chronic/chronic.rb

@@ -11,76 +11,76 @@ module Chronic
 
   class << self
 
-    # 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 <tt>:guess</tt>). If no date or time can be found,
-    # +nil+ will be returned.
+    # Parses a string containing a natural language date or time
     #
-    # Options are:
+    # 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
     #
-    # [<tt>:context</tt>]
-    #     <tt>:past</tt> or <tt>:future</tt> (defaults to <tt>:future</tt>)
+    # @option opts [Symbol] :context (:future)
+    #   * If your string represents a birthday, you can set `:context` to
+    #     `:past` and if an ambiguous string is given, it will assume it is
+    #     in the past. Specify `:future` or omit to set a future context.
     #
-    #     If your string represents a birthday, you can set <tt>:context</tt> to <tt>:past</tt>
-    #     and if an ambiguous string is given, it will assume it is in the
-    #     past. Specify <tt>:future</tt> or omit to set a future context.
+    # @option opts [Object] :now (Time.now)
+    #   * By setting `:now` to a Time, all computations will be based off of
+    #     that time instead of `Time.now`. If set to nil, Chronic will use
+    #     `Time.now`
     #
-    # [<tt>:now</tt>]
-    #     Time (defaults to Time.now)
+    # @option opts [Boolean] :guess (true)
+    #   * By default, the parser will guess a single point in time for the
+    #     given date or time. If you'd rather have the entire time span
+    #     returned, set `:guess` to `false` and a {Chronic::Span} will
+    #     be returned
     #
-    #     By setting <tt>:now</tt> to a Time, all computations will be based off
-    #     of that time instead of Time.now. If set to nil, Chronic will use Time.now.
-    #
-    # [<tt>:guess</tt>]
-    #     +true+ or +false+ (defaults to +true+)
-    #
-    #     By default, the parser will guess a single point in time for the
-    #     given date or time. If you'd rather have the entire time span returned,
-    #     set <tt>:guess</tt> to +false+ and a Chronic::Span will be returned.
-    #
-    # [<tt>:ambiguous_time_range</tt>]
-    #     Integer or <tt>:none</tt> (defaults to <tt>6</tt> (6am-6pm))
-    #
-    #     If an Integer is given, ambiguous times (like 5:00) will be
+    # @option opts [Integer] :ambiguous_time_range (6)
+    #   * If an Integer is given, ambiguous times (like 5:00) will be
     #     assumed to be within the range of that time in the AM to that time
-    #     in the PM. For example, if you set it to <tt>7</tt>, then the parser will
-    #     look for the time between 7am and 7pm. In the case of 5:00, it would
-    #     assume that means 5:00pm. If <tt>:none</tt> is given, no assumption
-    #     will be made, and the first matching instance of that time will
-    #     be used.
+    #     in the PM. For example, if you set it to `7`, then the parser
+    #     will look for the time between 7am and 7pm. In the case of 5:00, it
+    #     would assume that means 5:00pm. If `:none` is given, no
+    #     assumption will be made, and the first matching instance of that
+    #     time will be used
     #
-    # [<tt>:endian_precedence</tt>]
-    #     Array (defaults to <tt>[:middle, :little]</tt>)
-    #
-    #     By default, Chronic will parse "03/04/2011" as the fourth day
+    # @option opts [Array] :endian_precedence ([:middle, :little])
+    #   * By default, Chronic will parse "03/04/2011" as the fourth day
     #     of the third month. Alternatively you can tell Chronic to parse
     #     this as the third day of the fourth month by altering the
-    #     <tt>:endian_precedence</tt> to <tt>[:little, :middle]</tt>.
-    def parse(text, specified_options = {})
+    #     `:endian_precedence` to `[:little, :middle]`
+    #
+    # @option opts [Integer] :ambiguous_year_future_bias (50)
+    #   * When parsing two digit years (ie 79) unlike Rubys Time class,
+    #     Chronic will attempt to assume the full year using this figure.
+    #     Chronic will look x amount of years into the future and past. If
+    #     the two digit year is `now + x years` it's assumed to be the
+    #     future, `now - x years` is assumed to be the past
+    #
+    # @return [Time, Chronic::Span, nil]
+    def parse(text, opts={})
       @text = text
-      options = DEFAULT_OPTIONS.merge specified_options
+      options = DEFAULT_OPTIONS.merge opts
 
       # ensure the specified options are valid
-      (specified_options.keys-DEFAULT_OPTIONS.keys).each {|key| raise(InvalidArgumentException, "#{key} is not a valid option key.")}
+      (opts.keys - DEFAULT_OPTIONS.keys).each do |key|
+        raise InvalidArgumentException, "#{key} is not a valid option key."
+      end
 
-      [:past, :future, :none].include?(options[:context]) || raise(InvalidArgumentException, "Invalid value ':#{options[:context]}' for :context specified. Valid values are :past and :future.")
+      unless [:past, :future, :none].include?(options[:context])
+        raise InvalidArgumentException, "Invalid context, :past/:future only"
+      end
 
+      options[:text] = text
       options[:now] ||= Chronic.time_class.now
-      @now = options[:now]
-
-      # put the text into a normal format to ease scanning
-      text = pre_normalize(text)
+      Chronic.now = options[:now]
 
       # tokenize words
-      @tokens = tokenize(text, options)
+      tokens = tokenize(text, options)
 
       if Chronic.debug
-        puts "+---------------------------------------------------"
-        puts "| " + @tokens.to_s
-        puts "+---------------------------------------------------"
+        puts "+#{'-' * 51}\n| #{tokens}\n+#{'-' * 51}"
       end
 
-      span = tokens_to_span(@tokens, options)
+      span = tokens_to_span(tokens, options)
 
       if options[:guess]
         guess span
@@ -89,52 +89,66 @@ module Chronic
       end
     end
 
-    # Clean up the specified input text by stripping unwanted characters,
-    # converting idioms to their canonical form, converting number words
-    # to numbers (three => 3), and converting ordinal words to numeric
+    # Clean up the specified text ready for parsing
+    #
+    # Clean up the string by stripping unwanted characters, converting
+    # idioms to their canonical form, converting number words to numbers
+    # (three => 3), and converting ordinal words to numeric
     # ordinals (third => 3rd)
-    def pre_normalize(text) #:nodoc:
-      normalized_text = text.to_s.downcase
-      normalized_text.gsub!(/['"\.,]/, '')
-      normalized_text.gsub!(/\bsecond (of|day|month|hour|minute|second)\b/, '2nd \1')
-      normalized_text = numericize_numbers(normalized_text)
-      normalized_text.gsub!(/ \-(\d{4})\b/, ' tzminus\1')
-      normalized_text.gsub!(/([\/\-\,\@])/) { ' ' + $1 + ' ' }
-      normalized_text.gsub!(/\b0(\d+:\d+\s*pm?\b)/, '\1')
-      normalized_text.gsub!(/\btoday\b/, 'this day')
-      normalized_text.gsub!(/\btomm?orr?ow\b/, 'next day')
-      normalized_text.gsub!(/\byesterday\b/, 'last day')
-      normalized_text.gsub!(/\bnoon\b/, '12:00')
-      normalized_text.gsub!(/\bmidnight\b/, '24:00')
-      normalized_text.gsub!(/\bbefore now\b/, 'past')
-      normalized_text.gsub!(/\bnow\b/, 'this second')
-      normalized_text.gsub!(/\b(ago|before)\b/, 'past')
-      normalized_text.gsub!(/\bthis past\b/, 'last')
-      normalized_text.gsub!(/\bthis last\b/, 'last')
-      normalized_text.gsub!(/\b(?:in|during) the (morning)\b/, '\1')
-      normalized_text.gsub!(/\b(?:in the|during the|at) (afternoon|evening|night)\b/, '\1')
-      normalized_text.gsub!(/\btonight\b/, 'this night')
-      normalized_text.gsub!(/\b\d+:?\d*[ap]\b/,'\0m')
-      normalized_text.gsub!(/(\d)([ap]m|oclock)\b/, '\1 \2')
-      normalized_text.gsub!(/\b(hence|after|from)\b/, 'future')
-      normalized_text
+    #
+    # @example
+    #   Chronic.pre_normalize('first day in May')
+    #     #=> "1st day in may"
+    #
+    #   Chronic.pre_normalize('tomorrow after noon')
+    #     #=> "next day future 12:00"
+    #
+    #   Chronic.pre_normalize('one hundred and thirty six days from now')
+    #     #=> "136 days future this second"
+    #
+    # @param [String] text The string to normalize
+    # @return [String] A new string ready for Chronic to parse
+    def pre_normalize(text)
+      text = text.to_s.downcase
+      text.gsub!(/['"\.,]/, '')
+      text.gsub!(/\bsecond (of|day|month|hour|minute|second)\b/, '2nd \1')
+      text = numericize_numbers(text)
+      text.gsub!(/ \-(\d{4})\b/, ' tzminus\1')
+      text.gsub!(/([\/\-\,\@])/) { ' ' + $1 + ' ' }
+      text.gsub!(/\b0(\d+:\d+\s*pm?\b)/, '\1')
+      text.gsub!(/\btoday\b/, 'this day')
+      text.gsub!(/\btomm?orr?ow\b/, 'next day')
+      text.gsub!(/\byesterday\b/, 'last day')
+      text.gsub!(/\bnoon\b/, '12:00')
+      text.gsub!(/\bmidnight\b/, '24:00')
+      text.gsub!(/\bbefore now\b/, 'past')
+      text.gsub!(/\bnow\b/, 'this second')
+      text.gsub!(/\b(ago|before)\b/, 'past')
+      text.gsub!(/\bthis past\b/, 'last')
+      text.gsub!(/\bthis last\b/, 'last')
+      text.gsub!(/\b(?:in|during) the (morning)\b/, '\1')
+      text.gsub!(/\b(?:in the|during the|at) (afternoon|evening|night)\b/, '\1')
+      text.gsub!(/\btonight\b/, 'this night')
+      text.gsub!(/\b\d+:?\d*[ap]\b/,'\0m')
+      text.gsub!(/(\d)([ap]m|oclock)\b/, '\1 \2')
+      text.gsub!(/\b(hence|after|from)\b/, 'future')
+      text
     end
 
-    # Convert number words to numbers (three => 3)
-    def numericize_numbers(text) #:nodoc:
+    # Convert number words to numbers (three => 3, fourth => 4th)
+    #
+    # @see Numerizer.numerize
+    # @param [String] text The string to convert
+    # @return [String] A new string with words converted to numbers
+    def numericize_numbers(text)
       Numerizer.numerize(text)
     end
 
-    def tokenize(text, options) #:nodoc:
-      tokens = text.split(' ').map { |word| Token.new(word) }
-      [Repeater, Grabber, Pointer, Scalar, Ordinal, Separator, TimeZone].each do |tok|
-        tokens = tok.scan(tokens, options)
-      end
-      tokens.delete_if { |token| !token.tagged? }
-    end
-
     # Guess a specific time within the given span
-    def guess(span) #:nodoc:
+    #
+    # @param [Span] span
+    # @return [Time]
+    def guess(span)
       return nil if span.nil?
       if span.width > 1
         span.begin + (span.width / 2)
@@ -142,16 +156,133 @@ module Chronic
         span.begin
       end
     end
+
+    # List of {Handler} definitions. See {parse} for a list of options this
+    # method accepts
+    #
+    # @see parse
+    # @return [Hash] A Hash of Handler definitions
+    def definitions(options={})
+      options[:endian_precedence] ||= [:middle, :little]
+
+      @definitions ||= {
+        :time => [
+          Handler.new([:repeater_time, :repeater_day_portion?], nil)
+        ],
+
+        :date => [
+          Handler.new([:repeater_day_name, :repeater_month_name, :scalar_day, :repeater_time, :separator_slash_or_dash?, :time_zone, :scalar_year], :handle_rdn_rmn_sd_t_tz_sy),
+          Handler.new([:repeater_month_name, :scalar_day, :scalar_year], :handle_rmn_sd_sy),
+          Handler.new([:repeater_month_name, :ordinal_day, :scalar_year], :handle_rmn_od_sy),
+          Handler.new([:repeater_month_name, :scalar_day, :scalar_year, :separator_at?, 'time?'], :handle_rmn_sd_sy),
+          Handler.new([:repeater_month_name, :ordinal_day, :scalar_year, :separator_at?, 'time?'], :handle_rmn_od_sy),
+          Handler.new([:repeater_month_name, :scalar_day, :separator_at?, 'time?'], :handle_rmn_sd),
+          Handler.new([:repeater_time, :repeater_day_portion?, :separator_on?, :repeater_month_name, :scalar_day], :handle_rmn_sd_on),
+          Handler.new([:repeater_month_name, :ordinal_day, :separator_at?, 'time?'], :handle_rmn_od),
+          Handler.new([:repeater_time, :repeater_day_portion?, :separator_on?, :repeater_month_name, :ordinal_day], :handle_rmn_od_on),
+          Handler.new([:repeater_month_name, :scalar_year], :handle_rmn_sy),
+          Handler.new([:scalar_day, :repeater_month_name, :scalar_year, :separator_at?, 'time?'], :handle_sd_rmn_sy),
+          Handler.new([:scalar_year, :separator_slash_or_dash, :scalar_month, :separator_slash_or_dash, :scalar_day, :separator_at?, 'time?'], :handle_sy_sm_sd),
+          Handler.new([:scalar_month, :separator_slash_or_dash, :scalar_year], :handle_sm_sy)
+        ],
+
+        # tonight at 7pm
+        :anchor => [
+          Handler.new([:grabber?, :repeater, :separator_at?, :repeater?, :repeater?], :handle_r),
+          Handler.new([:grabber?, :repeater, :repeater, :separator_at?, :repeater?, :repeater?], :handle_r),
+          Handler.new([:repeater, :grabber, :repeater], :handle_r_g_r)
+        ],
+
+        # 3 weeks from now, in 2 months
+        :arrow => [
+          Handler.new([:scalar, :repeater, :pointer], :handle_s_r_p),
+          Handler.new([:pointer, :scalar, :repeater], :handle_p_s_r),
+          Handler.new([:scalar, :repeater, :pointer, 'anchor'], :handle_s_r_p_a)
+        ],
+
+        # 3rd week in march
+        :narrow => [
+          Handler.new([:ordinal, :repeater, :separator_in, :repeater], :handle_o_r_s_r),
+          Handler.new([:ordinal, :repeater, :grabber, :repeater], :handle_o_r_g_r)
+        ]
+      }
+
+      endians = [
+        Handler.new([:scalar_month, :separator_slash_or_dash, :scalar_day, :separator_slash_or_dash, :scalar_year, :separator_at?, 'time?'], :handle_sm_sd_sy),
+        Handler.new([:scalar_day, :separator_slash_or_dash, :scalar_month, :separator_slash_or_dash, :scalar_year, :separator_at?, 'time?'], :handle_sd_sm_sy)
+      ]
+
+      case endian = Array(options[:endian_precedence]).first
+      when :little
+        @definitions[:endian] = endians.reverse
+      when :middle
+        @definitions[:endian] = endians
+      else
+        raise InvalidArgumentException, "Unknown endian option '#{endian}'"
+      end
+
+      @definitions
+    end
+
+    private
+
+    def tokenize(text, options)
+      text = pre_normalize(text)
+      tokens = text.split(' ').map { |word| Token.new(word) }
+      [Repeater, Grabber, Pointer, Scalar, Ordinal, Separator, TimeZone].each do |tok|
+        tokens = tok.scan(tokens, options)
+      end
+      tokens.select { |token| token.tagged? }
+    end
+
+    def tokens_to_span(tokens, options)
+      definitions = definitions(options)
+
+      (definitions[:date] + definitions[:endian]).each do |handler|
+        if handler.match(tokens, definitions)
+          puts "-date" if Chronic.debug
+          good_tokens = tokens.select { |o| !o.get_tag Separator }
+          return Handlers.send(handler.handler_method, good_tokens, options)
+        end
+      end
+
+      definitions[:anchor].each do |handler|
+        if handler.match(tokens, definitions)
+          puts "-anchor" if Chronic.debug
+          good_tokens = tokens.select { |o| !o.get_tag Separator }
+          return Handlers.send(handler.handler_method, good_tokens, options)
+        end
+      end
+
+      definitions[:arrow].each do |handler|
+        if handler.match(tokens, definitions)
+          puts "-arrow" if Chronic.debug
+          tags = [SeparatorAt, SeparatorSlashOrDash, SeparatorComma]
+          good_tokens = tokens.reject { |o| tags.any? { |t| o.get_tag(t) } }
+          return Handlers.send(handler.handler_method, good_tokens, options)
+        end
+      end
+
+      definitions[:narrow].each do |handler|
+        if handler.match(tokens, definitions)
+          puts "-narrow" if Chronic.debug
+          good_tokens = tokens.select { |o| !o.get_tag Separator }
+          return Handlers.send(handler.handler_method, tokens, options)
+        end
+      end
+
+      puts "-none" if Chronic.debug
+      return nil
+    end
+
   end
 
   # Internal exception
-  class ChronicPain < Exception #:nodoc:
-
+  class ChronicPain < Exception
   end
 
   # This exception is raised if an invalid argument is provided to
   # any of Chronic's methods
   class InvalidArgumentException < Exception
-
   end
 end

data/lib/chronic/grabber.rb

@@ -1,11 +1,20 @@
 module Chronic
-  class Grabber < Tag #:nodoc:
+  class Grabber < Tag
+
+    # Scan an Array of {Token}s and apply any necessary Grabber 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 [Grabber, nil]
     def self.scan_for_all(token)
       scan_for token, self,
       {