eymiha_units 0.1.0

data/lib/units/units.rb

@@ -0,0 +1,229 @@
+require 'eymiha'
+
+require 'forward_referencing'
+
+require 'units/units_measure'
+require 'units/units_exception'
+require 'units/numeric'
+require 'units/numeric_with_units'
+require 'units/units_hash'
+require 'units/object'
+
+# The Units framework
+#
+# Units is the top level that you'll typically never have to deal with
+# directly. While it provides a few chunks of general functionality such
+# as getting defined units and ranking, most of its guts are devoted to
+# defining new UnitsMeasures - unless you're setting up your own sets of
+# specialized units, you will hardly know it's here.
+class Units
+  
+  @@debug = false
+
+  def self.debug=(value)
+    @@debug = value
+  end
+
+  extend ForwardReferencing
+  start_forward_referencing
+
+  @@measures = {}
+  @@units = {}
+  @@defining = nil
+  @@holding = nil
+  
+  # Returns an Array of the defined UnitsMeasures.
+  def Units.units_measures
+    @@measures.keys
+  end
+  
+  # Creates or extends a UnitsMeasure.
+  def Units.create(name, &block)
+    measure = (@@measures[name.to_s] ||= UnitsMeasure.new)
+    block.call measure if block_given?
+    measure
+  end
+  
+  # Creates or extends a UnitsMeasure derived from other UnitsMeasures.
+  def Units.derive(name, target, &block)
+    measure = ( @@measures[name.to_s] =
+      if target.kind_of? UnitsMeasure
+        if target.derived && (derived = find_by_derivation target.derived)
+          derived
+        else
+          target
+        end
+      else
+        Units.create(target.to_s)
+      end )
+    block.call measure if block_given?
+    measure
+  end
+  
+  # Returns the UnitsMeasure with the given derivation.
+  def Units.find_by_derivation(derivation)
+    matches = @@measures.values.uniq.select { |measure|
+      if measure.derived
+        measure == derivation
+      elsif derivation.size == 1
+        a = derivation.to_a[0]
+        a[0] == measure and a[1] == 1
+      else
+        false
+      end
+    }
+    case matches.size
+      when 0 then nil
+      when 1 then matches[0]
+      else raise UnitsException.new(
+          "Multiple UnitsMeasures with same derivation found")
+    end
+  end
+  
+  # Removes the named UnitsMeasure from the Units framework.
+  def Units.delete(name)
+    @@measures.delete name.to_s
+  end
+  
+  # Clears the Units framework of all defined elements.
+  def Units.clear
+    @@measures.clear
+    @@units.clear
+    forward_references_clear
+    self
+  end
+  
+  # Returns the number of defined UnitsMeasures.
+  def Units.size
+    @@measures.size
+  end
+  
+  # Returns the named UnitsMeasure.
+  def Units.[](name)
+    @@measures[name.to_s]
+  end
+  
+  def Units.method_missing(method,*args) # :nodoc:
+    measure = self[method]
+    raise UnitsException.new("UnitsMeasure '#{method}' undefined") if !measure
+    measure
+  end
+  
+  # Returns an Array containing the names of a given UnitsMeasure.
+  def Units.names_of(units_measure)
+    @@measures.keys.select { |name| @@measures[name].equal? units_measure }
+  end
+
+  def Units.add_unit(unit,unit_identifier=nil) # :nodoc:
+    if unit_identifier
+      if (element = @@units[unit_identifier])
+        @@units[unit_identifier] += [ unit ] unless element.index(unit)
+      else
+        @@units[unit_identifier] = [ unit ]
+      end
+    else
+      add_unit unit, unit.name
+      add_unit unit, unit.plural
+      unit.abbrevs.each { |abbrev| add_unit unit, abbrev }
+    end
+  end
+  
+  # Returns an Array of UnitsUnit associated with a singular, plural or
+  # abbreviated name.
+  def Units.lookup(unit_identifier)
+    @@units[unit_identifier.to_s] || [ ]
+  end
+  
+  # Answers the question of whether a UnitsMeasure is being defined with the
+  # instance if true, or nil if false.
+  def Units.defining?
+    @@defining
+  end
+
+  def Units.defining(measure) # :nodoc:
+    @@defining = measure
+  end
+  
+  def Units.convert(numeric,unit_identifier) # :nodoc:
+    puts "Units:convert #{numeric} #{unit_identifier}" if @@debug
+    if (candidates = lookup(unit_identifier)).size == 0
+      puts @@units.keys.sort.join(" ") if @@debug
+      puts "  no candidates!" if @@debug
+      raise MissingUnitsException.new(unit_identifier.to_s)
+    elsif !defining?
+      if candidates.size > 1
+        raise AmbiguousUnitsException.new(unit_identifier.to_s)
+      else
+        unit = candidates[0]
+        NumericWithUnits.new(numeric,unit)
+      end
+    else
+      if candidates.size == 1
+        units = candidates
+      else
+        units = candidates.select { |candidate|
+          @@defining == candidate.units_system.units_measure }
+        units = candidates.select { |candidate|
+          @@defining.derived[candidate.units_measure] } if units.size == 0
+      end
+      case units.size
+        when 0 then
+          raise MissingUnitsException.new(unit_identifier.to_s)
+        when 1 then 
+          unit = units[0]
+	  if unit.equals.kind_of? Array
+	    element = unit.equals[0]
+	    value = NumericWithUnits.
+              new(numeric*element.numeric,element.unit)
+	  else
+	    value = NumericWithUnits.
+              new(numeric*unit.equals.numeric,unit.equals.unit)
+	  end
+          value.original = numeric.unite(unit)
+          value
+        else
+          raise AmbiguousUnitsException.new(unit_identifier.to_s)
+      end
+    end
+  end
+
+  def Units.make_forward_reference(method,context) # :nodoc:
+    @@holding ? nil : create_forward_reference(method,context)
+  end
+
+  def Units.release_forward_reference(reference = nil) # :nodoc:
+    remove_forward_reference(reference) if reference != nil
+  end
+
+  def Units.hold_forward_reference(hold = true) # :nodoc:
+    @@holding = hold
+  end
+  
+  def Units.holding_forward_reference? # :nodoc:
+    @@holding
+  end
+  
+  def Units.establish_forward_reference_context(context) # :nodoc:
+    defining context
+  end
+
+  # Given a Hash of units to raking weights, a set of samples, and
+  # optionally a block that returns rankings, returns an Array of units
+  # ordered by best weighted fit over the samples. Like golf, low scores
+  # rank best. In absence of a block, ranking is based on the number of
+  # unit values whose magnitudes are between 1 and 10.
+  def Units.rank(unit_choices = {}, samples = [], &numeric_ranker) # :yields: n
+    if block_given?
+      scores = {}
+      samples.each {|s|
+        unit_choices.each {|uc,w|
+          scores[uc] = (scores[uc] || 0) + w*(yield s.convert(uc).numeric) } }
+      scores.sort {|e1,e2| -(e1[1] <=> e2[1])}.collect {|s| s[0]}
+    else
+      rank(unit_choices,samples) { |n|
+        e = ((((n.abs)-5.5).abs-4.5).at_least(0))
+        (e == 0) ? 0 : (e == 1)? 0 : -(e + 1/(1-e)) }
+    end
+  end
+  
+end

data/lib/units/units_exception.rb

@@ -0,0 +1,14 @@
+# Raised when a general problem has occurred in the Units framework or some
+# other error has occurred during its use.
+class UnitsException < Exception
+end
+
+
+# Raised when a unit was expected but was not found.
+class MissingUnitsException < UnitsException
+end
+
+
+# Raised when a unit was expected but more than one was found.
+class AmbiguousUnitsException < UnitsException
+end

data/lib/units/units_hash.rb

@@ -0,0 +1,112 @@
+require "units/units"
+
+# The unit part of a NumericWithUnits is a UnitsHash - a Hash from UnitsUnit
+# instances to powers.
+class UnitsHash < Hash
+  
+  @@debug = false
+
+  def self.debug=(value)
+    @@debug = value
+  end
+
+  def initialize(unit = nil,power = 1) # :nodoc
+    if unit
+      if unit.kind_of? UnitsUnit
+        self[unit] = power
+      elsif unit.kind_of? UnitsHash
+        unit.each { |k,v| self[k] = v*power }
+      else
+        raise UnitsException.new("invalid unit: #{unit}")
+      end
+    end
+  end
+  
+  # Returns a String reprentation of the instance. If there is only one item in
+  # the UnitsHash, whole names are rendered; otherwise abbreviations are used.
+  def to_s(numeric = 1,use_abbrevs = false)
+    if size == 1 &&
+        (su = select {|k,v| v == 1}).size == 1 &&
+        !use_abbrevs
+      su = su.to_a[0][0]
+      ((numeric == 1)? su.name : su.plural).gsub(/_/,' ')
+    else
+      abbrevs_to_s
+    end
+  end
+  
+  def abbrevs_to_s # :nodoc:
+    p = select {|k,v| v > 0}.sort{|e1,e2| e1[1] <=> e2[1]}.collect {|e|
+      "#{e[0].abbrevs[0] || e[0].name}#{(e[1] == 1) ? "" : "^#{e[1]}"}"}
+    n = select {|k,v| v < 0}.sort{|e1,e2| e1[1] <=> e2[1]}.collect {|e|
+      "#{e[0].abbrevs[0] || e[0].name}#{(e[1] == -1) ? "" : "^#{-e[1]}"}"}
+    numerator = (p.size > 0)? p.join(" ") : (n.size > 0)? "1" : ""
+    denominator = (n.size > 0)? ((p.size > 0)? " / " : "/")+n.join(" ") : ""
+    "#{numerator}#{denominator}"
+  end
+  
+  # Raises and returns the instance after each of its exponents has been raised
+  # by the given power.
+  def power!(power)
+    self.each { |k,v| self[k] = v*power }
+  end
+
+  # Returns a new UnitsHash whose value is the instance raised to the given
+  # power.
+  def **(power)
+    clone.power!(power)
+  end
+
+  # Returns a new UnitsHash whose value is the instance's units and powers have
+  # been merged with the given value raised to the power.
+  def merge(value,power=1)
+    clone.merge!(value,power)
+  end
+  
+  # Merges and returns the instance after the value raised to the power has
+  # been merged into it.
+  def merge!(value,power=1)
+    value.unit.each { |k,v|
+      self[k] = (self[k] || 0) + v*power
+      delete k if self[k] == 0
+    }
+    self
+  end
+  
+  alias :* :merge
+
+  # Returns the UnitsMeasure of the instance if defined.
+  def measure
+    measure = UnitsMeasure.new
+    each { |unit,power|
+      measure.merge_derivation unit.units_system.units_measure => power }
+    Units.find_by_derivation(measure.derived)
+  end
+
+  # Returns true is any of the instance's components are derived.
+  def derived?
+    keys.select{|unit| unit.units_system.units_measure.derived != nil}.size > 0
+  end
+
+  # Return a NumericWithUnits that represents the instance when all derived
+  # units have been replaced with the units from which they derive.
+  def reduce
+    puts "UnitsHash:reduce #{to_s}" if @@debug
+    factor = 1.0
+    new_unit = UnitsHash.new
+    each do |unit,power|
+      puts "  #{unit} #{power}" if @@debug
+      factor *= unit.equals.numeric**power
+      puts "  #{factor}" if @@debug
+      new_unit.merge!(unit.equals,power)
+    end
+    factor.unite new_unit
+  end
+
+  # Return true if the instance is not equal to 1, ie. has at least one non-zero
+  # exponent.
+  def has_units?
+    (self.select {|k,v| v != 0.0}).size > 0
+  end
+
+end

data/lib/units/units_measure.rb

@@ -0,0 +1,91 @@
+require 'units/units_system'
+require 'methodic_hash'
+
+# A UnitsMeasure groups sets of units that measure the same quality.
+class UnitsMeasure < MethodicHash
+  
+  # A Hash of UnitsMeasures to powers that represent the bases for this
+  # UnitsMeasure if it is derived.
+  attr_reader :derived
+  attr_writer :derived # :nodoc:
+
+  # A Methodic Hash mapping names of formats to procs that implement them.
+  attr_reader :formats
+  
+  def initialize # :nodoc:
+    @formats = MethodicHash.new
+  end
+  
+  # Defines or extends a UnitsSystem. During definition, if forward
+  # references between entities may occur and when encountered, are stored.
+  # Upon completion of the definition, if any existing unresolved still
+  # exist, an attempt is made to resolve them.
+  def system(name,&block)
+    Units.defining self
+    system = (self[name] ||= UnitsSystem.new(self,name))
+    block.call system if block_given?
+    Units.resolve_forward_references
+    Units.defining nil
+    system
+  end
+
+  # Returns the names by which this UnitsMeasure is known.
+  def names
+    Units.names_of self
+  end
+
+  # Returns a new UnitsMeasure equal to the instance raised to the given
+  # power. This is typically used to derive UnitsMeasures - for example,
+  # if length is a UnitsMeasure, then length**3 could be used as the target
+  # to derive volume.
+  def **(exponent)
+    UnitsMeasure.new.merge_derivation(self => exponent)
+  end
+
+  # Returns a new UnitsMeasure equal to the instance divided by another
+  # UnitsMeasure. This is typically used to derive UnitsMeasures - for
+  # example, if mass and volume are UnitsMeasures, then mass/volume could be
+  # used as the target to derive density.
+  def /(divisor)
+    UnitsMeasure.new.merge_derivation(self).merge_derivation(divisor,-1)
+  end
+
+  # Returns a new UnitsMeasure equal to the instance multiplied by another
+  # UnitsMeasure. This is typically used to derive UnitsMeasures - for
+  # example, if length is a UnitsMeasure, then length*length could be
+  # used as the target to derive area.
+  def *(factor)
+    UnitsMeasure.new.merge_derivation(self).merge_derivation(factor)
+  end
+
+  def merge_derivation derivation, multiplier=1 # :nodoc:
+    current = (self.derived ||= {})
+    if derivation.kind_of? UnitsMeasure
+      if derivation.derived
+        derivation.derived.each {|key,value|
+          current[key] = (current[key] || 0) + multiplier*value } 
+      else
+        current[derivation] = (current[derivation] || 0) + multiplier
+      end
+    elsif derivation.kind_of? Hash
+      derivation.each {|key,value|
+        current[key] = ((current[key] || 0 ) + multiplier*value) }
+    else
+      raise UnitsException.new(
+         "Cannot add #{derivation.self_name} to derivation")
+    end
+    self
+  end
+  
+  # Returns a String containing the names of this UnitsMeasure and the
+  # namse of the UnitsSystems defined within it. 
+  def to_s
+    "#{self_name} #{names} #{keys}"
+  end
+
+  # Associates the name of a format with an output formatter.
+  def format(options)
+    @formats[options[:name]] = options[:format]
+  end
+  
+end

data/lib/units/units_system.rb

@@ -0,0 +1,85 @@
+require 'units/units_unit'
+require 'methodic_hash'
+
+# A UnitsSystem groups units that measure the same quality and are
+# conceptually organized together within a UnitsMeasure. Its a MethodicHash
+# of unit names to UnitsUnit instances.
+class UnitsSystem < MethodicHash
+  
+  # The UnitsMeasure to which this instance is associated.
+  attr_reader :units_measure
+  # The name of this UnitsSystem
+  attr_reader :name
+
+  def initialize(units_measure,name) # :nodoc:
+    @units_measure = units_measure
+    @name = name
+  end
+  
+  # Defines a new UnitsUnit. If ten-based or two-based greeking is defined,
+  # it is applied.
+  def unit(attributes)
+    unit = nil
+    if !Units.holding_forward_reference?
+      unit = UnitsUnit.new self, attributes
+      self[unit.name] = unit
+      Units.add_unit unit
+      case unit.greek
+        when :ten then greek_ten unit
+        when :two then greek_two unit
+      end
+    else
+      Units.hold_forward_reference nil
+    end
+    Units.continue_forward_reference_resolution
+    unit
+  end
+
+  # Associates the name of a format with an output formatter in the instance's
+  # UnitsMeasure.
+  def format(options)
+    @units_measure.format(options)
+  end
+  
+  def greek_ten(base) # :nodoc:
+    greek_unit base, "yocto", "y",  0.000000000000000000000001
+    greek_unit base, "zepto", "z",  0.000000000000000000001
+    greek_unit base, "atto",  "a",  0.000000000000000001
+    greek_unit base, "femto", "f",  0.000000000000001
+    greek_unit base, "pico",  "p",  0.000000000001
+    greek_unit base, "nano",  "n",  0.000000001
+    greek_unit base, "micro", "u",  0.000001
+    greek_unit base, "milli", "m",  0.001
+    greek_unit base, "centi", "c",  0.01
+    greek_unit base, "deci",  "d",  0.1
+    greek_unit base, "deca",  "da", 10.0
+    greek_unit base, "hecto", "h",  100.0
+    greek_unit base, "kilo",  "k",  1000.0
+    greek_unit base, "mega",  "M",  1000000.0
+    greek_unit base, "giga",  "G",  1000000000.0
+    greek_unit base, "tera",  "T",  1000000000000.0
+    greek_unit base, "peta",  "P",  1000000000000000.0
+    greek_unit base, "exa",   "E",  1000000000000000000.0
+    greek_unit base, "zetta", "Z",  1000000000000000000000.0
+    greek_unit base, "yotta", "Y",  1000000000000000000000000.0
+  end
+  
+  def greek_two(base) # :nodoc:
+    greek_unit base, "kilo",  "k", 2**10
+    greek_unit base, "mega",  "m", 2**20
+    greek_unit base, "giga",  "g", 2**30
+    greek_unit base, "tera",  "t", 2**40
+    greek_unit base, "peta",  "p", 2**50
+    greek_unit base, "exa",   "e", 2**60
+    greek_unit base, "zetta", "z", 2**70
+    greek_unit base, "yotta", "y", 2**80
+  end
+  
+  def greek_unit(base,prefix,abbrev_prefix,scalar) # :nodoc:
+    unit :name => prefix+base.name,
+         :plural => prefix+base.plural,
+         :abbrevs => base.abbrevs.collect { |abbrev| abbrev_prefix+abbrev },
+         :equals => base.equals * scalar
+  end
+  
+end

data/lib/units/units_unit.rb

@@ -0,0 +1,60 @@
+require 'methodic_hash'
+
+require 'units/numeric_with_units'
+
+# A unit in the context of a particular UnitsSystem. It's a MethodicHash of
+# its named qualities.
+class UnitsUnit < MethodicHash
+  
+  # The UnitsSystem to which this instance is associated.
+  attr_reader :units_system
+  
+  def initialize(units_system,attributes) # :nodoc:
+    @units_system = units_system
+    merge! attributes
+    normalize
+  end
+  
+  def ==(unit) # :nodoc:
+    self.equal? unit
+  end
+  
+  def normalize # :nodoc:
+    raise UnitsException.new("UnitUnits must have a name attribute") unless
+      self.name
+    self.name = self.name.to_s
+    add_plural
+    add_abbrevs
+    add_equals
+    equals.each { |n| n.promote_original } if equals.kind_of? Array
+    self
+  end
+  
+  def add_plural # :nodoc:
+    self.plural =
+      (self.no_plural == true) ? self.name :
+      (plural = self.plural) ? plural.to_s : self.name+'s'
+  end
+  
+  def add_abbrevs(attribute = nil) # :nodoc:
+    if attribute == nil
+      self.abbrevs = add_abbrevs(:abbrev)+add_abbrevs(:abbrevs)
+    elsif (value = self[attribute])
+      self.delete(attribute)
+      (value.kind_of? Array) ? value.collect {|e| e.to_s } : [ value.to_s ]
+    else
+      [ ]
+    end
+  end
+  
+  def add_equals # :nodoc:
+    self.equals = NumericWithUnits.new(1,self) unless self.equals
+  end
+  
+  # returns the UnitsMeasure containing the UnitsSystem to which this instance
+  # belongs.
+  def units_measure
+    units_system.units_measure
+  end
+  
+end

data/lib/units.rb

@@ -0,0 +1,4 @@
+# Adds the Units framework and a set of basic definitions.
+require 'units/units'
+require 'units/definitions/measures'
+

data/rakefile.rb

@@ -0,0 +1,2 @@
+require 'gem_package'
+require 'gem_raker'

data/test/framework.rb

@@ -0,0 +1,7 @@
+module UnitsTest
+  
+  def setup
+    Units.clear
+  end
+  
+end

data/test/tc_definitions.rb

@@ -0,0 +1,49 @@
+require 'test/unit'
+
+require 'units'
+
+class TC_definitions < Test::Unit::TestCase
+
+  def test_definitions
+
+    assert(Units.forward_references.size == 0)  # all the definitions loaded
+
+    t = 5.years
+    assert(t.to_s == "5 years")
+    assert(t.in_months.to_s == "60 months")
+    assert(t.in_months.in_days.to_s == "1800 days")
+    assert(t.in_days.to_s == "1825 days")
+    assert(t.in_days.in_months.to_s == "60.8333333333333 months")
+    assert(t.in_hours.to_s == "43800.0 hours")
+    assert(t.in_weeks.to_s == "260 weeks")
+    assert(t.in_months.in_weeks.to_s == "240 weeks")
+    assert(t.in_days.in_weeks.to_s == "260.714285714286 weeks")
+    assert(t.in_days == 260.weeks+5.days)
+
+    assert(days_in_january.to_s == "31.0")
+    assert(hours_in_january.to_s == "744.0")
+    assert(hours_per_january == 744)
+    assert(1.january.hours == 744.hours)
+    assert(january.hours == 744.hours)
+    assert(february.hours == 672.hours)
+    assert(july.weeks.to_s == "4.42857142857143 weeks")
+    assert(july.format(:weeks_and_days).to_s == "4 weeks 3 days")
+    assert(july.to_s(:weeks_and_days) == "4 weeks 3 days")
+
+    assert(speed_of_light.in_mi_s.to_s == "186282.024486427 mi / s")
+    assert(4.5.ly.in_mi.to_s == "26435654658917.8 miles")
+    assert(4.5.ly.AU.to_s == "284389.813364457 astronomical units")
+    assert(speed_of_light.miles.to_s == "186282.024486427 mi / s")
+    assert(speed_of_light.feet_nanosecond.to_s == "0.983569089288333 ft / ns")
+    assert(4.5.unite(["light_years"]).AU.to_s ==
+           "284389.813364457 astronomical units")
+    assert(4.5.light_years.AU.to_s == 
+           "284389.813364457 astronomical units")
+    assert(4.5.light_years.astronomical_units.to_s == 
+           "284389.813364457 astronomical units")
+    assert(1.speed_of_light.to_s == "1 speed of light")
+    assert(4.5.speed_of_light.to_s == "4.5 speed of light")
+
+  end
+    
+end

data/test/tc_formatting.rb

@@ -0,0 +1,41 @@
+require 'test/unit'
+require 'test/framework'
+
+require 'units'
+
+class TC_formatting < Test::Unit::TestCase
+  
+  understands UnitsTest
+
+  def test_fractions
+    
+    Units.create :length do |m|
+      m.system :english do |s|
+        s.unit :name => :inch, :plural => :inches, :abbrev => :in
+        s.unit :name => :foot, :plural => :feet, :abbrev => :ft,
+               :equals => 12.inches
+        s.unit :name => :yard, :abbrevs => :yd, :equals => 3.feet
+        s.unit :name => :mile, :abbrevs => :mi, :equals => 1760.yards
+        s.format :name => :feet_inches_and_32s,
+                 :format => lambda { |u|
+                                     ru = u.inch.round_to_nearest 32
+                                     feet = ru.feet.floor
+                                     inches = (ru-feet).inches
+                                     "#{feet} #{inches.with_fraction 32}" }
+      end
+    end
+
+    l = 13.28090635.ft
+    assert(l.measure == Units.length)
+    assert(3.46875.with_fraction(32) == "3-15/32")
+    assert(l.format(:feet_inches_and_32s) == "13 feet 3-12/32 inches")
+     
+    almost = 1.999.ft
+    assert(almost.inch.round_to_nearest(32) == 24.0.in)
+
+    almost = 1.996.ft
+    assert(almost.inch.round_to_nearest(32) == 23.9375.in)
+
+  end
+
+end