unitwise-193 1.0.4

data/lib/unitwise/expression/composer.rb

@@ -0,0 +1,41 @@
+module Unitwise
+  module Expression
+    # Composer creates string expressions for arrays of terms, following
+    # UCUM's conventions.
+    class Composer
+      attr_reader :terms, :mode
+      def initialize(terms, mode)
+        @terms  = terms
+        @mode = mode || :primary_code
+      end
+
+      def set
+        @set ||= terms.reduce(SignedMultiset.new) do |s, t|
+          identifier = { :f => t.factor,
+                         :p => (t.prefix.to_s(mode) if t.prefix),
+                         :a => (t.atom.to_s(mode) if t.atom) }
+          s.increment(identifier, t.exponent); s
+        end
+      end
+
+      def numerator
+        @numerator ||= set.select{ |_, v| v > 0 }.map do |k, v|
+          "#{ k[:f] if k[:f] != 1 }#{ k[:p] }#{ k[:a] }#{ v if v != 1 }"
+        end.select { |t| !t.empty? }.join('.')
+      end
+
+      def denominator
+        @denominator ||= set.select{ |_, v| v < 0 }.map do |k, v|
+          "#{ k[:f] if k[:f] != 1 }#{ k[:p] }#{ k[:a] }#{ -v if v != -1 }"
+        end.select { |t| !t.empty? }.join('.')
+      end
+
+      def expression
+        @expression = []
+        @expression << (numerator.empty? ? '1' : numerator)
+        (@expression << denominator) unless denominator.empty?
+        @expression.join('/')
+      end
+    end
+  end
+end

data/lib/unitwise/expression/decomposer.rb

@@ -0,0 +1,68 @@
+module Unitwise
+  module Expression
+    # The decomposer is used to turn string expressions into collections of
+    # terms. It is responsible for executing the parsing and transformation
+    # of a string, as well as caching the results.
+    class Decomposer
+
+      MODES = [:primary_code, :secondary_code, :names, :slugs, :symbol]
+
+      PARSERS = MODES.reduce({}) do |hash, mode|
+        hash[mode] = Parser.new(mode); hash
+      end
+
+      TRANSFORMER = Transformer.new
+
+      class << self
+
+        # Parse an expression to an array of terms and cache the results
+        def parse(expression)
+          expression = expression.to_s
+          if cache.key?(expression)
+            cache[expression]
+          elsif decomposer = new(expression)
+            cache[expression] = decomposer
+          end
+        end
+
+        private
+
+        # A simple cache to prevent re-decomposing the same units
+        # api private
+        def cache
+          @cache ||= {}
+        end
+      end
+
+      attr_reader :expression, :mode
+
+      def initialize(expression)
+        @expression = expression.to_s
+        if expression.empty? || terms.nil? || terms.empty?
+          fail(ExpressionError, "Could not evaluate '#{ expression }'.")
+        end
+      end
+
+      def parse
+        PARSERS.reduce(nil) do |_, (mode, parser)|
+          parsed = parser.parse(expression) rescue next
+          @mode = mode
+          break parsed
+        end
+      end
+
+      def transform
+        @transform ||= TRANSFORMER.apply(parse, :mode => mode)
+      end
+
+      def terms
+        @terms ||= if transform.respond_to?(:terms)
+          transform.terms
+        else
+          Array(transform)
+        end
+      end
+
+    end
+  end
+end

data/lib/unitwise/expression/matcher.rb

@@ -0,0 +1,47 @@
+module Unitwise
+  module Expression
+    # Matcher is responsible for building up Parslet alternatives of atoms and
+    # prefixes to be used by Unitwise::Expression::Parser.
+    class Matcher
+      class << self
+        def atom(mode)
+          @atom ||= {}
+          @atom[mode] ||= new(Atom.all, mode).alternative
+        end
+
+        def metric_atom(mode)
+          @metric_atom ||= {}
+          @metric_atom[mode] ||=
+            new(Atom.all.select(&:metric?), mode).alternative
+        end
+
+        def prefix(mode)
+          @prefix ||= {}
+          @prefix[mode] ||= new(Prefix.all, mode).alternative
+        end
+      end
+
+      attr_reader :collection, :mode
+
+      def initialize(collection, mode = :primary_code)
+        @collection = collection
+        @mode = mode
+      end
+
+      def strings
+        collection.map(&mode).flatten.compact.sort do |x, y|
+          y.length <=> x.length
+        end
+      end
+
+      def matchers
+        strings.map { |s| Parslet::Atoms::Str.new(s) }
+      end
+
+      def alternative
+        Parslet::Atoms::Alternative.new(*matchers)
+      end
+
+    end
+  end
+end

data/lib/unitwise/expression/parser.rb

@@ -0,0 +1,58 @@
+module Unitwise
+  module Expression
+    # Parses a string expression into a hash tree representing the
+    # expression's terms, prefixes, and atoms.
+    class Parser < Parslet::Parser
+      attr_reader :key
+      def initialize(key = :primary_code)
+        @key = key
+      end
+
+      root :expression
+
+      rule (:atom) { Matcher.atom(key).as(:atom_code) }
+      rule (:metric_atom) { Matcher.metric_atom(key).as(:atom_code) }
+      rule (:prefix) { Matcher.prefix(key).as(:prefix_code) }
+
+      rule (:simpleton) do
+        (prefix.as(:prefix) >> metric_atom.as(:atom) | atom.as(:atom))
+      end
+
+      rule (:annotation) do
+        str('{') >> match['^}'].repeat.as(:annotation) >> str('}')
+      end
+
+      rule (:digits) { match['0-9'].repeat(1) }
+
+      rule (:integer) { (str('-').maybe >> digits).as(:integer) }
+
+      rule (:fixnum) do
+        (str('-').maybe >> digits >> str('.') >> digits).as(:fixnum)
+      end
+
+      rule (:number) { fixnum | integer }
+
+      rule (:exponent) { integer.as(:exponent) }
+
+      rule (:factor) { number.as(:factor) }
+
+      rule (:operator) { (str('.') | str('/')).as(:operator) }
+
+      rule (:term) do
+        ((factor >> simpleton | simpleton | factor) >>
+          exponent.maybe >> annotation.maybe).as(:term)
+      end
+
+      rule (:group) do
+        (factor.maybe >> str('(') >> expression.as(:nested) >> str(')') >>
+          exponent.maybe).as(:group)
+      end
+
+      rule (:expression) do
+        ((group | term).as(:left)).maybe >>
+          (operator >> expression.as(:right)).maybe
+      end
+
+    end
+  end
+end

data/lib/unitwise/expression/transformer.rb

@@ -0,0 +1,37 @@
+module Unitwise
+  module Expression
+    # Transformer is responsible for turning a Unitwise::Expression::Parser
+    # hash result into a collection of Unitwise::Terms.
+    class Transformer < Parslet::Transform
+
+      rule(:integer => simple(:i)) { i.to_i }
+      rule(:fixnum => simple(:f)) { f.to_f }
+
+      rule(:prefix_code => simple(:c)) { |x| Prefix.find(x[:c], x[:mode]) }
+      rule(:atom_code => simple(:c))   { |x| Atom.find(x[:c], x[:mode]) }
+      rule(:term => subtree(:h))       { Term.new(h) }
+
+      rule(:operator => simple(:o), :right => simple(:r)) do
+        o == '/' ? r ** -1 : r
+      end
+
+      rule(:left => simple(:l), :operator => simple(:o),
+            :right => simple(:r)) do
+        o == '/' ? l / r : l * r
+      end
+
+      rule(:left => simple(:l)) { l }
+
+      rule(:group => { :factor => simple(:f),
+            :nested => simple(:n), :exponent => simple(:e) }) do
+        (n ** e) * f
+      end
+
+      rule(:group => { :nested => simple(:n) , :exponent => simple(:e) }) do
+        n ** e
+      end
+
+      rule(:group => { :nested => simple(:n) }) { n }
+    end
+  end
+end

data/lib/unitwise/ext.rb

@@ -0,0 +1,2 @@
+require 'unitwise'
+require 'unitwise/ext/numeric'

data/lib/unitwise/ext/numeric.rb

@@ -0,0 +1,45 @@
+# Unitwise extends Numeric to add these dyanmic method conveniences: `1.meter`,
+# `26.2.to_mile`, and `4.convert_to("Joule")`. These overrides are optional due
+# to their controversial nature. `require 'unitwise/ext'` to enable them.
+class Numeric
+  # Converts numeric to a measurement
+  # @param unit [Unitwise::Unit, String] The unit to use in the measurement
+  # @return [Unitwise::Measurement]
+  # @example
+  #   26.2.convert_to('mile') # => #<Unitwise::Measurement 1 mile>
+  # @api public
+  def convert_to(unit)
+    Unitwise::Measurement.new(self, unit)
+  end
+
+  # Converts numeric to a measurement by the method name
+  # @example
+  #   26.2.mile # => #<Unitwise::Measurement 26.2 mile>
+  #   100.to_foot # => #<Unitwise::Measurement 100 foot>
+  # @api semipublic
+  def method_missing(meth, *args, &block)
+    if args.empty? && !block_given?
+      unit = (match = /\Ato_(\w+)\Z/.match(meth.to_s)) ? match[1] : meth
+      converted = begin
+        convert_to(unit)
+      rescue Unitwise::ExpressionError
+        nil
+      end
+    end
+    if converted
+      Numeric.define_unit_conversion_methods_for(unit)
+      converted
+    else
+      super(meth, *args, &block)
+    end
+  end
+
+  def self.define_unit_conversion_methods_for(name)
+    [name.to_sym, "to_#{ name }".to_sym].each do |meth|
+      next if method_defined?(meth)
+      define_method meth do
+        convert_to(name)
+      end
+    end
+  end
+end

data/lib/unitwise/functional.rb

@@ -0,0 +1,117 @@
+module Unitwise
+  # Functional is an alterative function-based scale for atoms with a
+  # non-linear (or non-zero y-intercept) scale. This is most commonly used for
+  # temperatures. Known functions for converting to and from special atoms
+  # are setup as class methods here.
+  class Functional < Scale
+    extend Math
+
+    def self.to_cel(x)
+      x - 273.15
+    end
+
+    def self.from_cel(x)
+      x + 273.15
+    end
+
+    def self.to_degf(x)
+      9.0 * x / 5.0 - 459.67
+    end
+
+    def self.from_degf(x)
+      5.0 / 9.0 * (x + 459.67)
+    end
+
+    def self.to_hpX(x)
+      -log10(x)
+    end
+
+    def self.from_hpX(x)
+      10.0 ** -x
+    end
+
+    def self.to_hpC(x)
+      -log(x) / log(100.0)
+    end
+
+    def self.from_hpC(x)
+      100.0 ** -x
+    end
+
+    def self.to_tan100(x)
+      100.0 * tan(x)
+    end
+
+    def self.from_tan100(x)
+      atan(x / 100.0)
+    end
+
+    def self.to_ph(x)
+      to_hpX(x)
+    end
+
+    def self.from_ph(x)
+      from_hpX(x)
+    end
+
+    def self.to_ld(x)
+      Math.log(x) / Math.log(2.0)
+    end
+
+    def self.from_ld(x)
+      2.0 ** x
+    end
+
+    def self.to_ln(x)
+      log(x)
+    end
+
+    def self.from_ln(x)
+      Math::E ** x
+    end
+
+    def self.to_lg(x)
+      log10(x)
+    end
+
+    def self.from_lg(x)
+      10.0 ** x
+    end
+
+    def self.to_2lg(x)
+      2.0 * log10(x)
+    end
+
+    def self.from_2lg(x)
+      10.0 ** (x / 2.0)
+    end
+
+    attr_reader :function_name
+
+    # Setup a new functional.
+    # @param value [Numeric] The magnitude of the scale
+    # @param unit [Unitwise::Unit, String] The unit of the scale
+    # @param function_name [String, Symbol] One of the class methods above to be
+    # used for conversion
+    def initialize(value, unit, function_name)
+      @function_name = function_name
+      super(value, unit)
+    end
+
+    # Get the equivalent scalar value of a magnitude on this scale
+    # @param magnitude [Numeric] The magnitude to find the scalar value for
+    # @return [Numeric] Equivalent linear scalar value
+    # @api public
+    def scalar(magnitude = value)
+      self.class.send(:"from_#{function_name}", magnitude)
+    end
+
+    # Get the equivalent magnitude on this scale for a scalar value
+    # @param scalar [Numeric] A linear scalar value
+    # @return [Numeric] The equivalent magnitude on this scale
+    # @api public
+    def magnitude(scalar = scalar())
+      self.class.send(:"to_#{function_name}", scalar)
+    end
+  end
+end

data/lib/unitwise/measurement.rb

@@ -0,0 +1,198 @@
+module Unitwise
+  # A Measurement is a combination of a numeric value and a unit. You can think
+  # of this as a type of vector where the direction is the unit designation and
+  # the value is the magnitude. This is the primary class that outside code
+  # will interact with. Comes with conversion, comparison, and math methods.
+  class Measurement < Scale
+    # Create a new Measurement
+    # @param value [Numeric] The scalar value for the measurement
+    # @param unit  [String, Measurement::Unit] Either a string expression, or a
+    # Measurement::Unit
+    # @example
+    #   Unitwise::Measurement.new(20, 'm/s')
+    # @api public
+    def initialize(*args)
+      super(*args)
+      terms
+    end
+
+    # Convert this measurement to a compatible unit.
+    # @param other_unit [String, Measurement::Unit] Either a string expression
+    # or a Measurement::Unit
+    # @example
+    #   measurement1.convert_to('foot')
+    #   measurement2.convert_to('kilogram')
+    # @api public
+    def convert_to(other_unit)
+      other_unit = Unit.new(other_unit)
+      if compatible_with?(other_unit)
+        new(converted_value(other_unit), other_unit)
+      else
+        fail ConversionError, "Can't convert #{self} to #{other_unit}."
+      end
+    end
+
+    # Multiply this measurement by a number or another measurement
+    # @param other [Numeric, Unitwise::Measurement]
+    # @example
+    #   measurent * 5
+    #   measurement * some_other_measurement
+    # @api public
+    def *(other)
+      operate(:*, other) ||
+        fail(TypeError, "Can't multiply #{self} by #{other}.")
+    end
+
+    # Divide this measurement by a number or another measurement
+    # @param (see #*)
+    # @example
+    #   measurement / 2
+    #   measurement / some_other_measurement
+    # @api public
+    def /(other)
+      operate(:/, other) || fail(TypeError, "Can't divide #{self} by #{other}")
+    end
+
+    # Add another measurement to this unit. Units must be compatible.
+    # @param other [Unitwise::Measurement]
+    # @example
+    #   measurement + some_other_measurement
+    # @api public
+    def +(other)
+      combine(:+, other) || fail(TypeError, "Can't add #{other} to #{self}.")
+    end
+
+    # Subtract another measurement from this unit. Units must be compatible.
+    # @param (see #+)
+    # @example
+    #   measurement - some_other_measurement
+    # @api public
+    def -(other)
+      combine(:-, other) ||
+        fail(TypeError, "Can't subtract #{other} from #{self}.")
+    end
+
+    # Raise a measurement to a numeric power.
+    # @param number [Numeric]
+    # @example
+    #   measurement ** 2
+    # @api public
+    def **(other)
+      if other.is_a?(Numeric)
+        new(value ** other, unit ** other)
+      else
+        fail TypeError, "Can't raise #{self} to #{other} power."
+      end
+    end
+
+    # Round the measurement value. Delegates to the value's class.
+    # @return [Integer, Float]
+    # @api public
+    def round(digits = nil)
+      rounded_value = digits ? value.round(digits) : value.round
+      self.class.new(rounded_value, unit)
+    end
+
+    # Coerce a numeric to a a measurement for mathematical operations
+    # @param other [Numeric]
+    # @example
+    #   2.5 * measurement
+    #   4 / measurement
+    # @api public
+    def coerce(other)
+      case other
+      when Numeric
+        return self.class.new(other, '1'), self
+      else
+        fail TypeError, "#{self.class} can't be coerced into #{other.class}"
+      end
+    end
+
+    # Convert a measurement to an Integer.
+    # @example
+    #   measurement.to_i # => 4
+    # @api public
+    def to_i
+      Integer(value)
+    end
+
+    # Convert a measurement to a Float.
+    # @example
+    #   measurement.to_f # => 4.25
+    # @api public
+    def to_f
+      Float(value)
+    end
+
+    # Convert a measurement to a Rational.
+    # @example
+    #   measurement.to_r # => (17/4)
+    # @api public
+    def to_r
+      Rational(value)
+    end
+
+    # Will attempt to convert to a unit by method name.
+    # @example
+    #   measurement.to_foot # => <Unitwise::Measurement 4 foot>
+    # @api semipublic
+    def method_missing(meth, *args, &block)
+      if args.empty? && !block_given? && (match = /\Ato_(\w+)\Z/.match(meth.to_s))
+        begin
+          convert_to(match[1])
+        rescue ExpressionError
+          super(meth, *args, &block)
+        end
+      else
+        super(meth, *args, &block)
+      end
+    end
+
+    private
+
+    # Helper method to create a new instance from this instance
+    # @api private
+    def new(*args)
+      self.class.new(*args)
+    end
+
+    # Set the value for the measurement.
+    # @api private
+    attr_writer :value
+
+    # Determine value of the unit after conversion to another unit
+    # @api private
+    def converted_value(other_unit)
+      if other_unit.special?
+        other_unit.magnitude scalar
+      else
+        scalar / other_unit.scalar
+      end
+    end
+
+    # Add or subtract other unit
+    # @api private
+    def combine(operator, other)
+      if other.respond_to?(:composition) && compatible_with?(other)
+        new(value.send(operator, other.convert_to(unit).value), unit)
+      end
+    end
+
+    # Multiply or divide other unit
+    # @api private
+    def operate(operator, other)
+      if other.is_a?(Numeric)
+        new(value.send(operator, other), unit)
+      elsif other.respond_to?(:composition)
+        if compatible_with?(other)
+          converted = other.convert_to(unit)
+          new(value.send(operator, converted.value),
+              unit.send(operator, converted.unit))
+        else
+          new(value.send(operator, other.value),
+              unit.send(operator, other.unit))
+        end
+      end
+    end
+  end
+end