measurb 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 041ff65242c85675992b2b42b67f1747c24f8e64
+  data.tar.gz: 37ec1b92574b3a80ee26999d295baf35824ebb7d
+SHA512:
+  metadata.gz: c3539e48fb3b4bbe21e341d56907fa7bd4526ccebf61c5e4fe4379c3e9cd22c2c2b7f324c6c0677d74922d83978d112e6f533b0d50e8a811846c498d2b0bc2ca
+  data.tar.gz: e287a287a4f9bab984ff8f8addaeb8b4df0d75551985dd20c1e7c6230bbcac52a34800db7f3def1d039542c067a5c2ecccf13ffeee82c5f59e508dab95efb40a

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,4 @@
+--color
+--warnings
+--require spec_helper
+--format progress

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in dims-rb.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Jeremy Fairbank
+
+MIT License
+
+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.md

@@ -0,0 +1,130 @@
+# Measurb
+
+Handle units of measurment with ease! Measurb is a Ruby library for creating and managing units of measurements, or dimensions. Create your own units and define how to convert amongst them. Measurb also comes with a few default dimensions: inches, feet, and yards, but you don't have to use them. Measurb takes care of the tediousness of adding, subtracting, and comparing different measurements, especially between different units of measurement.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'measurb'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install measurb
+
+## Defining Dimensions
+
+Measurb has a straightforward interface to defining dimensions. Just give `Measurb.define` a dimension name and optional block to define conversions.
+
+```ruby
+# Without conversions
+Measurb.define :inches
+
+# With conversion
+Measurb.define :inches do
+  feet  value / 12.0
+  yards value / 36.0
+end
+
+Measurb.define :feet do
+  inches value * 12.0
+  yards  value / 3.0
+end
+
+Measurb.define :yards do
+  feet   value * 3.0
+  inches value * 36.0
+end
+```
+
+You can specify an abbreviation for a dimension too.
+
+```ruby
+Measurb.define :ft, abbrev: 'ft'
+```
+
+## Using Dimensions
+
+When you define a dimension, Measurb creates a dimension class that can be instantiated.
+
+```ruby
+Measurb.define :inches
+forty_two_inches = Measurb::Inches.new(42)
+```
+
+Merb also defines a singleton method on itself and a method on `Numeric`, both of the same dimension name.
+
+```ruby
+two_inches   = Measurb.inches(2) # singleton method
+three_inches = 3.inches          # Numeric method
+```
+
+If you defined an abbreviation, you can use it on `Numeric` as well.
+
+```ruby
+Measurb.define :ft, abbrev: 'ft'
+5.feet == 5.ft #=> true
+```
+
+## Converting
+
+To convert a dimension, you must have set up at least two dimensions, including the appropriate conversion formulas.
+
+```ruby
+Measurb.define :inches do
+  feet value / 12.0
+end
+
+Measurb.define :feet do
+  inches value * 12.0
+end
+```
+
+For every conversion you set up in the definition block, Measurb will add a `to_*` method for that conversion.
+
+```ruby
+24.inches.to_feet == 2.feet
+3.feet.to_inches  == 36.inches
+```
+
+## Arithmetic
+
+Measurb supports addition and subtraction currently. You can perform operations amongst all the defined dimension classes. Make sure you've define your conversions beforehand, though! The resulting value will use the class of the leftmost operand.
+
+```ruby
+2.feet + 12.inches == 3.feet
+3.feet - 6.inches  == 2.5.feet
+3.yards - 1.feet   == 2.yards
+```
+
+## Equality and Comparisons
+
+Measurb also supports all the typical equality and inequality checks `==`  `!=`  `<`  `>`  `<=`  `>=` `<=>`. They work correctly with other dimension classes too.
+
+```ruby
+42.feet == 42.feet  #=> true
+2.feet < 26.inches  #=> true
+3.feet > 2.yards    #=> false
+24.inches <= 2.feet #=> true
+5.feet <=> 2.yards  #=> -1
+24.inches != 2.feet #=> false
+```
+
+`eql?` is also implemented, but it DOES depend on the same dimension class to be true
+
+```ruby
+2.feet.eql? 2.feet    #=> true
+2.feet.eql? 24.inches #=> false
+```
+
+## Contributing
+
+1. Fork it ( http://github.com/jfairbank/measurb/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/measurb/config.rb

@@ -0,0 +1,32 @@
+module Measurb
+  # Class for managing configuration of {Measurb}
+  class Config
+    # Enable defaults dimensions based on their name
+    #
+    # @api public
+    #
+    # @example
+    #   Measurb.configure do |config|
+    #     config.enable_defaults :inches, :feet
+    #   end
+    #
+    # @param  names [Symbol, String]        The dimension names to enable
+    # @return       [Array<Symbol, String>] The dimension names that were enabled
+    def enable_defaults(*names)
+      enabled = []
+
+      names.each do |name|
+        path = "measurb/defaults/#{name}"
+
+        begin
+          require path
+          enabled << name
+        rescue LoadError
+          warn "'#{name}' is not a default dimension"
+        end
+      end
+
+      enabled
+    end
+  end
+end

data/lib/measurb/core_ext.rb

@@ -0,0 +1,33 @@
+module Measurb
+  # Module for extending core classes
+  module CoreExt
+    # Add the dimension name method to `Numeric`
+    #
+    # @api semipublic
+    #
+    # @example
+    #   42.respond_to?(:inches) #=> false
+    #
+    #   Measurb::CoreExt.add_numeric_dimension(:inches, 'Inches', 'in')
+    #
+    #   42.respond_to?(:inches) #=> true
+    #
+    # @param name                 [Symbol, String] Name of the dimension
+    # @param dimension_class_name [String]         Name of the dimension class
+    # @param abbrev               [String]         Abbreviation for the dimension name
+    # @return                     [nil]
+    def self.add_numeric_dimension(name, dimension_class_name, abbrev)
+      def_string = <<-EOS
+        def #{name}(precision = #{DEFAULT_PRECISION})
+          Measurb::#{dimension_class_name}.new(self, precision)
+        end
+      EOS
+
+      unless abbrev.nil?
+        def_string << "\nalias_method :#{abbrev}, :#{name}"
+      end
+
+      Numeric.class_eval(def_string)
+    end
+  end
+end

data/lib/measurb/defaults/feet.rb

@@ -0,0 +1,4 @@
+Measurb.define :feet, abbrev: 'ft' do
+  inches value * 12.0
+  yards  value / 3.0
+end

data/lib/measurb/defaults/inches.rb

@@ -0,0 +1,4 @@
+Measurb.define :inches, abbrev: 'in' do
+  feet  value / 12.0
+  yards value / 36.0
+end

data/lib/measurb/defaults/yards.rb

@@ -0,0 +1,4 @@
+Measurb.define :yards, abbrev: 'yd' do
+  feet   value * 3.0
+  inches value * 36.0
+end

data/lib/measurb/dimension.rb

@@ -0,0 +1,93 @@
+module Measurb
+  # Base class for defined dimensions to inherit from.
+  class Dimension
+    include Comparable
+
+    attr_reader :value, :precision
+
+    class << self
+      attr_reader :abbrev, :dimension_name
+    end
+
+    # Initialize the dimension
+    #
+    # @param value     [Numeric] Numeric value to wrap
+    # @param precision [Integer] Precision of decimal places
+    # @return          [Measurb::Dimension]
+    def initialize(value, precision = DEFAULT_PRECISION)
+      @precision      = precision
+      @original_value = value
+      @value          = fix_value(value, precision)
+    end
+
+    # Add another dimension
+    #
+    # @param other [Measurb::Dimension]
+    # @return      [Measurb::Dimension]
+    def +(other)
+      arithmetic(:+, other)
+    end
+
+    # Subtract another dimension
+    #
+    # @param other [Measurb::Dimension]
+    # @return      [Measurb::Dimension]
+    def -(other)
+      arithmetic(:-, other)
+    end
+
+    # Compare with another dimension
+    #
+    # @param other [Measurb::Dimension]
+    # @return      [-1, 0, 1]
+    def <=>(other)
+      value <=> to_self(other).value
+    end
+
+    # Check type and value quality with another dimension
+    #
+    # @param other [Measurb::Dimension]
+    # @return      [Boolean]
+    def eql?(other)
+      self.class == other.class && self == other
+    end
+
+    # Get the inspect string
+    #
+    # @return [String]
+    def inspect
+      "#{value} #{self.class.abbrev || self.class.dimension_name}"
+    end
+
+    private
+
+    # Perform an arithmetic operation `name` with `other`, keeping the
+    # smallest precision of the two dimensions.
+    #
+    # @param op    [Symbol] Name of the arithmetic operation
+    # @param other [Measurb::Dimension]
+    # @return      [Measurb::Dimension]
+    def arithmetic(op, other)
+      least_precision = [precision, other.precision].min
+      new_value = value.__send__(op, to_self(other).value)
+      self.class.new(new_value, least_precision)
+    end
+
+    # Coerce other dimension to own class
+    #
+    # @param other [Measurb::Dimension]
+    # @return      [self.class]
+    def to_self(other)
+      other.__send__("to_#{self.class.dimension_name}")
+    end
+
+    # Adjust a value to a given decimal precision
+    #
+    # @param value     [Numeric]
+    # @param precision [Integer] Precision of decimal places
+    def fix_value(value, precision)
+      modifier = (10 ** precision).to_f
+      (value * modifier).round / modifier
+    end
+  end
+end

data/lib/measurb/dimension_builder.rb

@@ -0,0 +1,108 @@
+module Measurb
+  # Factory class for building new dimension classes
+  class DimensionBuilder
+    attr_reader :dimension_class_name, :value
+
+    # Get an appropriate class name for a dimension name
+    #
+    # @param name [Symbol, String] Name of the dimension
+    # @return     [String]         Name of the dimension class
+    def self.get_dimension_class_name(name)
+      name.to_s.split('_').map(&:capitalize).join
+    end
+
+    # Initialize the builder
+    #
+    # @param  name    [Symbol, String] Name of the dimension
+    # @param  options [Hash]
+    # @option options [String]         :abbrev (nil) The dimension abbreviation
+    # @param  block   [Proc]           Block for defining conversions to other dimensions
+    def initialize(name, options = {}, &block)
+      @name                 = name
+      @def_block            = block
+      @options              = options
+      @dimension_class_name = self.class.get_dimension_class_name(name)
+    end
+
+    # @!attribute [r] dimension_class
+    # Get the dimension class, creating it if it's not available
+    # @return [Measurb::Dimension]
+    def dimension_class
+      build_dimension_class unless defined?(@dimension_class)
+      @dimension_class
+    end
+
+    # Use to build conversion methods to other dimensions
+    def method_missing(name, *args, &block)
+      build_default_conversion(name, args.first)
+    end
+
+    private
+
+    # Build a conversion to another dimension with a default implementation
+    #
+    # @param name       [Symbol, String] Name of the dimension
+    # @param conversion [Proc]           Proc to convert the actual value
+    def build_default_conversion(name, conversion)
+      class_name = self.class.get_dimension_class_name(name)
+
+      build_conversion(name) do
+        precision ||= self.precision
+        Measurb.const_get(class_name).new(instance_eval(&conversion), precision)
+      end
+    end
+
+    # Build a conversion method, using `block` as the body
+    #
+    # @param name  [Symbol, String] Name of the dimension
+    # @param block [Proc]           Conversion method body
+    def build_conversion(name, &block)
+      @dimension_class.__send__(:define_method, "to_#{name}", &block)
+    end
+
+    # Build the dimension class, defining any conversions from `@def_block` and
+    # defining a default conversion to itself
+    def build_dimension_class
+      @value           = ValueProxy.new
+      @dimension_class = Class.new(Dimension)
+
+      @dimension_class.instance_variable_set(:@dimension_name, @name.to_s)
+      @dimension_class.instance_variable_set(:@abbrev,         @options[:abbrev])
+
+      instance_eval(&@def_block) unless @def_block.nil?
+
+      # Return self when converting to same dimension
+      build_conversion(@name) { self }
+    end
+
+    # Placeholder class in definition blocks for writing straightforward conversion syntax.
+    # Currently only supports multiplication and division.
+    #
+    # ==== Examples
+    #
+    #    Measurb.define :inches do
+    #      feet value / 12.0
+    #    end
+    #
+    #    Measurb.define :feet do
+    #      inches value * 12.0
+    #    end
+    class ValueProxy
+      # Handle a conversion by multiplication
+      #
+      # @param convert_value [Float]
+      # @return              [Proc] Proc to be used as the body for the conversion method on the {Dimension dimension class}
+      def *(convert_value)
+        proc { value * convert_value }
+      end
+
+      # Handle a conversion by division
+      #
+      # @param convert_value [Float]
+      # @return              [Proc] Proc to be used as the body for the conversion method on the {Dimension dimension class}
+      def /(convert_value)
+        proc { value / convert_value }
+      end
+    end
+  end
+end

data/lib/measurb/version.rb

@@ -0,0 +1,3 @@
+module Measurb
+  VERSION = '0.0.1'
+end

data/lib/measurb.rb

@@ -0,0 +1,109 @@
+require 'measurb/version'
+require 'measurb/config'
+require 'measurb/core_ext'
+require 'measurb/dimension'
+require 'measurb/dimension_builder'
+
+# Main module
+module Measurb
+  DEFAULT_PRECISION = 3
+
+  # Error when attempting to define a dimension that already exists
+  class DuplicateDimensionError < NameError; end
+
+  class << self
+    # Define a new dimension class and helper singleton method
+    #
+    # @api public
+    #
+    # @example Without conversions
+    #   Measurb.define :inches
+    #
+    # @example With conversions
+    #   Measurb.define :inches do
+    #     feet value / 12.0
+    #   end
+    #
+    #   Measurb.define :feet do
+    #     inches value * 12.0
+    #   end
+    #
+    # @param name [Symbol, String]     Name of the dimension
+    # @return     [Measurb::Dimension] A subclass of {Measurb::Dimension}
+    def define(name, options = {}, &block)
+      # Check if the dimension has already been defined
+      if dimension_exists?(name)
+        raise DuplicateDimensionError,
+          "Already defined dimension class `#{DimensionBuilder.get_dimension_class_name(name)}`"
+      end
+
+      # Create the dimension builder
+      builder = DimensionBuilder.new(name, options, &block)
+
+      # Add the class constant and helper method to the module
+      const_set(builder.dimension_class_name, builder.dimension_class)
+      add_dimension_method(name, builder.dimension_class_name)
+
+      # Add the helper methods to 'Numeric'
+      CoreExt.add_numeric_dimension(name, builder.dimension_class_name, builder.dimension_class.abbrev)
+
+      builder.dimension_class
+    end
+
+    # Configure {Measurb} with {Config}
+    #
+    # @api public
+    #
+    # @example
+    #   Measurb.configure do |config|
+    #     config.enable_defaults :inches, :feet
+    #   end
+    #
+    # @return [nil]
+    def configure
+      yield config
+    end
+
+    # Check if the dimension already exists
+    #
+    # @api public
+    #
+    # @example
+    #   Measurb.configure { |config| config.enable_defaults(:inches) }
+    #
+    #   Measurb.dimension_exists?(:inches) #=> true
+    #   Measurb.dimension_exists?(:feet)   #=> false
+    #
+    # @param name [Symbol, String] Name of the dimension
+    # @return     [Boolean]
+    def dimension_exists?(name)
+      const_defined?(DimensionBuilder.get_dimension_class_name(name))
+    end
+
+    private
+
+    # Config object used by {#configure}
+    #
+    # @api private
+    #
+    # @return [Config] The configurable object
+    def config
+      @config ||= Config.new
+    end
+
+    # Create the dimension class singleton method
+    #
+    # @api private
+    #
+    # @param name                 [Symbol, String] Name of the dimension
+    # @param dimension_class_name [String]         Name of the dimension class
+    # @return                     [Symbol, nil]    Return type based on ruby version
+    def add_dimension_method(name, dimension_class_name)
+      instance_eval <<-EOS, __FILE__, __LINE__ + 1
+        def #{name}(value, precision = DEFAULT_PRECISION)
+          #{dimension_class_name}.new(value, precision)
+        end
+      EOS
+    end
+  end
+end

data/measurb.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'measurb/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'measurb'
+  spec.version       = Measurb::VERSION
+  spec.authors       = ['Jeremy Fairbank']
+  spec.email         = ['elpapapollo@gmail.com']
+  spec.summary       = %q{Handle units of measurement}
+  spec.description   = %q{Handle units of measurement}
+  spec.homepage      = ''
+  spec.license       = 'MIT'
+
+  #spec.files         = `git ls-files -z`.split('\x0')
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.5'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec',   '~> 3.0.0'
+end

data/spec/arithmetic_spec.rb

@@ -0,0 +1,67 @@
+require 'spec_helper'
+
+describe Measurb::Dimension do
+  before :context do
+    clear_defined_inches
+    clear_defined_feet
+    clear_defined_yards
+    remove_loaded_default_dimensions
+
+    Measurb.configure do |config|
+      config.enable_defaults :inches, :feet
+    end
+  end
+
+  let(:inches) { 24.inches }
+  let(:feet)   { 5.feet }
+
+  context 'when adding' do
+    it 'returns the left hand side class' do
+      expect(inches + inches).to be_a(Measurb::Inches)
+      expect(inches + feet).to   be_a(Measurb::Inches)
+      expect(feet   + feet).to   be_a(Measurb::Feet)
+      expect(feet   + inches).to be_a(Measurb::Feet)
+    end
+
+    it 'adds correctly' do
+      expect(inches + inches).to have_value(48)
+      expect(inches + feet).to   have_value(84)
+      expect(feet   + feet).to   have_value(10)
+      expect(feet   + inches).to have_value(7)
+    end
+
+    it 'respects the smallest precision' do
+      x = Math::PI.inches(4)
+      y = 2.001.inches(3)
+      sum = x + y
+
+      expect(sum).to have_precision(3)
+      expect(sum).to have_value(5.143)
+    end
+  end
+
+  context 'when subtracting' do
+    it 'returns the left hand side class' do
+      expect(inches - inches).to be_a(Measurb::Inches)
+      expect(inches - feet).to   be_a(Measurb::Inches)
+      expect(feet   - feet).to   be_a(Measurb::Feet)
+      expect(feet   - inches).to be_a(Measurb::Feet)
+    end
+
+    it 'subtracts correctly' do
+      expect(inches - inches).to have_value(0)
+      expect(inches - feet).to   have_value(-36)
+      expect(feet   - feet).to   have_value(0)
+      expect(feet   - inches).to have_value(3)
+    end
+
+    it 'respects the smallest precision' do
+      x = Math::PI.inches(4)
+      y = 2.001.inches(3)
+      difference = x - y
+
+      expect(difference).to have_precision(3)
+      expect(difference).to have_value(1.141)
+    end
+  end
+end