dimensional 0.0.2

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008-2009 Christopher Cyrus Hapgood
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README

@@ -0,0 +1,11 @@
+# This library aims to provide effective parsing of user-supplied measures/metrics, intuitive scaling of those
+# measures into a standard base scale unit and intuitive presentation of values.  It does not attempt to mixin
+# unit-oriented methods into Ruby standard classes -to perform operations, particularly across dimensions, you
+# will need to use basic conversion methods provided by this library combined with standard Ruby numerical oper-
+# ations.  There is no method_missing magic or large mixin of spiffy unit-like methods here.
+
+# The long-term objective for this library is to achieve compliance with the UCUM standard, with additional
+# facilities for simple parsing and formatting of measures according to localized standards, and conversion
+# of measures between units.  References:
+#   UCUM Website: http://unitsofmeasure.org/
+#   UCUM Standard: http://aurora.regenstrief.org/~ucum/ucum.html

data/Rakefile

@@ -0,0 +1,38 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'rubygems'
+
+task :default => [:test]
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.test_files = FileList['test/*_test.rb']
+  t.verbose = true
+end
+Rake::Task['test'].comment = "Run all tests in test/*_test.rb"
+
+spec = Gem::Specification.new do |s|
+  s.platform = Gem::Platform::RUBY
+  s.name = %q{dimensional}
+  s.version = "0.0.2"
+  s.required_ruby_version = '>= 1.6.8'
+  s.date = %q{2009-10-09}
+  s.authors = ["Chris Hapgood"]
+  s.email = %q{cch1@hapgoods.com}
+  s.summary = %q{Dimensional provides handling for numbers with units.}
+  s.homepage = %q{http://cho.hapgoods.com/dimensional}
+  s.description = <<-EOF
+    Dimensional provides handling for dimensional values (numbers with units).  Dimensional values
+    can be parsed, stored, converted and formatted for output.
+  EOF
+  s.files = Dir['lib/**/*.rb'] + Dir['test/**/*.rb']
+  s.files += ["README", "CHANGELOG", "LICENSE", "Rakefile"]
+  s.test_files = Dir['test/**/*.rb']
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+    pkg.need_zip = true
+    pkg.need_tar = false
+end

data/lib/dimensional.rb

@@ -0,0 +1,8 @@
+require 'dimensional/dimension'
+require 'dimensional/system'
+require 'dimensional/unit'
+require 'dimensional/measure'
+
+module Dimensional
+  VERSION = "0.0.2"
+end

data/lib/dimensional/configurator.rb

@@ -0,0 +1,118 @@
+require 'dimensional/dimension'
+require 'dimensional/system'
+require 'dimensional/unit'
+require 'dimensional/metric'
+
+module Dimensional
+  # A little DSL for defining units.  Beware of Ruby 1.8 binding a block variable
+  # to a local variable if they have the same name -it can subtly goof things up.
+  class Configurator
+    # A simple container for holding a context for definition, parsing and formatting of dimensional data
+    Context = Struct.new(:system, :dimension, :unit) do 
+      def valid?
+        true
+      end
+    end
+
+    attr_reader :context
+
+    # Start the configurator with the given context hash and evaluate the supplied block
+    def self.start(c_hash = {}, &block)
+      new.change_context(c_hash, block)
+    end
+
+    def self.dimension_default_metric_name(d)
+      d && d.symbol
+    end
+
+    def initialize(c = Context.new)
+      @context = c
+      raise "Invalid context" unless context.valid?
+    end
+
+    # Change the context, either for the scope of the supplied block or for this instance
+    # NB: The scope in which constants (and classes) are evaluated in instance_eval is surprising in some
+    # versions of Ruby.  Reference: http://groups.google.com/group/ruby-talk-google/browse_thread/thread/186ac9e618a7312d/a8c5dafa7fcfa3dd?lnk=raot
+    def change_context(c_hash, block = nil)
+      new_context = context.dup
+      c_hash.each{|k, v| new_context[k] = v}
+      if block
+        self.class.new(new_context).instance_eval &block
+      else
+        @context = new_context
+        self # Allow chaining
+      end
+    end
+
+    # Change dimension of the context to the given dimension (or its symbol)
+    def dimension(d = nil, &block)
+      d = Dimension[d] unless d.kind_of?(Dimension)
+      change_context({:dimension => d}, block)
+    end
+
+    # Change system of the context to the given system (or its abbreviation)
+    def system(s = nil, &block)
+      s = System[s] unless s.kind_of?(System)
+      change_context({:system => s}, block)
+    end
+
+    # Register a new base unit
+    def base(name, options = {}, &block)
+      u = register_unit(name, options)
+      change_context({:unit => u}, block)
+    end
+
+    # Register a new derived unit
+    def derive(name, factor, options = {}, &block)
+      options[:reference_factor] = factor
+      options[:reference_unit] = context.unit
+      u = register_unit(name, options)
+      change_context({:unit => u}, block)
+    end
+
+    # Register an alias for the unit in context
+    def alias(name, options = {}, &block)
+      derive(name, 1, options, &block)
+    end
+
+    # Register a new unit in the current context that references an arbitrary unit
+    def reference(name, reference, factor, options = {}, &block)
+      options.merge!(:reference_factor => factor, :reference_unit =>  reference)
+      u = register_unit(name, options)
+      change_context({:unit => u}, block)
+    end
+
+    # Register a new unit in the current context that is composed of multiple units
+    def combine(name, components, options = {}, &block)
+      options.merge!(:reference_factor => 1, :reference_unit => components)
+      u = register_unit(name, options)
+      change_context({:unit => u}, block)
+    end
+
+    # Register preferred options for the current unit in the named metric
+    def prefer(name, options = {})
+      m = find_or_register_metric(name, dimension_metric)
+      m.prefer(context.unit, options)
+    end
+
+    def to_s
+      context.to_s
+    end
+    
+    private
+    def register_unit(name, options)
+      u = Unit.register(name, context.system, context.dimension, options)
+      dimension_metric.prefer(u, options)
+      u
+    end
+
+    def dimension_metric
+      find_or_register_metric(self.class.dimension_default_metric_name(context.dimension), nil)
+    end
+
+    # Register the metric defined by the given key and the current context if it does not already exist.
+    def find_or_register_metric(name, parent = nil)
+      Metric[name] || Metric.register(name, context.dimension, parent)
+    end
+  end
+end

data/lib/dimensional/dimension.rb

@@ -0,0 +1,56 @@
+module Dimensional
+  # Represents a dimension that can be used to characterize a physical quantity.  With the exception of certain
+  # fundamental dimensions, all dimensions are expressed as a set of exponents relative to the fundamentals.
+  # Reference: http://en.wikipedia.org/wiki/Dimensional_analysis
+  class Dimension
+    @registry = Hash.new
+    @symbol_registry = Hash.new # Not a Ruby Symbol but a (typically one-character) natural language symbol
+
+    def self.register(*args)
+      d = new(*args)
+      raise "Dimension #{d.name} already exists" if @registry[d.name]
+      raise "Dimension #{d.name}'s symbol already exists" if @symbol_registry[d.symbol]
+      @registry[d.name.to_sym] = d
+      @symbol_registry[d.symbol.to_sym] = d
+      const_set(d.symbol.to_s, d) rescue nil # Not all symbols strings are valid constant names
+      d
+    end
+
+    # Lookup the dimension by name or symbol
+    def self.[](sym)
+      return nil unless sym = sym && sym.to_sym
+      @registry[sym] || @symbol_registry[sym]
+    end
+    
+    # Purge all dimensions from storage.
+    def self.reset!
+      constants.each {|d| remove_const(d)}
+      @registry.clear
+      @symbol_registry.clear
+    end
+
+    attr_reader :exponents, :name, :symbol
+
+    def initialize(name, symbol = nil, exponents = {})
+      exponents.each_pair do |k,v|
+        raise "Invalid fundamental dimension #{k}" unless k.fundamental?
+        raise "Invalid exponent #{v}" unless v.kind_of?(Integer)  # Can't this really be any Rational?
+      end
+      @exponents = Hash.new(0).merge(exponents)
+      @name = name.to_s
+      @symbol = symbol.nil? ? name.to_s.slice(0, 1).upcase : symbol.to_s
+    end
+    
+    def fundamental?
+      exponents.empty?
+    end
+
+    def to_s
+      name rescue super
+    end
+    
+    def to_sym
+      symbol.to_sym
+    end
+  end
+end

data/lib/dimensional/measure.rb

@@ -0,0 +1,98 @@
+require 'dimensional/unit'
+require 'dimensional/metric'
+require 'delegate'
+
+module Dimensional
+  # A numeric-like class used to represent the measure of a physical quantity.  An instance of this
+  # class represents both the unit and the numerical value of a measure.  In turn, the (scale)
+  # unit implies a dimension of the measure.  Instances of this class are immutable (value objects)
+  # Reference: http://en.wikipedia.org/wiki/Physical_quantity
+  class Measure < DelegateClass(Numeric)
+    # A Measure string is composed of a number followed by a unit separated by optional whitespace.
+    # A unit (optional) is composed of a non-digit character followed by zero or more word characters and terminated by some stuff.
+    # Scientific notation is not currently supported.
+    NUMERIC_REGEXP = /((?=\d|\.\d)\d*(?:\.\d*)?)\s*(\D\w*?)?(?=\b|\d|\W|$)/
+  
+    # Parse a string into a Measure instance.  The metric and system parameters may be keys for looking up the associated values. 
+    # Unrecognized strings return nil.
+    def self.parse(str, metric, system = nil)
+      metric = Metric[metric] unless metric.kind_of?(Metric)
+      system = System[system] unless system.kind_of?(System)
+      raise "Metric not specified" unless metric
+      units = metric.units
+      elements = str.to_s.scan(NUMERIC_REGEXP).map do |(v, us)|
+        units = units.select{|u| system == u.system} if system
+        unit = us.nil? ? units.first : units.detect{|u| u.match(us.to_s)}
+        raise ArgumentError, "Unit cannot be determined (#{us})" unless unit
+        system = unit.system
+        value = unit.dimension.nil? ? v.to_i : v.to_f
+        new(value, unit, metric)
+      end
+      # Coalesce the elements into a single Measure instance in "expression base" units.
+      # The expression base is the first provided unit in an expression like "1 mile 200 feet"
+      elements.inject do |t, e|
+        converted_value = e.convert(t.unit)
+        new(t + converted_value, t.unit, metric)
+      end
+    end
+
+    attr_reader :unit, :metric
+
+    def initialize(value, unit, metric = nil)
+      @unit = unit
+      metric = Metric[metric] if metric.kind_of?(Symbol)
+      @metric = metric || Metric[unit.dimension]
+      super(value)
+    end
+
+    # Convert this dimensional value to a different unit
+    def convert(new_unit)
+      new_value = self * unit.convert(new_unit)
+      self.class.new(new_value, new_unit, metric)
+    end
+
+    # Return a new dimensional value expressed in the base unit
+    # DEPRECATE: this method has dubious semantics for composed units as there may be no defined unit with
+    # a matching dimension vector.
+    def base
+      raise "Composed units cannot be converted to a base unit" if unit.reference_unit.kind_of?(Enumerable)
+      convert(unit.base)
+    end
+
+    def native
+      metric.dimension ? to_f : to_i
+    end
+
+    def to_s
+      strfmeasure(metric.preferences(unit)[:format]) rescue super
+    end
+
+    # Like Date, Time and DateTime, Measure represents both a value and a context.  Like those built-in classes,
+    # Measure needs this output method to control the context.  The format string is identical to that used by
+    # Kernel.sprintf with the addition of support for the U specifier:
+    #   %U  replace with unit.  This specifier supports the '#' flag to use the unit's name instead of abbreviation
+    #       In addition, this specifier supports the same width and precision modfiers as the '%s' specifier.  
+    #       For example: %#10.10U
+    # All other specifiers are applied to the numeric value of the measure.
+    # TODO: Support positional arguments (n$).
+    # TODO: Support modulo subordinate units with format hash -> {1 => "'", 12 => :inch} or {1 => "%d#", 16 => "%doz."}
+    def strfmeasure(format = nil, *args)
+      v = if precision = metric.preferences(unit)[:precision]
+        pfactor = 10**(-precision)
+        ((self * pfactor).round / pfactor.to_f).to_s
+      else
+        native
+      end
+      format = format || unit.format
+      format.gsub!(/%(#)?([\d.\-\*]*)U/) do |s|
+        arg = ($1) ? unit.name : unit.abbreviation
+        Kernel.sprintf("%#{$2}s", arg)
+      end
+      Kernel.sprintf(format, v, *args)
+    end
+
+    def inspect
+      "#{super} : #{unit.inspect}"
+    end
+  end
+end

data/lib/dimensional/metric.rb

@@ -0,0 +1,59 @@
+require 'dimensional/dimension'
+
+module Dimensional
+  # A specific physical entity that can be measured.
+  # TODO: Add a hierarchy that allows metrics to be grouped by domain, like shipping, carpentry or sports
+  class Metric
+    include Enumerable
+
+    @registry = Hash.new
+
+    attr_reader :name, :dimension, :parent
+
+    def self.register(*args)
+      m = new(*args)
+      raise "Metric #{m} has already been registered." if @registry[m.name]
+      @registry[m.name && m.name.to_sym] = m
+      m
+    end
+
+    # Lookup the metric by key.  The default metric for a dimension is keyed by the dimension's symbol
+    def self.[](sym)
+      @registry[sym && sym.to_sym]
+    end
+
+    def self.reset!
+      @registry.clear
+    end
+
+    def initialize(name, dimension, parent = nil)
+      @name = name && name.to_s
+      @dimension = dimension
+      @units = Hash.new{|h,k| h[k] = {}}
+      @parent = parent
+    end
+  
+    def prefer(unit, options = {})
+      raise "Unit #{unit} is not compatible with dimension #{dimension || '<nil>'}." unless unit.dimension == dimension
+      @units[unit] = options
+    end
+    
+    def units
+      baseline = parent ? parent.units : @units.keys
+      baseline.sort{|a,b| (@units.has_key?(b) ? 1 : 0) <=> (@units.has_key?(a) ? 1 : 0)}
+    end
+  
+    def preferences(u)
+      baseline = parent ? parent.preferences(u) : {} 
+      baseline.merge(@units[u])
+    end
+
+    def each
+      units.each
+    end
+
+    def to_s
+      name || super
+    end
+  end
+end

data/lib/dimensional/system.rb

@@ -0,0 +1,51 @@
+module Dimensional
+  # Represents a set of units for comprehensive measurement of physical quantities.
+  class System
+    @registry = Hash.new
+    @abbreviation_registry = Hash.new
+
+    def self.register(*args)
+      s = new(*args)
+      raise "System #{s.name} already exists" if @registry[s.name]
+      raise "System #{s.name}'s abbreviation already exists" if @abbreviation_registry[s.abbreviation]
+      @registry[s.name.to_sym] = s
+      @abbreviation_registry[s.abbreviation.to_sym] = s if s.abbreviation
+      const_set(s.abbreviation, s) rescue nil # Not all symbols strings are valid constant names
+      s
+    end
+    
+    # Lookup the system by name or abbreviation
+    def self.[](sym)
+      return nil unless sym = sym && sym.to_sym
+      @abbreviation_registry[sym] || @registry[sym]
+    end
+    
+    # Systems are expected to be declared 'universally' and always be in context so we only dump the name
+    def self._load(str)
+      @registry[str.to_sym]
+    end
+
+    # Purge all systems from storage.
+    def self.reset!
+      constants.each {|d| remove_const(d)}
+      @registry.clear
+      @abbreviation_registry.clear
+    end
+
+    attr_reader :name, :abbreviation
+
+    def initialize(name, abbreviation = nil)
+      @name = name.to_s.freeze
+      @abbreviation = abbreviation && abbreviation.to_s
+    end
+    
+    # Systems are expected to be declared 'universally' and always be in context so we only dump the name
+    def _dump(depth)
+      name
+    end
+
+    def to_s
+      name rescue super
+    end
+  end
+end