hpoydar-chronic_duration 0.7.1 → 0.7.3

data/README.rdoc

@@ -0,0 +1,51 @@
+= Chronic Duration
+
+A simple Ruby natural language parser for elapsed time. (For example, 4 hours and 30 minutes, 6 minutes 4 seconds, 3 days, etc.) Returns all results in seconds. Will return an integer unless you get tricky and need a float. (4 minutes and 13.47 seconds, for example.) 
+
+The reverse can also be accomplished with the output method.  So pass in seconds and you can get strings like 4 mins 31.51 secs (default  format), 4h 3m 30s, or 4:01:29.
+
+== Installation
+
+    $ sudo gem sources -a http://gems.github.com
+    $ sudo gem install hpoydar-chronic_duration
+
+== Usage
+
+    >> require 'chronic_duration'
+    => true
+    >> ChronicDuration.parse('4 minutes and 30 seconds')
+    => 270
+    >> ChronicDuration.output(270)
+    => 4 mins 30 secs
+    >> ChronicDuration.output(270, :format => :short)
+    => 4m 30s
+    >> ChronicDuration.output(270, :format => :long)
+    => 4 minutes 30 seconds
+    >> ChronicDuration.output(270, :format => :chrono)
+    => 4:30
+    
+Nil is returned if the string can't be parsed
+
+Examples of parse-able strings:
+
+* '12.4 secs'
+* '1:20' 
+* '1:20.51'
+* '4:01:01'
+* '3 mins 4 sec'
+* '2 hrs 20 min'
+* '2h20min'
+* '6 mos 1 day'
+* '47 yrs 6 mos and 4d'
+* 'two hours and twenty minutes'
+    
+== Contributors
+
+jduff, olauzon
+    
+== TODO
+
+* Benchmark, optimize
+* Context specific matching (E.g., for '4m30s', assume 'm' is minutes not months)
+* Smartly parse vacation-like durations (E.g., '4 days and 3 nights')
+* :chrono output option should probably change to something like 4 days 4:00:12 instead of 4:04:00:12

data/lib/chronic_duration.rb

@@ -0,0 +1,202 @@
+require 'numerizer'
+module ChronicDuration
+  extend self
+  
+  # Given a string representation of elapsed time,
+  # return an integer (or float, if fractions of a
+  # second are input)
+  def parse(string)
+    result = calculate_from_words(cleanup(string))
+    result == 0 ? nil : result
+  end  
+  
+  # Given an integer and an optional format,
+  # returns a formatted representing elapsed time
+  def output(seconds, opts = {})
+    
+    opts[:format] ||= :default
+    
+    years = months = days = hours = minutes = 0
+    
+    if seconds >= 60
+      minutes = (seconds / 60).to_i 
+      seconds = seconds % 60
+      if minutes >= 60
+        hours = (minutes / 60).to_i
+        minutes = (minutes % 60).to_i
+        if hours >= 24
+          days = (hours / 24).to_i
+          hours = (hours % 24).to_i
+          if days >= 30
+            months = (days / 30).to_i
+            days = (days % 30).to_i
+            if months >= 12
+              years = (months / 12).to_i
+              months = (months % 12).to_i
+            end
+          end
+        end
+      end
+    end
+    
+    joiner = ' '
+    process = nil
+    
+    case opts[:format]
+    when :short
+      dividers = { 
+        :years => 'y', :months => 'm', :days => 'd', :hours => 'h', :minutes => 'm', :seconds => 's' }
+    when :default 
+      dividers = {
+        :years => ' yr', :months => ' mo', :days => ' day', :hours => ' hr', :minutes => ' min', :seconds => ' sec',
+        :pluralize => true }
+    when :long 
+      dividers = {
+        :years => ' year', :months => ' month', :days => ' day', :hours => ' hour', :minutes => ' minute', :seconds => ' second', 
+        :pluralize => true }
+    when :chrono
+      dividers = {
+        :years => ':', :months => ':', :days => ':', :hours => ':', :minutes => ':', :seconds => ':', :keep_zero => true }
+      process = lambda do |str|
+        # Pad zeros
+        # Get rid of lead off times if they are zero
+        # Get rid of lead off zero
+        # Get rid of trailing :
+        str.gsub(/\b\d\b/) { |d| ("%02d" % d) }.gsub(/^(00:)+/, '').gsub(/^0/, '').gsub(/:$/, '')
+      end
+      joiner = ''
+    end
+    
+    result = []
+    [:years, :months, :days, :hours, :minutes, :seconds].each do |t|
+      result << humanize_time_unit( eval(t.to_s), dividers[t], dividers[:pluralize], dividers[:keep_zero] )
+    end
+    
+    result = result.join(joiner).squeeze(' ').strip
+    
+    if process
+      result = process.call(result)
+    end
+    
+    result.length == 0 ? nil : result
+
+  end
+  
+private
+  
+  def humanize_time_unit(number, unit, pluralize, keep_zero)
+    return '' if number == 0 && !keep_zero
+    res = "#{number}#{unit}"
+    # A poor man's pluralizer
+    res << 's' if !(number == 1) && pluralize
+    res
+  end
+  
+  def calculate_from_words(string)
+    val = 0
+    words = string.split(' ')
+    words.each_with_index do |v, k|
+      if v =~ float_matcher
+        val += (convert_to_number(v) * duration_units_seconds_multiplier(words[k + 1] || 'seconds'))
+      end
+    end
+    val
+  end
+  
+  def cleanup(string)
+    res = filter_by_type(Numerizer.numerize(string))
+    res = res.gsub(float_matcher) {|n| " #{n} "}.squeeze(' ').strip
+    res = filter_through_white_list(res)
+  end
+  
+  def convert_to_number(string)
+    string.to_f % 1 > 0 ? string.to_f : string.to_i
+  end
+  
+  def duration_units_list
+    %w(seconds minutes hours days weeks months years)
+  end
+  def duration_units_seconds_multiplier(unit)
+    return 0 unless duration_units_list.include?(unit)
+    case unit
+    when 'years';   31557600 # accounts for leap years
+    when 'months';  3600 * 24 * 30
+    when 'weeks';   3600 * 24 * 7
+    when 'days';    3600 * 24
+    when 'hours';   3600
+    when 'minutes'; 60
+    when 'seconds'; 1
+    end
+  end
+  
+  def error_message
+    'Sorry, that duration could not be parsed'
+  end
+  
+  # Parse 3:41:59 and return 3 hours 41 minutes 59 seconds
+  def filter_by_type(string)
+    if string.gsub(' ', '') =~ /#{float_matcher}(:#{float_matcher})+/
+      res = []
+      string.gsub(' ', '').split(':').reverse.each_with_index do |v,k|
+        return unless duration_units_list[k]
+        res << "#{v} #{duration_units_list[k]}"
+      end
+      res = res.reverse.join(' ')
+    else
+      res = string
+    end
+    res
+  end
+  
+  def float_matcher
+    /[0-9]*\.?[0-9]+/
+  end
+  
+  # Get rid of unknown words and map found
+  # words to defined time units
+  def filter_through_white_list(string)
+    res = []
+    string.split(' ').each do |word|
+      if word =~ float_matcher
+        res << word.strip
+        next
+      end
+      res << mappings[word.strip] if mappings.has_key?(word.strip)
+    end
+    res.join(' ')
+  end
+  
+  def mappings
+    { 
+      'seconds' => 'seconds',
+      'second'  => 'seconds',
+      'secs'    => 'seconds',
+      'sec'     => 'seconds',
+      's'       => 'seconds',
+      'minutes' => 'minutes',
+      'minute'  => 'minutes',
+      'mins'    => 'minutes',
+      'min'     => 'minutes',
+      'm'       => 'minutes',
+      'hours'   => 'hours',
+      'hour'    => 'hours',
+      'hrs'     => 'hours',
+      'hr'      => 'hours',
+      'h'       => 'hours',
+      'days'    => 'days',
+      'day'     => 'days',
+      'dy'      => 'days',
+      'd'       => 'days',
+      'months'  => 'months',
+      'mos'     => 'months',
+      'years'   => 'years',
+      'yrs'     => 'years',
+      'y'       => 'years'
+    }
+  end
+  
+  def white_list
+    self.mappings.map {|k, v| k}
+  end
+  
+end

data/lib/numerizer.rb

@@ -0,0 +1,98 @@
+require 'strscan'
+
+class Numerizer
+
+  DIRECT_NUMS = [
+                  ['eleven', '11'],
+                  ['twelve', '12'],
+                  ['thirteen', '13'],
+                  ['fourteen', '14'],
+                  ['fifteen', '15'],
+                  ['sixteen', '16'],
+                  ['seventeen', '17'],
+                  ['eighteen', '18'],
+                  ['nineteen', '19'],
+                  ['ninteen', '19'], # Common mis-spelling
+                  ['zero', '0'],
+                  ['one', '1'],
+                  ['two', '2'],
+                  ['three', '3'],
+                  ['four(\W|$)', '4\1'],  # The weird regex is so that it matches four but not fourty
+                  ['five', '5'],
+                  ['six(\W|$)', '6\1'],
+                  ['seven(\W|$)', '7\1'],
+                  ['eight(\W|$)', '8\1'],
+                  ['nine(\W|$)', '9\1'],
+                  ['ten', '10'],
+                  ['\ba[\b^$]', '1'] # doesn't make sense for an 'a' at the end to be a 1
+                ]
+
+  TEN_PREFIXES = [ ['twenty', 20],
+                    ['thirty', 30],
+                    ['forty', 40],
+                    ['fourty', 40], # Common misspelling
+                    ['fifty', 50],
+                    ['sixty', 60],
+                    ['seventy', 70],
+                    ['eighty', 80],
+                    ['ninety', 90]
+                  ]
+
+  BIG_PREFIXES = [ ['hundred', 100],
+                    ['thousand', 1000],
+                    ['million', 1_000_000],
+                    ['billion', 1_000_000_000],
+                    ['trillion', 1_000_000_000_000],
+                  ]
+
+  def self.numerize(string)
+    string = string.dup
+  
+    # preprocess
+    string.gsub!(/ +|([^\d])-([^\d])/, '\1 \2') # will mutilate hyphenated-words but shouldn't matter for date extraction
+    string.gsub!(/a half/, 'haAlf') # take the 'a' out so it doesn't turn into a 1, save the half for the end
+    
+    # easy/direct replacements
+    
+    DIRECT_NUMS.each do |dn|
+      string.gsub!(/#{dn[0]}/i, '<num>' + dn[1])
+    end
+    
+    # ten, twenty, etc.
+    
+    TEN_PREFIXES.each do |tp|
+      string.gsub!(/(?:#{tp[0]}) *<num>(\d(?=[^\d]|$))*/i) { '<num>' + (tp[1] + $1.to_i).to_s }
+    end
+    
+    TEN_PREFIXES.each do |tp|
+      string.gsub!(/#{tp[0]}/i) { '<num>' + tp[1].to_s }
+    end
+    
+    # hundreds, thousands, millions, etc.
+    
+    BIG_PREFIXES.each do |bp|
+      string.gsub!(/(?:<num>)?(\d*) *#{bp[0]}/i) { '<num>' + (bp[1] * $1.to_i).to_s}
+      andition(string)
+    end
+    
+    # fractional addition
+    # I'm not combining this with the previous block as using float addition complicates the strings
+    # (with extraneous .0's and such )
+    string.gsub!(/(\d+)(?: | and |-)*haAlf/i) { ($1.to_f + 0.5).to_s }
+    
+    string.gsub(/<num>/, '')
+  end
+
+  private
+  
+  def self.andition(string)
+    sc = StringScanner.new(string)
+    while(sc.scan_until(/<num>(\d+)( | and )<num>(\d+)(?=[^\w]|$)/i))
+      if sc[2] =~ /and/ || sc[1].size > sc[3].size
+        string[(sc.pos - sc.matched_size)..(sc.pos-1)] = '<num>' + (sc[1].to_i + sc[3].to_i).to_s
+        sc.reset
+      end
+    end
+  end
+
+end

data/spec/chronic_duration_spec.rb

@@ -0,0 +1,157 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe ChronicDuration, 'gem' do
+  
+  it "should build" do
+    spec = eval(File.read("#{File.dirname(__FILE__)}/../chronic_duration.gemspec"))
+    FileUtils.rm_f(File.dirname(__FILE__) + "/../chronic_duration-#{spec.version}.gem")
+    system "cd #{File.dirname(__FILE__)}/.. && gem build chronic_duration.gemspec -q --no-verbose"
+    File.exists?(File.dirname(__FILE__) + "/../chronic_duration-#{spec.version}.gem").should be_true
+    FileUtils.rm_f(File.dirname(__FILE__) + "/../chronic_duration-#{spec.version}.gem")
+  end
+  
+end
+
+describe ChronicDuration, '.parse' do
+  
+  @exemplars = { 
+    '1:20'                  => 60 + 20,
+    '1:20.51'               => 60 + 20.51,
+    '4:01:01'               => 4 * 3600 + 60 + 1,
+    '3 mins 4 sec'          => 3 * 60 + 4,
+    'three mins four sec'          => 3 * 60 + 4,
+    '2 hrs 20 min'          => 2 * 3600 + 20 * 60,
+    '2h20min'               => 2 * 3600 + 20 * 60,
+    '6 mos 1 day'           => 6 * 30 * 24 * 3600 + 24 * 3600,
+    '2.5 hrs'               => 2.5 * 3600,
+    '47 yrs 6 mos and 4.5d' => 47 * 31557600 + 6 * 30 * 24 * 3600 + 4.5 * 24 * 3600,
+    'two hours and twenty minutes' => 2 * 3600 + 20 * 60,
+    'four hours and forty minutes' => 4 * 3600 + 40 * 60,
+    'four hours and fourty minutes' => 4 * 3600 + 40 * 60
+  }
+  
+  it "should return nil if the string can't be parsed" do
+    ChronicDuration.parse('gobblygoo').should be_nil
+  end
+  
+  it "should return a float if seconds are in decimals" do
+    ChronicDuration.parse('12 mins 3.141 seconds').is_a?(Float).should be_true
+  end
+  
+  it "should return an integer unless the seconds are in decimals" do
+    ChronicDuration.parse('12 mins 3 seconds').is_a?(Integer).should be_true
+  end
+  
+  @exemplars.each do |k, v|
+    it "should properly parse a duration like #{k}" do
+      ChronicDuration.parse(k).should == v
+    end
+  end
+  
+end
+
+describe ChronicDuration, '.output' do
+  
+  it "should return nil if the input can't be parsed" do
+    ChronicDuration.parse('gobblygoo').should be_nil
+  end
+  
+  @exemplars = { 
+    (60 + 20) => 
+      { 
+        :short    => '1m 20s',
+        :default  => '1 min 20 secs',
+        :long     => '1 minute 20 seconds',
+        :chrono   => '1:20'
+      },
+    (60 + 20.51) => 
+      { 
+        :short    => '1m 20.51s',
+        :default  => '1 min 20.51 secs',
+        :long     => '1 minute 20.51 seconds',
+        :chrono   => '1:20.51'
+      },
+    (4 * 3600 + 60 + 1) => 
+      { 
+        :short    => '4h 1m 1s',
+        :default  => '4 hrs 1 min 1 sec',
+        :long     => '4 hours 1 minute 1 second',
+        :chrono   => '4:01:01'
+      },
+    (2 * 3600 + 20 * 60) => 
+      { 
+        :short    => '2h 20m',
+        :default  => '2 hrs 20 mins',
+        :long     => '2 hours 20 minutes',
+        :chrono   => '2:20'
+      },
+    (2 * 3600 + 20 * 60) => 
+      { 
+        :short    => '2h 20m',
+        :default  => '2 hrs 20 mins',
+        :long     => '2 hours 20 minutes',
+        :chrono   => '2:20:00'
+      },
+    (6 * 30 * 24 * 3600 + 24 * 3600) => 
+      { 
+        :short    => '6m 1d',
+        :default  => '6 mos 1 day',
+        :long     => '6 months 1 day',
+        :chrono   => '6:01:00:00:00' # Yuck. FIXME
+      }
+  }
+  
+  @exemplars.each do |k, v|
+    v.each do |key, val|
+      it "should properly output a duration of #{k} seconds as #{val} using the #{key.to_s} format option" do
+        ChronicDuration.output(k, :format => key).should == val
+      end
+    end
+  end
+  
+  it "should use the default format when the format is not specified" do
+    ChronicDuration.output(2 * 3600 + 20 * 60).should == '2 hrs 20 mins'
+  end
+  
+  
+end
+
+
+# Some of the private methods deserve some spec'ing to aid
+# us in development...
+
+describe ChronicDuration, "private methods" do
+  
+  describe ".filter_by_type" do
+    
+    it "should take a chrono-formatted time like 3:14 and return a human time like 3 minutes 14 seconds" do
+      ChronicDuration.instance_eval("filter_by_type('3:14')").should == '3 minutes 14 seconds'
+    end
+    
+    it "should take a chrono-formatted time like 12:10:14 and return a human time like 12 hours 10 minutes 14 seconds" do
+      ChronicDuration.instance_eval("filter_by_type('12:10:14')").should == '12 hours 10 minutes 14 seconds'
+    end
+    
+    it "should return the input if it's not a chrono-formatted time" do
+      ChronicDuration.instance_eval("filter_by_type('4 hours')").should == '4 hours'
+    end
+  
+  end
+  
+  describe ".cleanup" do
+    
+    it "should clean up extraneous words" do
+      ChronicDuration.instance_eval("cleanup('4 days and 11 hours')").should == '4 days 11 hours'
+    end
+    
+    it "should cleanup extraneous spaces" do
+      ChronicDuration.instance_eval("cleanup('  4 days and 11     hours')").should == '4 days 11 hours'
+    end
+    
+    it "should insert spaces where there aren't any" do
+      ChronicDuration.instance_eval("cleanup('4m11.5s')").should == '4 minutes 11.5 seconds'
+    end
+    
+  end
+  
+end 

data/spec/spec_helper.rb

@@ -0,0 +1,5 @@
+require 'rubygems'
+require 'spec'
+require 'fileutils'
+$LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
+require 'chronic_duration'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: hpoydar-chronic_duration
 version: !ruby/object:Gem::Version 
-  version: 0.7.1
+  version: 0.7.3
 platform: ruby
 authors: 
 - Henry Poydar
@@ -19,10 +19,14 @@ executables: []
 
 extensions: []
 
-extra_rdoc_files: []
-
-files: []
-
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- lib/chronic_duration.rb
+- lib/numerizer.rb
+- spec/chronic_duration_spec.rb
+- spec/spec_helper.rb
+- README.rdoc
 has_rdoc: true
 homepage: http://github.com/hpoydar/chronic_duration
 post_install_message: 
@@ -52,5 +56,5 @@ rubygems_version: 1.2.0
 signing_key: 
 specification_version: 2
 summary: A Ruby natural language parser for elapsed time
-test_files: []
-
+test_files: 
+- spec/chronic_duration_spec.rb