dimensional 0.0.6 → 0.1.1

data/CHANGELOG

@@ -0,0 +1,2 @@
+0.1.0
+0.1.1	Simpler conversion system-to-system and redefinition of preference semantics.

data/Rakefile

@@ -19,7 +19,7 @@ spec = Gem::Specification.new do |s|
   s.name = %q{dimensional}
   s.version = Dimensional::VERSION
   s.required_ruby_version = '>= 1.6.8'
-  s.date = %q{2009-10-09}
+  s.date = Time.now.strftime("%Y-%m-%d")
   s.authors = ["Chris Hapgood"]
   s.email = %q{cch1@hapgoods.com}
   s.summary = %q{Dimensional provides handling for numbers with units.}

data/lib/dimensional.rb

@@ -1,7 +1,7 @@
 require 'dimensional/dimension'
 require 'dimensional/system'
 require 'dimensional/unit'
-require 'dimensional/measure'
+require 'dimensional/metric'
 require 'dimensional/version'
 
 module Dimensional

data/lib/dimensional/configuration.rb

@@ -2,47 +2,120 @@ require 'dimensional/dimension'
 require 'dimensional/system'
 require 'dimensional/unit'
 require 'dimensional/metric'
+require 'forwardable'
 
 # Encapsulates the application-specific configuration of Dimensional elements, including
-#   * Dimensions, including which are considered fundamental.
+#   * Dimensions
 #   * Systems, including a prioritized array of Systems to be consulted during parsing.
-#   * Metrics, including Unit formatting and parsing options per Metric
+#   * Metrics, including associated Unit formatting and parsing options
 #   * Units
 # Configurations can be constructed with a Configurator.  They can also be copied and extended.
 #
 # Metric == context
 #
 # Configuration#options(unit, context) => options_hash
+#   a hash of formatting and parsing options for the given unit in the given context
 
-# Configuration#format(unit, context) => format_string
+# Configuration#format(unit, context = nil) => format_string
 #   #strfmeasure-compatible format string for given unit and given context
 
-# Configuration#detectors(context) => detector_hash
-#   #parse-compatible detector->unit pairs suitable for given context
+# Configuration#detectors(context = nil) => detector_hash
+#   Measure#parse-compatible detector->unit pairs suitable for given context
 
-# Measure.parse(str, detectors) => instance of measure with unit matched by detectors
-# Measure#strfmeasure(format)
-# Measure#change_system(system)
+# Measure.parse(str, detectors) => measure
+#    instance of measure with unit matched by detectors
 
-class Configuration
-  class Systems < Array
-  end
+# Measure.new(value, unit, context) => measure
+#    instance of measure with given value and unit, and with the given context.
+
+# Measure#strfmeasure(format) => str
+#   formatted string representing the given measure
+
+# Measure#change_system(system) => measure
+#   a
 
+# Create a Measure from a Numeric and Unit, optionally for a given Metric (load attribute from DB)
+# Create a Measure from a String for a given Metric with a preferred System (parse form input)
+# Convert a Measure from a given Unit to the most appropriate Unit in a given System
+# Format a Measure as a String given a specific format String
+
+class Configuration
+  # A (unordered and unique) set of dimensions with generous lookup semantics
+  # TODO: Prevent a composite dimension from being added unless its fundamentals are already included
   class Dimensions < Set
+    def [](str)
+      raise unless str
+      detect{|d| d.name == str.to_s || d.symbol == str.to_s} 
+    end
   end
 
-  class Metrics < Set
-  end
+  # An ordered and unique collection of systems with generous lookup semantics and re-orderability.  Order
+  # is not defined prior to invoking #priortize.
+  class Systems < DelegateClass(Set)
+    include Enumerable
+    attr_reader :priority
+    
+    def initialize(*args)
+      @priority = []
+      super(args)
+    end
 
-  class Units < Set
+    # Prioritize the system according to the given array of lookup keys
+    def prioritize(keys)
+      new = keys.map{|k| self[k]}.uniq.compact
+      priority.replace(new)
+    end
+    
+    # Iteration is in priority order.  We directly access the delegate object so that enumerable
+    # methods needed here don't recurse (#each being called from a mixin apparently triggers this behavior) 
+    def each(&block)
+      @_dc_obj.sort_by{|s| priority.index(s) || priority.size}.each(&block)
+    end
+
+    def [](str)
+      detect {|s| (s == str.to_s) || (s.abbreviation == str.to_s) } 
+    end
   end
 
-  attr_reader :dimensions, :systems, :units, :metrics
+  attr_reader :dimensions, :systems, :metrics
+  
+  include Enumerable
+  extend Forwardable
 
   def initialize
     @dimensions = Dimensions.new
     @systems = Systems.new
-    @metrics = Metrics.new
-    @units = Units.new
+    @units = Set.new
+  end
+  
+  def_delegators :@units, :each
+  def_delegators :to_set, :size, :length, :empty?
+
+  def add(u)
+    systems << u.system
+    # TODO: Add fundamental dimensions before adding composite dimension
+    dimensions << u.dimension
+    @units << u
+  end
+  alias << add
+  
+  def [](dim, sys, str)
+    us = select{|u| u.dimension == dim && u.system == sys}
+    us.detect{|u| str == u.name || (u.abbreviation && str == u.abbreviation)}
+  end
+
+  # Returns a new configuration with only the units with the specified dimension
+  def dimension(d)
+    scope(@units.select{|u| u.dimension == d})
+  end
+  
+  private
+  # Returns a new configuration scoped to the supplied units
+  def scope(us)
+    config = self.dup
+    config.instance_eval do
+      @units = us
+    end
+    config
   end
 end

data/lib/dimensional/configurator.rb

@@ -8,7 +8,7 @@ module Dimensional
   # 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 
+    Context = Struct.new(:system, :dimension, :unit) do
       def valid?
         true
       end
@@ -57,15 +57,13 @@ module Dimensional
 
     # Register a new base unit
     def base(name, abbreviation = nil, options = {}, &block)
-      u = unit(name, {:abbreviation => abbreviation})
-      dimension_metric.prefer(u, default_preferences(u).merge(options))
+      u = unit(name, {:abbreviation => abbreviation}.merge(options))
       change_context({:unit => u}, block)
     end
 
     # Register a new derived unit
     def derive(name, abbreviation, factor, options = {}, &block)
-      u = unit(name, {:abbreviation => abbreviation, :reference_unit => context.unit, :reference_factor => factor})
-      dimension_metric.prefer(u, default_preferences(u).merge(options))
+      u = unit(name, {:abbreviation => abbreviation, :reference_units => {context.unit => 1}, :reference_factor => factor}.merge(options))
       change_context({:unit => u}, block)
     end
 
@@ -75,49 +73,24 @@ module Dimensional
     end
 
     # Register a new unit in the current context that references an arbitrary unit
-    def reference(name, abbreviation, u, f, options = {}, &block)
-      u = unit(name, :abbreviation => abbreviation, :reference_unit => u, :reference_factor => f)
-      dimension_metric.prefer(u, default_preferences(u).merge(options))
+    def reference(name, abbreviation, ru, f, options = {}, &block)
+      u = unit(name, {:abbreviation => abbreviation, :reference_units => {ru => 1}, :reference_factor => f}.merge(options))
       change_context({:unit => u}, block)
     end
 
     # Register a new unit in the current context that is composed of multiple units
     def combine(name, abbreviation, components, options = {}, &block)
-      u = unit(name, :abbreviation => abbreviation, :reference_factor => 1, :reference_unit => components)
-      dimension_metric.prefer(u, default_preferences(u).merge(options))
+      u = unit(name, {:abbreviation => abbreviation, :reference_factor => 1, :reference_units => components}.merge(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 unit(name, options = {})
       Unit.register(name, context.system, context.dimension, options)
     end
-
-    def dimension_metric
-      find_or_register_metric(self.class.dimension_default_metric_name(context.dimension), nil)
-    end
-    
-    # Basic preferences for formatting and parsing the given unit
-    def default_preferences(u)
-      o = {}
-      o[:format] = u.dimension.nil? ? "%s %U" : "%s%U"
-      o[:detector] = /\A#{[u.name, u.abbreviation].compact.join('|')}\Z/
-      o
-    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

@@ -8,8 +8,7 @@ module Dimensional
 
     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]
+      raise "Dimension #{d}'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
@@ -29,20 +28,37 @@ module Dimensional
       @symbol_registry.clear
     end
 
-    attr_reader :exponents, :name, :symbol
+    attr_reader :name, :symbol, :basis
 
-    def initialize(name, symbol = nil, exponents = {})
-      exponents.each_pair do |k,v|
+    def initialize(name, symbol = nil, basis = {})
+      basis.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?
+        raise "Invalid exponent for basis member #{v}" unless v.kind_of?(Integer)  # Can't this really be any Rational?
       end
-      @exponents = Hash.new(0).merge(exponents)
+      @basis = Hash.new(0).merge(basis)
       @name = name.to_s
       @symbol = symbol.nil? ? name.to_s.slice(0, 1).upcase : symbol.to_s
     end
     
     def fundamental?
-      exponents.empty?
+      basis.empty?
+    end
+    alias base? fundamental?
+
+    # Equality is determined by equality of value-ish attributes.  Specifically, equal basis for non-fundamental units
+    # and identicality for fundamental units.  The nil dimension is inherently un-equal to any non-nil dimension.
+    def ==(other)
+      other.kind_of?(self.class) && ((fundamental? && other.fundamental?) ? eql?(other) : other.basis == basis)
+    end
+
+    # Hashing collisions are desired when we have same identity-defining attributes.
+    def eql?(other)
+      other.kind_of?(self.class) && other.name.eql?(self.name)
+    end
+
+    # This is pretty lame, but the expected usage means we shouldn't get penalized
+    def hash
+      [self.class, name].hash
     end
 
     def to_s

data/lib/dimensional/metric.rb

@@ -1,64 +1,138 @@
-require 'dimensional/dimension'
+require 'dimensional/unit'
+require 'delegate'
 
 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
+  # TODO: Add a hierarchy that allows metrics to be built into a taxonomy by domain, like shipping, carpentry or sports
+  class Metric < 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|$)/
 
-    @registry = Hash.new
+    class << self
+      attr_accessor :dimension, :base, :default
 
-    attr_reader :name, :dimension, :parent
+      # The units applicable to this metric in priority order (highest priority first)
+      def units
+        @units ||= Unit.select{|u| u.dimension == dimension}.sort_by{|u| configuration[u][:preference]}.reverse
+      end
 
-    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
+      # Find the unit matching the given string, preferring units in the given system
+      def find_unit(str, system = nil)
+        system = System[system] unless system.kind_of?(System)
+        us = self.units.select{|u| configuration[u][:detector].match(str.to_s)}
+        us.detect{|u| u.system == system} || us.first
+      end
+
+      def configuration
+        @configuration ||= Hash.new do |h,u|
+          h[u] = {:detector => u.detector, :format => u.format, :preference => u.preference}
+        end
+      end
+
+      def configure(unit, options = {})
+        @dimension ||= unit.dimension
+        @base ||= unit
+        @default ||= unit
+        @units = nil
+        raise "Unit #{unit} is not compatible with dimension #{dimension || '<nil>'}." unless unit.dimension == dimension
+        configuration[unit] = {:detector => unit.detector, :format => unit.format, :preference => unit.preference * 1.01}.merge(options)
+      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]
+      # Parse a string into a Metric instance. Providing a unit system (or associated symbol) will prefer the units from that system.
+      # Unrecognized strings return nil.
+      def parse(str, system = nil)
+        system = System[system] unless system.kind_of?(System)
+        elements = str.to_s.scan(NUMERIC_REGEXP).map do |(v, us)|
+          unit = us.nil? ? default : find_unit(us, system)
+          raise ArgumentError, "Unit cannot be determined (#{us})" unless unit
+          system = unit.system # Set the system to restrict subsequent filtering
+          value = Integer(v) rescue Float(v)
+          new(value, unit)
+        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|
+          raise ArgumentError, "Inconsistent units in compound metric" unless t.unit.system == e.unit.system
+          converted_value = e.convert(t.unit)
+          new(t + converted_value, t.unit)
+        end
+      end
+
+      # Sort units by "best" fit for the desired order of magnitude.  Preference values offset OOM differences.
+      def best_fit(target_oom)
+        units.sort_by do |u|
+          oom_delta = (Math.log10(u.factor) - target_oom).abs
+          configuration[u][:preference] - oom_delta
+        end
+      end
     end
 
-    def self.reset!
-      @registry.clear
+    attr_reader :unit
+    def initialize(value, unit = self.class.default)
+      raise ArgumentError, "No default unit set" unless unit
+      @unit = unit
+      super(value)
     end
 
-    def initialize(name, dimension, parent = nil)
-      @name = name && name.to_s
-      @dimension = dimension
-      @units = {}
-      @parent = parent
+    # 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)
     end
-  
-    def prefer(unit, options = {})
-      raise "Unit #{unit} is not compatible with dimension #{dimension || '<nil>'}." unless unit.dimension == dimension
-      @units[unit] = options
+
+    # Convert this metric to the "most appropriate" unit in the given system.  A similar order-of-magnitude for the result is preferred.
+    def change_system(system)
+      system = System[system] unless system.kind_of?(System)
+      target_oom = Math.log10(self.unit.factor)
+      bu = self.class.best_fit(target_oom).select{|u| u.system == system}.last
+      convert(bu)
     end
 
-    def units
-      baseline = parent ? parent.units : @units.keys
-      baseline.sort_by{|u| [1.0 - preference(u), u.name, u.system]}
+    # Convert this metric to the "most appropriate" unit in the current system.  A resulting order of magnitude close to zero is preferred.
+    def preferred
+      target_oom = Math.log10(self) + Math.log10(self.unit.factor)
+      bu = self.class.best_fit(target_oom).select{|u| u.system == unit.system}.last
+      convert(bu)
     end
-  
-    def preferences(u)
-      baseline = parent ? parent.preferences(u) : {} 
-      baseline.merge(@units[u] || {})
+
+    # Return a new metric expressed in the base unit
+    def base
+      raise "No base unit defined" unless self.class.base
+      convert(self.class.base)
     end
-    
-    # How "preferred" is the given unit for this metric?
-    def preference(u)
-      @units.has_key?(u) ? 1 : 0
+
+    def to_s
+      strfmeasure(self.class.configuration[unit][:format])
     end
 
-    def each
-      units.each
+    # Like Date, Time and DateTime, Metric represents both a value and a context.  Like those built-in classes,
+    # Metric 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 modulo subordinate units with format hash -> {1 => "'", 12 => :inch} or {1 => "%d#", 16 => "%doz."}
+    def strfmeasure(format)
+      v = if (precision = self.class.configuration[unit][:precision])
+        # TODO: This precision could more usefully be converted to "signifigant digits"
+        pfactor = 10**(-precision)
+        ((self * pfactor).round / pfactor.to_f)
+      else
+        __getobj__ # We need the native value to prevent infinite recursion if the user specifies the %s specifier.
+      end
+      format = format.gsub(/%(#)?([\d.\-\*]*)U/) do |s|
+        us = ($1) ? unit.name : (unit.abbreviation || unit.name)
+        Kernel.sprintf("%#{$2}s", us)
+      end
+      count = format.scan(/(?:\A|[^%])(%[^% ]*[A-Za-z])/).size
+      Kernel.sprintf(format, *Array.new(count, v))
     end
 
-    def to_s
-      name || super
+    def inspect
+      strfmeasure("<%p <%#U>>")
     end
   end
 end