unitwise-193 1.0.4

data/data/prefix.yaml

@@ -0,0 +1,121 @@
+---
+- :names: yotta
+  :symbol: Y
+  :primary_code: Y
+  :secondary_code: YA
+  :scalar: 1e24
+- :names: zetta
+  :symbol: Z
+  :primary_code: Z
+  :secondary_code: ZA
+  :scalar: 1e21
+- :names: exa
+  :symbol: E
+  :primary_code: E
+  :secondary_code: EX
+  :scalar: 1e18
+- :names: peta
+  :symbol: P
+  :primary_code: P
+  :secondary_code: PT
+  :scalar: 1e15
+- :names: tera
+  :symbol: T
+  :primary_code: T
+  :secondary_code: TR
+  :scalar: 1e12
+- :names: giga
+  :symbol: G
+  :primary_code: G
+  :secondary_code: GA
+  :scalar: 1e9
+- :names: mega
+  :symbol: M
+  :primary_code: M
+  :secondary_code: MA
+  :scalar: 1e6
+- :names: kilo
+  :symbol: k
+  :primary_code: k
+  :secondary_code: K
+  :scalar: 1e3
+- :names: hecto
+  :symbol: h
+  :primary_code: h
+  :secondary_code: H
+  :scalar: 1e2
+- :names: deka
+  :symbol: da
+  :primary_code: da
+  :secondary_code: DA
+  :scalar: 1e1
+- :names: deci
+  :symbol: d
+  :primary_code: d
+  :secondary_code: D
+  :scalar: 1e-1
+- :names: centi
+  :symbol: c
+  :primary_code: c
+  :secondary_code: C
+  :scalar: 1e-2
+- :names: milli
+  :symbol: m
+  :primary_code: m
+  :secondary_code: M
+  :scalar: 1e-3
+- :names: micro
+  :symbol: "μ"
+  :primary_code: u
+  :secondary_code: U
+  :scalar: 1e-6
+- :names: nano
+  :symbol: n
+  :primary_code: n
+  :secondary_code: N
+  :scalar: 1e-9
+- :names: pico
+  :symbol: p
+  :primary_code: p
+  :secondary_code: P
+  :scalar: 1e-12
+- :names: femto
+  :symbol: f
+  :primary_code: f
+  :secondary_code: F
+  :scalar: 1e-15
+- :names: atto
+  :symbol: a
+  :primary_code: a
+  :secondary_code: A
+  :scalar: 1e-18
+- :names: zepto
+  :symbol: z
+  :primary_code: z
+  :secondary_code: ZO
+  :scalar: 1e-21
+- :names: yocto
+  :symbol: y
+  :primary_code: y
+  :secondary_code: YO
+  :scalar: 1e-24
+- :names: kibi
+  :symbol: Ki
+  :primary_code: Ki
+  :secondary_code: KIB
+  :scalar: '1024'
+- :names: mebi
+  :symbol: Mi
+  :primary_code: Mi
+  :secondary_code: MIB
+  :scalar: '1048576'
+- :names: gibi
+  :symbol: Gi
+  :primary_code: Gi
+  :secondary_code: GIB
+  :scalar: '1073741824'
+- :names: tebi
+  :symbol: Ti
+  :primary_code: Ti
+  :secondary_code: TIB
+  :scalar: '1099511627776'

data/lib/unitwise.rb

@@ -0,0 +1,70 @@
+require 'liner'
+require 'memoizable'
+require 'parslet'
+require 'signed_multiset'
+require 'yaml'
+require 'bigdecimal'
+
+require 'unitwise/version'
+require 'unitwise/base'
+require 'unitwise/compatible'
+require 'unitwise/expression'
+require 'unitwise/scale'
+require 'unitwise/functional'
+require 'unitwise/measurement'
+require 'unitwise/atom'
+require 'unitwise/prefix'
+require 'unitwise/term'
+require 'unitwise/unit'
+require 'unitwise/search'
+require 'unitwise/errors'
+
+# Unitwise is a library for performing mathematical operations and conversions
+# on all units defined by the [Unified Code for Units of Measure(UCUM).
+module Unitwise
+
+  # Search for available compounds. This is just a helper method for
+  # convenience
+  # @param term [String, Regexp]
+  # @return [Array]
+  # @api public
+  def self.search(term)
+    Search.search(term)
+  end
+
+  # Determine if a given string is a valid unit expression
+  # @param expression [String]
+  # @return [true, false]
+  # @api public
+  def self.valid?(expression)
+    begin
+      !!Unitwise::Expression.decompose(expression)
+    rescue ExpressionError
+      false
+    end
+  end
+  
+  # The system path for the installed gem
+  # @api private
+  def self.path
+    @path ||= File.dirname(File.dirname(__FILE__))
+  end
+
+  # A helper to get the location of a yaml data file
+  # @api private
+  def self.data_file(key)
+    File.join path, 'data', "#{key}.yaml"
+  end
+end
+
+# Measurement initializer shorthand. Use this to instantiate new measurements.
+# @param first [Numeric, String] Either a numeric value or a unit expression
+# @param last [String, Nil] Either a unit expression, or nil
+# @return [Unitwise::Measurement]
+# @example
+#   Unitwise(20, 'mile') # => #<Unitwise::Measurement 20 mile>
+#   Unitwise('km') # => #<Unitwise::Measurement 1 km>
+# @api public
+def Unitwise(*args)
+  Unitwise::Measurement.new(*args)
+end

data/lib/unitwise/atom.rb

@@ -0,0 +1,121 @@
+module Unitwise
+  # Atoms are the most basic elements in Unitwise. They are named coded and
+  # scaled units without prefixes, multipliers, exponents, etc. Examples are
+  # 'meter', 'hour', 'pound force'.
+  class Atom < Base
+    liner :classification, :property, :metric, :special, :arbitrary, :dim
+    include Compatible
+
+    class << self
+      # Array of hashes representing atom properties.
+      # @api private
+      def data
+        @data ||= data_files.map { |file| YAML.load(File.open file) }.flatten
+      end
+
+      # Data files containing atom data
+      # @api private
+      def data_files
+        %w(base_unit derived_unit).map { |type| Unitwise.data_file type }
+      end
+    end
+
+    # Determine if an atom is base level. All atoms that are not base are
+    # defined directly or indirectly in reference to a base atom.
+    # @return [true, false]
+    # @api public
+    def base?
+      !!(@dim && !scale)
+    end
+
+    # Determine if an atom is derived. Derived atoms are defined with respect
+    # to other atoms.
+    # @return [true, false]
+    # @api public
+    def derived?
+      !base?
+    end
+
+    # Determine if an atom is metric. Metric atoms can be combined with metric
+    # prefixes.
+    # @return [true, false]
+    # @api public
+    def metric
+      base? ? true : !!@metric
+    end
+    alias_method :metric?, :metric
+
+    # Determine if a unit is special. Special atoms are not defined on a
+    # traditional ratio scale.
+    # @return [true, false]
+    # @api public
+    def special
+      !!@special
+    end
+    alias_method :special?, :special
+
+    # Determine if a unit is arbitrary. Arbitrary atoms are not of any specific
+    # dimension and have no general meaning, therefore cannot be compared with
+    # any other unit.
+    # @return [true, false]
+    # @api public
+    def arbitrary
+      !!@arbitrary
+    end
+    alias_method :arbitrary?, :arbitrary
+
+    # Determine how far away a unit is from a base unit.
+    # @return [Integer]
+    # @api public
+    def depth
+      base? ? 0 : scale.depth + 1
+    end
+    memoize :depth
+
+    # Determine if this is the last atom in the scale chain
+    # @return [true, false]
+    # @api public
+    def terminal?
+      depth <= 3
+    end
+
+    # A representation of an atoms composition. Used to determine if two
+    # different atoms are compatible.
+    # @return [String]
+    # @api public
+    def dim
+      terminal? ? @dim || property : composition_string
+    end
+
+    # Set the atom's scale. It can be set as a Scale or a Functional
+    # @return [Unitwise::Functional, Unitwise::Scale]
+    # @api public
+    def scale=(attrs)
+      @scale = if attrs[:function_code]
+        Functional.new(attrs[:value], attrs[:unit_code], attrs[:function_code])
+      else
+        Scale.new(attrs[:value], attrs[:unit_code])
+      end
+    end
+
+    # Get a numeric value that can be used to with other atoms to compare with
+    # or operate on. Base units have a scalar of 1.
+    # @return [Numeric]
+    # @api public
+    def scalar(magnitude = 1)
+      base? ? BigDecimal(magnitude.to_s) : scale.scalar(magnitude)
+    end
+
+    def magnitude(scalar = scalar())
+      special? ? scale.magnitude(scalar) : BigDecimal('1')
+    end
+
+    # An atom may have a complex scale with several base atoms at various
+    # depths. This method returns all of this atoms base level terms.
+    # @return [Array] An array containing base Unitwise::Term
+    def root_terms
+      base? ? [Term.new(:atom_code => primary_code)] : scale.root_terms
+    end
+    memoize :root_terms
+  end
+end

data/lib/unitwise/base.rb

@@ -0,0 +1,58 @@
+module Unitwise
+  # The base class that Atom and Prefix are extended from. This class provides
+  # shared functionality for said classes.
+  class Base
+    liner :names, :primary_code, :secondary_code, :symbol, :scale
+    include Memoizable
+
+    # The list of tracked items.
+    # @return [Array] An array of memoized instances.
+    # @api public
+    def self.all
+      @all ||= data.map { |d| new d }
+    end
+
+    # Find a matching instance by a specified attribute.
+    # @param string [String] The search term
+    # @param method [Symbol] The attribute to search by
+    # @return The first matching instance
+    # @example
+    #   Unitwise::Atom.find('m')
+    # @api public
+    def self.find(string, method = :primary_code)
+      all.find do |i|
+        key = i.send(method)
+        if key.is_a? Array
+          key.include?(string)
+        else
+          key == string
+        end
+      end
+    end
+
+    # Setter for the names attribute. Will always set as an array.
+    # @api semipublic
+    def names=(names)
+      @names = Array(names)
+    end
+
+    # A set of method friendly names.
+    # @return [Array] An array of strings
+    # @api semipublic
+    def slugs
+      names.map do |n|
+        n.downcase.strip.gsub(/\s/, '_').gsub(/\W/, '')
+      end
+    end
+    memoize :slugs
+
+    # String representation for the instance.
+    # @param mode [symbol] The attribute to for stringification
+    # @return [String]
+    # @api public
+    def to_s(mode = :primary_code)
+      res = send(mode)
+      res.respond_to?(:each) ? res.first.to_s : res.to_s
+    end
+  end
+end

data/lib/unitwise/compatible.rb

@@ -0,0 +1,60 @@
+module Unitwise
+  # Compatible is used to establish compatibility between units, terms, or
+  # measurements. This is done by determining the objects atomic composition
+  # represented as a Signed Multiset.
+  module Compatible
+    # @api private
+    def self.included(base)
+      base.send :include, Comparable
+      base.send :include, Memoizable unless base < Memoizable
+      base.send :memoize, :composition, :composition_string
+    end
+
+    def initialize(*args)
+      super(*args)
+      freeze
+    end
+
+    # A representation of a unit based on the atoms it's derived from.
+    # @return [SignedMultiset]
+    # @api public
+    def composition
+      root_terms.reduce(SignedMultiset.new) do |s, t|
+        s.increment(t.atom.dim, t.exponent) if t.atom
+        s
+      end
+    end
+
+    # Define a default #dim for included classes.
+    # @return [String]
+    # @api public
+    def dim
+      composition_string
+    end
+
+    # A string representation of a unit based on the atoms it's derived from
+    # @return [String]
+    # @api public
+    def composition_string
+      composition.sort.map do |k, v|
+        v == 1 ? k.to_s : "#{k}#{v}"
+      end.join('.')
+    end
+
+    # Determine if this instance is similar to or compatible with other
+    # @return [true false]
+    # @api public
+    def compatible_with?(other)
+      composition == other.composition
+    end
+
+    # Compare whether the instance is greater, less than or equal to other.
+    # @return [-1 0 1]
+    # @api public
+    def <=>(other)
+      if other.respond_to?(:composition) && compatible_with?(other)
+        scalar <=> other.scalar
+      end
+    end
+  end
+end

data/lib/unitwise/errors.rb

@@ -0,0 +1,7 @@
+module Unitwise
+  class ExpressionError < Exception
+  end
+
+  class ConversionError < Exception
+  end
+end

data/lib/unitwise/expression.rb

@@ -0,0 +1,35 @@
+require 'unitwise/expression/matcher'
+require 'unitwise/expression/parser'
+require 'unitwise/expression/transformer'
+require 'unitwise/expression/composer'
+require 'unitwise/expression/decomposer'
+
+module Unitwise
+  # The Expression module encompases all functions around encoding and decoding
+  # strings into Measurement::Units and vice-versa.
+  module Expression
+    class << self
+      # Build a string representation of a collection of terms
+      # @param terms [Array]
+      # @return [String]
+      # @example
+      #   Unitwise::Expression.compose(terms) # => "m2/s2"
+      # @api public
+      def compose(terms, method = :primary_code)
+        Composer.new(terms, method).expression
+      end
+
+      # Convert a string representation of a unit into an array of terms
+      # @param expression [String] The string you wish to convert
+      # @return [Array]
+      # @example
+      #   Unitwise::Expression.decompose("m2/s2")
+      #   # => [<Unitwise::Term m2>, <Unitwise::Term s-2>]
+      # @api public
+      def decompose(expression)
+        Decomposer.parse(expression)
+      end
+
+    end
+  end
+end