olauzon-chronic_distance 0.0.1

data/README.rdoc

@@ -0,0 +1,78 @@
+= Chronic Distance
+
+A simple Ruby natural language parser for distances. Given a parse-able string distance, it returns the distance in millimeters.
+
+The reverse can also be accomplished with the output method.  Given a distance in millimeters, it outputs a string like "4 kilometers" or "4km" depending on the desired format.
+
+
+== Installation
+
+    $ sudo gem sources -a http://gems.github.com
+    $ sudo gem install olauzon-chronic_distance
+
+
+== Usage
+
+    >> require 'chronic_distance'
+    => true
+
+===Parsing examples
+
+    >> ChronicDistance.parse('5 kilometers')
+    => 5000000
+    
+    >> ChronicDistance.parse('4 miles')
+    => 6437376
+    
+    >> ChronicDistance.parse('four miles')
+    => 6437376
+    
+    >> ChronicDistance.parse('1000m')
+    => 1000000
+    
+    >> ChronicDistance.parse('1000 meters')
+    => 1000000
+    
+    >> ChronicDistance.parse('ten yards')
+    => 9144.0
+    
+    >> ChronicDistance.parse('500 feet')
+    => 152400.0
+
+Nil is returned if the string can't be parsed:
+
+    >> ChronicDistance.parse('kilometers')
+    => nil
+
+===Output examples
+
+    >> ChronicDistance.output(5000000)
+    => 5000000 mm
+
+    >> ChronicDistance.output(5000000, :format => :short, :unit => 'kilometers')
+    => 5km
+
+    >> ChronicDistance.output(5000000, :format => :long, :unit => 'kilometers')
+    => 5 kilometers
+
+    >> ChronicDistance.output(5000000, :unit => 'meters')
+    => 5000 m
+
+    >> ChronicDistance.output(5000000, :format => :long, :unit => 'miles')
+    => 3.10685596118667 miles
+
+
+== Inspiration
+
+ChronicDistance borrows heavily from:
+
+* hpoydar's ChronicDuration http://github.com/hpoydar/chronic_duration
+* mojombo's Chronic http://github.com/mojombo/chronic
+
+
+== TODO
+
+* Benchmark, optimize
+* Other locale support
+
+Copyright (c) 2009 Olivier Lauzon. See MIT-LICENSE for details.

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:minor: 0
+:patch: 1
+:major: 0

data/lib/chronic_distance.rb

@@ -0,0 +1,215 @@
+require 'numerizer'
+
+module ChronicDistance
+  
+  extend self
+  
+  # Given a string representation of distance,
+  # return an integer (or float) representation
+  # of the distance in millimeters. Accepts an options
+  # hash with :round => true as an option.
+  def parse(string, options = {})
+    result = calculate_from_words(cleanup(string))
+    result = result.round.to_i if options[:round]
+    result == 0 ? nil : result
+  end
+  
+  # Given an integer or float distance in millimeters,
+  # and an optional format and unit,
+  # return a formatted string representing distance
+  def output(millimeters, options = {})
+    options[:unit]   ||= 'millimeters'
+    options[:format] ||= :default
+    
+    unit_options      = unit_formatting_options[options[:format]]
+    options[:format]  = :short if options[:format] == :default
+    unit              = unit_format(options[:unit], options[:format])
+    
+    result = humanize_distance(
+                                distance_in_unit(millimeters, options[:unit]),
+                                unit,
+                                unit_options[:pluralize],
+                                unit_options[:spacer]
+                              )
+    
+    result.length == 0 ? nil : result
+  end
+  
+private
+  
+  def distance_in_unit(millimeters, unit)
+    number = (millimeters.to_f / millimeter_multiplier(unit))
+    number = number.round if number == number.round
+    number
+  end
+  
+  def distance_units
+    [
+      'millimeters' ,
+      'centimeters' ,
+      'meters'      ,
+      'kilometers'  ,
+      'inches'      ,
+      'feet'        ,
+      'yards'       ,
+      'miles'
+    ]
+  end
+  
+  def millimeter_multiplier(unit = 'millimeters')
+    return 0 unless distance_units.include?(unit)
+    case unit
+      when 'millimeters'  ;             1
+      when 'centimeters'  ;            10
+      when 'meters'       ;         1_000
+      when 'kilometers'   ;     1_000_000
+      when 'inches'       ;            25.4
+      when 'feet'         ;           304.8
+      when 'yards'        ;           914.4
+      when 'miles'        ;     1_609_344
+    end
+  end
+  
+  def calculate_from_words(string)
+    distance = 0
+    words = string.split(' ')
+    words.each_with_index do |value, key|
+      if value =~ float_matcher
+        distance += (
+                      convert_to_number(value) *
+                      millimeter_multiplier(words[key + 1])
+                    )
+      end
+    end
+    distance
+  end
+  
+  def humanize_distance(number, unit, pluralize, spacer = '')
+    return '' if number == 0
+    display_unit = ''
+    display_unit << unit
+    if !(number == 1) && pluralize
+      if unit == 'inch'
+        display_unit = 'inches'
+      elsif unit == 'foot'
+        display_unit = 'feet'
+      else
+        display_unit << 's'
+      end
+    end
+    
+    result = "#{number}#{spacer}#{display_unit}"
+    result
+  end
+  
+  def cleanup(string)
+    result = Numerizer.numerize(string)
+    result = result.gsub(float_matcher) {|n| " #{n} "}.squeeze(' ').strip
+    result = filter_through_white_list(result)
+  end
+  
+  def convert_to_number(string)
+    string.to_f % 1 > 0 ? string.to_f : string.to_i
+  end
+  
+  def float_matcher
+    /[0-9]*\.?[0-9]+/
+  end
+  
+  # Get rid of unknown words and map found
+  # words to defined distance units
+  def filter_through_white_list(string)
+    result = Array.new
+    string.split(' ').each do |word|
+      if word =~ float_matcher
+        result << word.strip
+        next
+      end
+      result << mappings[word.strip] if mappings.has_key?(word.strip)
+    end
+    result.join(' ')
+  end
+  
+  def mappings
+    maps = Hash.new
+    mappings_by_format.values.each do |format_mappings|
+      maps.merge!(format_mappings)
+    end
+    maps
+  end
+  
+  def unit_format(unit, format = :short)
+    formats = Hash.new
+    mappings_by_format[format].each do |k, v|
+      formats[v] = k
+    end
+    formats[unit]
+  end
+  
+  def unit_formatting_options
+    {
+      :default => {
+        :spacer     => ' ',
+        :pluralize  => false
+      },
+      
+      :short => {
+        :spacer     => '',
+        :pluralize  => false
+      },
+      
+      :long => {
+        :spacer     => ' ',
+        :pluralize  => true
+      }
+    }
+  end
+  
+  def mappings_by_format
+    {
+      :short => {
+        'mm'                => 'millimeters',
+        'cm'                => 'centimeters',
+        'm'                 => 'meters',
+        'km'                => 'kilometers',
+        '"'                 => 'inches',
+        '\''                => 'feet',
+        'yd'                => 'yards',
+        'mile'              => 'miles'
+      },
+      
+      :long => {
+        'millimeter'        => 'millimeters',
+        'centimeter'        => 'centimeters',
+        'meter'             => 'meters',
+        'kilometer'         => 'kilometers',
+        'inch'              => 'inches',
+        'foot'              => 'feet',
+        'yard'              => 'yards',
+        'mile'              => 'miles'
+      },
+      
+      :other => {
+        'mms'               => 'millimeters',
+        'millimeters'       => 'millimeters',
+        'cms'               => 'centimeters',
+        'centimeters'       => 'centimeters',
+        'ms'                => 'meters',
+        'meters'            => 'meters',
+        'k'                 => 'kilometers',
+        'ks'                => 'kilometers',
+        'kms'               => 'kilometers',
+        'kilometers'        => 'kilometers',
+        'inch'              => 'inches',
+        'inches'            => 'inches',
+        'ft'                => 'feet',
+        'feet'              => 'feet',
+        'y'                 => 'yards',
+        'yds'               => 'yards',
+        'yards'             => 'yards',
+        'miles'             => 'miles'
+      }
+    }
+  end
+  
+end

data/lib/numerizer.rb

@@ -0,0 +1,99 @@
+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 misspelling
+                  ['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_distance_spec.rb

@@ -0,0 +1,241 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe ChronicDistance do
+  
+  describe '.parse' do
+    
+    @exemplars = {
+      '1mm'                     =>  1   *  1,
+      '5 mms'                   =>  5   *  1,
+      'fifty millimeters'       =>  50  *  1,
+      '1cm'                     =>  1   * 10,
+      '2 cms'                   =>  2   * 10,
+      '1 centimeter'            =>  1   * 10,
+      '1m'                      =>  1   * 1_000,
+      '2 ms'                    =>  2   * 1_000,
+      '1 meter'                 =>  1   * 1_000,
+      '1k'                      =>  1   * 1_000_000,
+      '5 ks'                    =>  5   * 1_000_000,
+      '1km'                     =>  1   * 1_000_000,
+      '2 kms'                   =>  2   * 1_000_000,
+      '1 kilometer'             =>  1   * 1_000_000,
+      '4 kilometers'            =>  4   * 1_000_000,
+      '1 inch'                  =>  1   *        25.4,
+      '4 inches'                =>  4   *        25.4,
+      '1 ft'                    =>  1   *       304.8,
+      '1y'                      =>  1   *       914.4,
+      'one yd'                  =>  1   *       914.4,
+      'eight yds'               =>  8   *       914.4,
+      '1 yard'                  =>  1   *       914.4,
+      'forty yards'             =>  40  *       914.4,
+      '1 mile'                  =>  1   * 1_609_344,
+      '3.5 miles'               =>  3.5 * 1_609_344,
+      '4 miles'                 =>  4   * 1_609_344,
+      '4 kms 2 miles'           =>  4 * 1_000_000 + 2   * 1_609_344,
+      'those four kms and 2 miles also' =>  4 * 1_000_000 + 2 * 1_609_344
+    }
+    
+    it "should return nil if the string can't be parsed" do
+      ChronicDistance.parse('gobblygoo').should be_nil
+    end
+    
+    it "should return an integer if units are kilometers" do
+      ChronicDistance.parse('4kms').is_a?(Integer).should be_true
+    end
+    
+    it "should return an integer if units are miles" do
+      ChronicDistance.parse('3 miles').is_a?(Integer).should be_true
+    end
+    
+    it "should return a float if units are yards" do
+      ChronicDistance.parse('4 yards').is_a?(Float).should be_true
+    end
+    
+    it "should return an integer if units are yards and distance is rounded" do
+      ChronicDistance.parse('four yards', :round => true).
+      is_a?(Integer).should be_true
+    end
+    
+    @exemplars.each do |key, value|
+      
+      it "should properly parse a distance like #{key}" do
+        ChronicDistance.parse(key).should == value
+      end
+      
+    end
+    
+  end
+  
+  describe '.output' do
+    
+    it "should return nil if the input can't be parsed" do
+      ChronicDistance.parse('gobblygoo').should be_nil
+    end
+    
+    @exemplars = {
+      
+      (1) => {
+        
+        'millimeters' => {
+          :short    => '1mm',
+          :default  => '1 mm',
+          :long     => '1 millimeter'
+        },
+      },
+      
+      (1_609_344) => {
+        
+        'millimeters' => {
+            :short    => '1609344mm',
+            :default  => '1609344 mm',
+            :long     => '1609344 millimeters'
+        },
+      },
+      
+      (1_609_344) => {
+        
+        'centimeters' => {
+          :short    => '160934.4cm',
+          :default  => '160934.4 cm',
+          :long     => '160934.4 centimeters'
+        },
+      },
+      
+      (1_609_344) => {
+        'miles' => {
+          :short    => '1mile',
+          :default  => '1 mile',
+          :long     => '1 mile'
+        }
+      },
+      
+      (4 * 1_609_344) => {
+      
+        'miles' => {
+          :short    => '4mile',
+          :default  => '4 mile',
+          :long     => '4 miles'
+        }
+      },
+      
+      (2.5 * 1_609_344) => {
+      
+        'miles' => {
+          :short    => '2.5mile',
+          :default  => '2.5 mile',
+          :long     => '2.5 miles'
+        }
+      },
+      
+      (4 * 25.4) => {
+        
+        'inches' => {
+          :short    => '4"',
+          :default  => '4 "',
+          :long     => '4 inches'
+        }
+      },
+      
+      (4 * 304.8) => {
+        
+        'feet' => {
+          :short    => '4\'',
+          :default  => '4 \'',
+          :long     => '4 feet'
+        }
+      }
+    }
+    
+    @exemplars.each do |distance, format|
+      format.each do |unit, distance_format|
+        distance_format.each do |format_option, formatted_distance|
+          
+          it "should output #{distance} millimeters as #{formatted_distance}
+              using the #{format_option.to_s} #{unit} format" do
+            ChronicDistance.output( distance,
+                                    :format => format_option,
+                                    :unit   => unit).
+            should == formatted_distance
+          end
+          
+        end
+      end
+    end
+    
+    it "should use the default format when the format is not specified" do
+      ChronicDistance.output(2000).should == '2000 mm'
+    end
+    
+  end
+  
+  describe " private methods" do
+    
+    describe ".calculate_from_words" do
+      
+      it "should return distance in millimeters" do
+        ChronicDistance.
+        instance_eval("calculate_from_words('10 centimeters')").
+        should == 100
+      end
+      
+      it "should return distance in millimeters when mixing input units" do
+        ChronicDistance.
+        instance_eval("calculate_from_words('2 kilometers and 10 centimeters')").
+        should == 2_000_100
+      end
+      
+      it "should return distance in millimeters when mixing input units" do
+        ChronicDistance.
+        instance_eval("calculate_from_words('2 miles and 10 centimeters')").
+        should == 3_218_788
+      end
+      
+    end
+    
+    describe ".cleanup" do
+      
+      it "should clean up extraneous words" do
+        ChronicDistance.
+        instance_eval("cleanup('4 meters and 10 centimeters')").
+        should == '4 meters 10 centimeters'
+      end
+      
+      it "should cleanup extraneous spaces" do
+        ChronicDistance.
+        instance_eval("cleanup('  4 meters and 11     centimeters')").
+        should == '4 meters 11 centimeters'
+      end
+      
+      it "should insert spaces where there aren't any" do
+        ChronicDistance.
+        instance_eval("cleanup('4m11.5cm')").
+        should == '4 meters 11.5 centimeters'
+      end
+      
+    end
+    
+    describe ".unit_format" do
+      
+      it "should select 'meter' for the long meters format" do
+        ChronicDistance.
+        instance_eval("unit_format('meters', :long)").
+        should == 'meter'
+      end
+      
+      it "should select 'm' for the short meters format" do
+        ChronicDistance.
+        instance_eval("unit_format('meters', :short)").
+        should == 'm'
+      end
+      
+      it "should select 'mm' for the short millimeters format" do
+        ChronicDistance.
+        instance_eval("unit_format('millimeters', :short)").
+        should == 'mm'
+      end
+      
+    end
+    
+  end
+  
+end

data/spec/spec_helper.rb

@@ -0,0 +1,10 @@
+require 'rubygems'
+require 'spec'
+
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+
+require 'chronic_distance'
+
+Spec::Runner.configure do |config|
+  
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification 
+name: olauzon-chronic_distance
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Olivier Lauzon
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-03-01 00:00:00 -08:00
+default_executable: 
+dependencies: []
+
+description: TODO
+email: olauzon@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.rdoc
+- VERSION.yml
+- lib/chronic_distance.rb
+- lib/numerizer.rb
+- spec/chronic_distance_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/olauzon/chronic_distance
+post_install_message: 
+rdoc_options: 
+- --inline-source
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: TODO
+test_files: []
+