dimensional 0.0.2

data/lib/dimensional/unit.rb

@@ -0,0 +1,90 @@
+require 'dimensional/dimension'
+require 'dimensional/system'
+require 'set'
+require 'enumerator'
+
+module Dimensional
+  # A standard scale unit for measuring physical quantities.  In addition to the Dimension and System attribute
+  # that are well-defined by classes above, the user-defined metric attribute is available to identify units as
+  # belonging to an arbitrary metric like length, draft or property size.  Effective use of the metric attribute
+  # can simplify presentation of Measures and make parsing of user input more accurate. 
+  # Reference: http://en.wikipedia.org/wiki/Units_of_measurement
+  class Unit
+    @store = Set.new
+
+    def self.register(*args)
+      u = new(*args)
+      raise "Namespace collision: #{u.dimension}:#{u.system}:#{u.name}" if self[u.dimension, u.system, u.name.to_sym]
+      raise "Namespace collision: #{u.dimension}:#{u.system}:#{u.abbreviation}" if self[u.dimension, u.system, u.abbreviation.to_sym]
+      @store << u
+      u
+    end
+
+    # Lookup the unit by name or abbreviation, scoped by dimension and system
+    def self.[](dim, sys, sym)
+      dim = Dimension[dim] unless dim.kind_of?(Dimension)
+      sys = System[sys] unless sys.kind_of?(System)
+      sym = sym.to_sym
+      @store.select{|u| u.dimension == dim}.select{|u| u.system == sys}.detect{|u| sym == u.abbreviation.to_sym || sym == u.name.to_sym}
+    end
+
+    def self.reset!
+      @store.clear
+    end
+
+    attr_reader :name, :abbreviation, :format
+    attr_reader :system, :dimension
+    attr_reader :reference_factor, :reference_unit
+
+    def initialize(name, system, dimension, options = {})
+      @name = name.to_s
+      @system = system
+      @dimension = dimension
+      @reference_factor = options[:reference_factor]
+      @reference_unit = options[:reference_unit]
+      @detector = options[:detector] || /\A#{self.name}\Z/
+      @abbreviation = (options[:abbreviation] || self.name).to_s
+      @format = options[:format] || dimension.nil? ? "%s %U" : "%s%U"
+    end
+    
+    def match(s)
+      @detector.match(s)
+    end
+
+    #  If no reference was provided during initialization, this unit must itself be a base unit.
+    def base?
+      !reference_unit
+    end
+
+    # Returns the unit or array of units on which this unit's scale is ultimately based.
+    def base
+      return self if base?
+      @base ||= reference_unit.kind_of?(Enumerable) ? reference_unit.map{|ru| ru.base} : reference_unit.base
+    end
+    
+    # The conversion factor relative to the base unit.
+    def factor
+      return 1 if base?
+      @factor ||= reference_factor * (reference_unit.kind_of?(Enumerable) ? reference_unit.inject(1){|f, ru| f * ru.factor} : reference_unit.factor)
+    end
+    
+    # Returns the conversion factor to convert to the other unit
+    def convert(other)
+      raise "Units #{self} and #{other} are not commensurable" unless commensurable?(other)
+      return 1 if self == other
+      self.factor / other.factor
+    end
+    
+    def commensurable?(other)
+      dimension == other.dimension
+    end
+    
+    def to_s
+      name rescue super
+    end
+    
+    def inspect
+      "#<#{self.class.inspect}: #{dimension.to_s}:#{system.to_s}:#{to_s}>"
+    end
+  end
+end

data/test/configurator_test.rb

@@ -0,0 +1,144 @@
+require 'test/unit'
+require 'dimensional/configurator'
+
+class ConfiguratorTest < Test::Unit::TestCase
+  include Dimensional
+
+  def setup
+    System.register('International System', 'SI')
+    System.register('United States Customary', 'US')
+    System.register('British Admiralty', 'BA')
+    Dimension.register('Length')
+    Dimension.register('Area', 'A', {Dimension::L => 2})
+    Dimension.register('Mass')
+  end
+
+  def teardown
+    Dimension.reset!
+    System.reset!
+    Unit.reset!
+    Metric.reset!
+  end
+
+  def test_create_configurator
+    assert_instance_of Configurator, c = Configurator.new
+    assert_nil c.context.dimension
+    assert_nil c.context.system
+    assert_nil c.context.unit
+  end
+
+  def test_start_configurator
+    assert Configurator.start
+    assert Configurator.start {true}
+    assert !Configurator.start {false}
+  end
+
+  def test_start_configurator_with_context_args
+    assert_same Dimension::L, Configurator.start(:dimension => Dimension::L){context.dimension}
+  end
+
+  def test_change_dimension_context_for_duration_of_block
+    test_context = self
+    Configurator.start do
+      dimension(Dimension::L) do
+        test_context.assert_equal Dimension::L, context.dimension
+        true
+      end
+      test_context.assert_nil context.dimension
+    end
+  end
+  
+  def test_change_system_context_for_duration_of_block
+    test_context = self
+    Configurator.start do
+      system(System::SI) do
+        test_context.assert_equal System::SI, context.system
+        true
+      end
+      test_context.assert_nil context.system
+    end
+  end
+
+  def test_build_base_unit
+    Configurator.start(:system => System::SI, :dimension => Dimension::L) do
+      base('meter', :detector => /\A(meters?|m)\Z/, :abbreviation => 'm')
+    end
+    assert_instance_of Unit, u = Unit[Dimension::L, System::SI, 'meter']
+    assert_same System::SI, u.system
+    assert_same Dimension::L, u.dimension
+    assert u.base?
+    assert_instance_of Metric, Metric[:L]
+  end
+
+  def test_build_derived_unit
+    Configurator.start(:system => System::SI, :dimension => Dimension::L) do
+      base('meter', :detector => /\A(meters?|m)\Z/, :abbreviation => 'm') do
+        derive('centimeter', 1e-2, :detector => /\A(centimeters?|cm)\Z/, :abbreviation => 'cm')
+      end
+    end
+    u0 = Unit[Dimension::L, System::SI, 'meter']
+    assert_instance_of Unit, u = Unit[Dimension::L, System::SI, 'centimeter']
+    assert_same System::SI, u.system
+    assert_same Dimension::L, u.dimension
+    assert_same u0, u.base
+    assert_equal 1E-2, u.factor
+    assert_equal 'cm', u.abbreviation
+    assert u.match("centimeters")
+  end
+
+  def test_build_aliased_unit
+    Configurator.start(:system => System::SI, :dimension => Dimension::L) do
+      base('meter', :detector => /\A(meters?|m)\Z/, :abbreviation => 'm') do
+        self.alias('decadecimeter')
+      end
+    end
+    u0 = Unit[Dimension::L, System::SI, 'meter']
+    assert_instance_of Unit, u = Unit[Dimension::L, System::SI, 'decadecimeter']
+    assert_same System::SI, u.system
+    assert_same Dimension::L, u.dimension
+    assert_same u0, u.base
+    assert_equal 1, u.factor
+  end
+
+  def test_build_referenced_unit
+    Configurator.start(:system => System::SI, :dimension => Dimension::L) do
+      base('meter', :detector => /\A(meters?|m)\Z/, :abbreviation => 'm')
+      system(:US) do
+        reference('yard', Unit[:L, :SI, 'meter'], 0.9144, :detector => /\A(yards?|yds?)\Z/, :abbreviation => 'yd')
+      end
+    end
+    u0 = Unit[Dimension::L, System::SI, 'meter']
+    assert_instance_of Unit, u = Unit[Dimension::L, System::US, 'yard']
+    assert_equal 0.9144, u.factor
+    assert_same u0, u.base
+  end
+
+  def test_build_combined_unit
+    Configurator.start(:system => System::SI, :dimension => Dimension::L) do
+      base('meter', :detector => /\A(meters?|m)\Z/, :abbreviation => 'm')
+      system(:US) do
+        reference('yard', Unit[:L, :SI, 'meter'], 0.9144, :detector => /\A(yards?|yds?)\Z/, :abbreviation => 'yd')
+        dimension(:A) do
+          combine('square yard', [Unit[:L, :US, 'yard'], Unit[:L, :US, 'yard']], :detector => //, :abbreviation => 'yd2')
+        end
+      end
+    end
+    u1 = Unit[Dimension::L, System::US, 'yard']
+    assert_instance_of Unit, u = Unit[:A, :US, 'square yard']
+    assert_equal Dimension::A, u.dimension
+    assert_equal 0.83612736, u.factor
+    assert_equal [u1.base, u1.base], u.base
+  end
+  
+  def test_register_metric_options
+    Configurator.start(:system => System::SI, :dimension => Dimension::L) do
+      base('meter', :detector => /\A(meters?|m)\Z/, :abbreviation => 'm') do
+        prefer(:length_over_all, :precision => 0.01)
+      end
+    end
+    u = Unit[:L, :SI, 'm']
+    assert_instance_of Metric, m = Metric[:length_over_all]
+    assert_same Metric[:L], m.parent
+    assert_equal 0.01, m.preferences(u)[:precision]
+  end
+end

data/test/demo.rb

@@ -0,0 +1,140 @@
+require 'dimensional/configurator'
+require 'rational'
+
+# Define fundamental dimensions and composite dimensions
+# Reference: http://en.wikipedia.org/wiki/Dimensional_Analysis
+Dimensional::Dimension.register('Length')
+Dimensional::Dimension.register('Mass')
+Dimensional::Dimension.register('Time')
+Dimensional::Dimension.register('Temperature', 'Temp') # Θ is the proper symbol, but it can't be represented in US ASCII
+Dimensional::Dimension.register('Electric Charge', 'Q')
+Dimensional::Dimension.register('Area', 'A', {Dimensional::Dimension[:L] => 2})
+Dimensional::Dimension.register('Volume', 'V', {Dimensional::Dimension[:L] => 3})
+
+# Define common Systems of Measurement
+Dimensional::System.register('SI - International System (kg, tonne, m)', 'SI')
+Dimensional::System.register('US Customary (lbs, ton, ft)', 'US')  # http://en.wikipedia.org/wiki/United_States_customary_units
+Dimensional::System.register('US Customary Troy (oz)', 'USt')  # http://en.wikipedia.org/wiki/United_States_customary_units
+Dimensional::System.register('British Imperial (lbs, ton, ft)', 'Imp')  # http://en.wikipedia.org/wiki/Imperial_units
+
+Dimensional::Configurator.start do
+  dimension(:L) do
+    system(:SI) do
+      base('meter', :detector => /\A(meters?|m)\Z/, :abbreviation => 'm') do
+        derive('centimeter', 1e-2, :detector => /\A(centimeters?|cm)\Z/, :abbreviation => 'cm')
+        derive('kilometer', 1e3, :detector => /\A(kilometers?|km)\Z/, :abbreviation => 'km')
+      end
+    end
+    system(:US) do # As of 1 July 1959 (http://en.wikipedia.org/wiki/United_States_customary_units#Units_of_length)
+      reference('yard', Dimensional::Unit[:L, :SI, 'meter'], 0.9144, :detector => /\A(yards?|yds?)\Z/, :abbreviation => 'yd') do
+        derive('foot', Rational(1,3), :detector => /\A(foot|feet|ft|')\Z/, :abbreviation => "ft", :format => "%p'") do
+          prefer(:hull)
+          derive('inch', Rational(1,12), :detector => /\A(inch|inches|in|")\Z/, :abbreviation =>"in", :format => "%p\"")          
+        end
+        derive('furlong', 220, :detector => /\A(furlongs?)\Z/) do
+          derive('mile', 8, :detector => /\Amiles?\Z/, :abbreviation => 'mi')
+        end
+      end
+    end
+  end
+  dimension(:M) do
+    system(:SI) do
+      base('kilogram', :detector => /\A(kilograms?|kg)\Z/, :abbreviation => 'kg') do
+        derive('tonne', 1e3, :detector => /\A(tonnes?)\Z/, :abbreviation => 't') do # metric ton
+          prefer(:displacement)
+        end
+        derive('gram', 1e-3, :detector => /\A(grams?|g)\Z/, :abbreviation => 'g')
+      end
+    end
+    system(:US) do # Common units for mass and, occasionally, force/weight (http://en.wikipedia.org/wiki/United_States_customary_units#Units_of_mass)
+      reference('pound', Dimensional::Unit[:M, :SI, 'gram'], 453.59237, :detector => /\A(pounds?|lbs?|#)\Z/, :abbreviation => 'lb') do # avoirdupois
+        derive('hundredweight', 100, :detector => /\A(hundredweights?|cwt)\Z/, :abbreviation => 'cwt') do
+          derive('ton', 20, :detector => /\A(tons?|t)\Z/, :abbreviation => 't') do # short ton
+            prefer(:displacement)
+          end
+        end
+        derive('grain', 7000**-1, :detector => /\A(grains?|gr)\Z/, :abbreviation => 'gr') do
+          derive('dram', 27 + Rational(11, 32), :detector => /\A(drams?|dr)\Z/, :abbreviation => 'dr') do
+            derive('ounce', :detector => /\A(ounces?|ozs?)\Z/, :conversion => [437.5, :grain], :abbreviation => 'oz') 
+          end
+        end
+      end
+    end
+    system(:Imp) do
+      reference('pound', Dimensional::Unit[:M, :SI, 'gram'], 453.59237, :detector => /\A(pounds?|lbs?|#)\Z/, :abbreviation => 'lb') do
+        derive('grain', 7000**-1, :detector => /\A(grains?|gr)\Z/, :abbreviation => 'gr')
+        derive('drachm', 256**-1, :detector => /\A(drachms?|dr)\Z/, :abbreviation => 'dr')
+        derive('ounce', 16**-1, :detector => /\A(ounces?|ozs?)\Z/, :abbreviation => 'oz')
+        derive('stone', 14, :detector => /\A(stones?)\Z/)
+        derive('quarter', 28, :detector => /\A(quarters?)\Z/)
+        derive('hundredweight', 112, :detector => /\A(hundredweights?|cwt)\Z/, :abbreviation => 'cwt')
+        derive('ton', 2240, :detector => /\A(tons?|t)\Z/, :abbreviation => 't') do # long ton
+          prefer(:displacement)
+        end
+      end
+    end
+  end
+  dimension(:A) do
+    system(:SI) do
+      combine('square meter', %w(meter meter).map{|name| Dimensional::Unit[:L, :SI, name]}, :detector => /\A(sq\.?\s?meters?|m2)\Z/, :abbreviation => 'm2') do
+        derive('hectare', 10000, :format => "%.4f%U", :abbreviation => 'ha') do
+          prefer(:forestry, :precision => -4, :format => "%s%U")
+        end
+      end
+    end
+    system(:US) do # All measures below are approximations due to the difference between a survey foot and an international foot.
+      combine('square yard', %w(yard yard).map{|name| Dimensional::Unit[:L, :US, name]}, :detector => /yd2/, :abbreviation => 'yd2') do
+        derive('acre', 4840.0)
+      end
+      combine('square mile', %w(mile mile).map{|name| Dimensional::Unit[:L, :US, name]}, :detector => /\A(sq(uare|\.)?\s?miles?)\Z/) do
+        self.alias('section', :detector => /\Asections?\Z/) do
+          derive('township', 36, :detector => /\Atownships?\Z/)
+        end
+      end
+    end
+  end
+
+  dimension(:V) do
+    system(:SI) do
+      combine('cubic meter', %w(meter meter meter).map{|name| Dimensional::Unit[:L, :SI, name]}, :detector => /\A(cubic meters?|m3)\Z/, :abbreviation => "m3") do
+        derive('cubic decimeter', 1e-3, :detector => /\A(cubic decimeters?|dm3)\Z/, :abbreviation => "dm3") do
+          self.alias('liter', :detector => /\A(liters?|l|L)\Z/, :abbreviation => "l") do
+            derive('milliliter', 1E-3, :detector => /\A(milliliters?|ml|mL)\Z/, :abbreviation => "ml")
+          end
+        end
+      end
+    end
+    system(:Imp) do
+      reference('ounce', Dimensional::Unit[:V, :SI, 'milliliter'], 28.4130625, :detector => /\A((fluid )?ounces?|oz)\Z/, :abbreviation => "fl oz")
+      #  register :ounce, :conversion => [28.4130625, :milliliter], :detector => /\A(imperial\s(fluid )?imp\.\sounces?|imp\.\soz)\Z/, :abbreviation => "imp. oz"
+      #  register :gill, :conversion => [5, :ounce], :detector => /\A(gills?|gi)\Z/, :abbreviation => "gi"
+      #  register :cup, :conversion => [2, :gill], :detector => /\A(cups?)\Z/, :abbreviation => "cp"
+      #  register :pint, :conversion => [2, :cup], :detector => /\A(pints?|pt)\Z/, :abbreviation => "pt"
+      #  register :quart, :conversion => [2, :pint], :detector => /\A(quarts?|qt)\Z/, :abbreviation => "qt"
+      #  register :gallon, :conversion => [4, :quart], :detector => /\A(gallons?|gal)\Z/, :abbreviation => "gal"
+    end
+    system(:US) do
+      #  # Common US Customary units for volume, based on the SI Base Unit 'liter'
+      #  register :minim, :conversion => [0.00006161152, :liter], :abbreviation => "min"  # Base Unit
+      #  register :dram, :conversion => [60, :minim], :abbreviation => "fl dr"
+      #  register :ounce, :conversion => [8, :dram], :detector => /\A((fluid )?ounces?|oz)\Z/, :abbreviation => "fl oz"
+      #  register :gill, :conversion => [4, :ounce], :detector => /\A(gills?|gi)\Z/, :abbreviation => "gi"
+      #  register :cup, :conversion => [2, :gill], :detector => /\A(cups?)\Z/, :abbreviation => "cp"
+      #  register :pint, :conversion => [2, :cup], :detector => /\A(pints?|pt)\Z/, :abbreviation => "pt"
+      #  register :quart, :conversion => [2, :pint], :detector => /\A(quarts?|qt)\Z/, :abbreviation => "qt"
+      #  register :gallon, :conversion => [4, :quart], :detector => /\A(gallons?|gal)\Z/, :abbreviation => "gal"
+    end
+  end
+    
+  dimension(nil) do
+    system(:US) do
+      base('each', :detector => /\Aea(ch)?\Z/, :abbreviation => 'ea') do
+        derive('pair', 2, :detector => /\A(pr|pair)\Z/, :abbreviation => 'pr')
+        derive('dozen', 12, :detector => /\A(dz|dozen)\Z/, :abbreviation => 'dz') do
+          derive('gross', 12)
+        end
+        derive('score', 20)
+      end
+    end
+  end
+end    

data/test/dimension_test.rb

@@ -0,0 +1,55 @@
+require 'test/unit'
+require 'dimensional/dimension'
+
+class DimensionTest < Test::Unit::TestCase
+  include Dimensional
+
+  def teardown
+    Dimension.reset!
+  end
+
+  def test_create_new_fundamental_dimension
+    assert_instance_of Dimension, d = Dimension.new('Mass')
+    assert d.fundamental?
+    assert_equal 'Mass', d.name
+    assert_equal 'M', d.symbol
+    assert_equal Hash.new, d.exponents
+  end
+
+  def test_create_new_composite_dimension
+    l = Dimension.new('Length')
+    assert_instance_of Dimension, a = Dimension.new('Hyperspace', 'H4', {l => 4})
+    assert !a.fundamental?
+    assert a.exponents.has_key?(l)
+    assert_equal 4, a.exponents[l]
+  end
+
+  def test_register_new_dimension
+    assert d = Dimension.register('Length')
+    assert_instance_of Dimension, d
+    assert_same d, Dimension['Length']
+    assert_same d, Dimension['L']
+    assert defined?(Dimension::L)
+    assert_same d, Dimension::L
+  end
+
+  def test_register_new_dimension_with_alternate_symbol
+    assert d = Dimension.register('Electric Charge', 'Q')
+    assert_instance_of Dimension, d
+    assert_same d, Dimension['Electric Charge']
+    assert_same d, Dimension['Q']
+    assert defined?(Dimension::Q)
+    assert_same d, Dimension::Q
+  end
+
+  def test_register_new_dimension_with_symbol_that_is_not_a_valid_constant
+    assert d = Dimension.register('Temperature', 'Θ')
+    assert_instance_of Dimension, d
+    assert_same d, Dimension['Temperature']
+    assert_same d, Dimension['Θ']
+  end
+  
+  def test_return_nil_on_nil_lookup
+    assert_nil Dimension[nil]
+  end
+end

data/test/dimensional_test.rb

@@ -0,0 +1,27 @@
+require 'test/unit'
+require 'dimensional'
+
+class DimensionalTest < Test::Unit::TestCase
+  include Dimensional
+
+  def setup
+    load 'test/demo.rb'
+  end
+
+  def teardown
+    Dimension.reset!
+    System.reset!
+    Unit.reset!
+    Metric.reset!
+  end
+
+  def test_a_lot
+    100.times do
+      assert m0 = Measure.parse("1 acre", Metric[:forestry])
+      assert u2 = Unit[:A, :SI, 'hectare']
+      assert m2 = m0.convert(u2)
+      assert_in_delta 0.40468564224, m2, 0.00001
+      assert_equal "0.4047ha", m2.to_s
+    end
+  end
+end