measurement 0.1 → 0.2

data/CHANGELOG

@@ -1 +1,3 @@
+v0.2 Documentation
+
 v0.1 First version

data/Manifest

@@ -4,12 +4,12 @@ Manifest
 README.rdoc
 Rakefile
 lib/measurement.rb
-lib/measurement/conversion.rb
 lib/measurement/length.rb
+lib/measurement/unit.rb
 lib/measurement/weight.rb
-spec/lib/conversion_spec.rb
 spec/lib/length_spec.rb
 spec/lib/measurement_spec.rb
+spec/lib/unit_spec.rb
 spec/lib/weight_spec.rb
 spec/spec.opts
 spec/spec_helper.rb

data/README.rdoc

@@ -2,12 +2,14 @@
 
 * http://github.com/jemmyw/measurement
 
-== DESCRIPTION
-
 == INSTALL:
 
 * sudo gem install measurement
 
+== DOCUMENTATION:
+
+* http://rdoc.info/projects/jemmyw/measurement
+
 == EXAMPLE:
 
   require 'measurement/length'

data/lib/measurement/length.rb

@@ -1,16 +1,36 @@
 require File.join(File.dirname(__FILE__), '..', 'measurement')
 
+# This class represents a Length measurement. The
+# base units are metres. The available conversions
+# are:
+#
+# * millimetres (mm)
+# * centimetres (cm)
+# * metres (m)
+# * kilometres (km)
+# * inches (")
+# * feet (')
+# * miles
+# * hands
+# * light_seconds
+# * light_hours
+#
+# Example usage:
+#
+#   require 'measurement/length'
+#   puts Length.parse('180.34cm').in_feet_and_inches => 5' 11"
+#
 class Length < Measurement::Base
-  base :metre, :suffix => 'm'
-  conversion 1000, :kilometre, :kilometres, :km, :suffix => 'km'
-  conversion 0.01, :centimetre, :centimetres, :cm, :suffix => 'cm'
-  conversion 0.001, :millimetre, :mm, :suffix => 'mm'
+  base :metre, :metres, :suffix => 'm'
+  unit 1000, :kilometre, :kilometres, :km, :suffix => 'km'
+  unit 0.01, :centimetre, :centimetres, :cm, :suffix => 'cm'
+  unit 0.001, :millimetre, :mm, :suffix => 'mm'
   
-  conversion 0.0254, :inch, :inches, :suffix => '"'
-  conversion 0.3048, :feet, :foot, :suffix => "'"
-  conversion 1609.34, :mile, :miles, :suffix => ' miles'
-  conversion 0.1016, :hand, :hands, :suffix => ' hands'
+  unit 0.0254, :inch, :inches, :suffix => '"'
+  unit 0.3048, :feet, :foot, :suffix => "'"
+  unit 1609.34, :mile, :miles, :suffix => ' miles'
+  unit 0.1016, :hand, :hands, :suffix => ' hands'
   
-  conversion 299792458, :light_seconds, :suffix => ' light seconds'
-  conversion 1079252848800, :light_hours, :suffix => ' light hours'
+  unit 299792458, :light_seconds, :suffix => ' light seconds'
+  unit 1079252848800, :light_hours, :suffix => ' light hours'
 end

data/lib/measurement/{conversion.rb → unit.rb}

@@ -1,5 +1,5 @@
 module Measurement
-  class Conversion
+  class Unit
     attr_reader :names
     
     def initialize(scale, *args)

data/lib/measurement/weight.rb

@@ -1,9 +1,24 @@
 require File.join(File.dirname(__FILE__), '..', 'measurement')
 
+# This class represents a Weight measurement. The
+# base units are grams. The available conversions
+# are:
+#
+# * grams (g)
+# * kilograms (kg)
+# * pounds (lbs)
+# * ounces (oz)
+# * stone (st)
+#
+# Example usage:
+#
+#   require 'measurement/weight'
+#   puts Length.parse('100kg').in_lbs_and_oz => 220lbs 7oz
+#
 class Weight < Measurement::Base
-  base :grams, :suffix => 'g'
-  conversion 1000.0, :kilograms, :kg, :kgs, :suffix => 'kg'
-  conversion 453.59236, :pounds, :pound, :lbs, :suffix => 'lbs'
-  conversion 28.3495231, :ounces, :ounce, :oz, :suffix => 'oz'
-  conversion 6350.29318, :stone, :st, :suffix => 'st'
+  base :gram, :grams, :suffix => 'g'
+  unit 1000.0, :kilograms, :kg, :kgs, :suffix => 'kg'
+  unit 453.59236, :pounds, :pound, :lbs, :suffix => 'lbs'
+  unit 28.3495231, :ounces, :ounce, :oz, :suffix => 'oz'
+  unit 6350.29318, :stone, :st, :suffix => 'st'
 end

data/lib/measurement.rb

@@ -1,55 +1,121 @@
-require File.join(File.dirname(__FILE__), 'measurement', 'conversion')
+require File.join(File.dirname(__FILE__), 'measurement', 'unit')
 
 module Measurement
-  class NoScaleFoundException < Exception; end
-  
+  class NoUnitFoundException < Exception; end
+
+  # The Measurement::Base class provides a basis for types of
+  # measurement. For example, length or weight. It should
+  # be subclassed and not used directly.
+  #
+  # Example:
+  #
+  #   class Length < Measurement::Base
+  #     base :metre, :metres, :suffix => 'm'
+  #     unit 0.3048, :feet, :foot, :suffix => "'"
+  #   end
+  #   
+  #   Length.new(10).in_feet => 32.8083989501312
+  #
+  # Extending an existing measurement:
+  #
+  # Length.unit 2000, :quint, :qt, :suffix => 'qt'
+  # Length.new(10).to_s(:qt, 3) => 0.005qt
+  #
   class Base
+    # Define the base measurement unit. This method accepts
+    # a list of names for the base measurement, followed
+    # by the standard unit options. See #unit
+    #
+    # Example, defining a base unit for weights:
+    #
+    #   class Weight < Measurement::Base
+    #     base :gram, :grams, :suffix => 'g'
+    #   end
+    #
+    #   Weight.new(1).to_s => "1g"
+    #
+    # The base unit should only be set once because all
+    # other units in this measurement are based off the
+    # base unit.
+    #
     def self.base(*args)
       if args.any?
-        @base = Conversion.new(1.0, *args)
-        add_conversion(@base)
+        @base = Unit.new(1.0, *args)
+        add_unit(@base)
       else
         @base
       end
     end
     
-    def self.conversions
-      @conversions ||= []
+    def self.units # :nodoc:
+      @units ||= []
     end
   
-    def self.conversion(scale, *args)
-      add_conversion(Conversion.new(scale, *args))
+    # Define a unit of measurement. This must be a number based on
+    # the #base measurement unit.
+    # Takes a scaling number, a list of names and finally a
+    # hash of options.
+    #
+    # For example, if the base unit is metres, then defining the
+    # unit for centimetres would be as follows:
+    #
+    #   unit 0.01, :centimetre, :centimetres, :cm, :suffix => 'cm'
+    #
+    # Here a centimetre is defined as one hundredth of a metre. The
+    # different name usages for centimetre are specified (for parsing, see #parse),
+    # and the suffix is set to 'cm'
+    #
+    # Available options:
+    #
+    # * <tt>prefix</tt> - A prefix to use when formatting the unit.
+    # * <tt>suffix</tt> - A suffix to use when formatting the unit.
+    #
+    def self.unit(scale, *args)
+      add_unit(Unit.new(scale, *args))
     end
   
-    def self.add_conversion(conversion)
-      conversions << conversion
+    def self.add_unit(unit) # :nodoc:
+      units << unit
     end
   
-    def self.fetch_scale(scale = nil)
-      scale.nil? ? base : conversions.detect do |conversion|
-        conversion.has_name?(scale)
+    def self.fetch_scale(scale = nil) # :nodoc:
+      scale.nil? ? base : units.detect do |unit|
+        unit.has_name?(scale)
       end
     end
     
-    def self.find_scale(scale)
-      conversions.detect do |conversion|
-        conversion.has_name?(scale) ||
-          conversion.suffix == scale
+    def self.find_scale(scale) # :nodoc:
+      units.detect do |unit|
+        unit.has_name?(scale) ||
+          unit.suffix == scale
       end
     end
   
-    def self.from(amount, scale)
+    def self.from(amount, scale) # :nodoc:
       fetch_scale(scale).from(amount)
     end
   
-    def self.to(amount, scale = nil)
+    def self.to(amount, scale = nil) # :nodoc:
       fetch_scale(scale).to(amount)
     end
   
-    def self.format(amount, scale = nil, precision = 2)
+    def self.format(amount, scale = nil, precision = 2) #:nodoc:
       fetch_scale(scale).format(amount, precision)
     end
     
+    # Parse a string containing this measurement. The string
+    # can use any of the defined units. This function will look
+    # for numbers in the string, followed by text. The text
+    # can be any unit name or suffix.
+    #
+    # Examples:
+    #   Length.parse("180cm").in_cm => 180
+    #   Length.parse("10m 11cm 12mm").in_metres => 10.122
+    #
+    # If a valid unit cannot be found an error is raised:
+    #
+    #   Weight.parse("180cm") => Measurement::NoScaleException
+    #
     def self.parse(string)
       string = string.dup
       base_amount = 0.0
@@ -62,7 +128,7 @@ module Measurement
           scale = find_scale(scale)
           
           if scale.nil?
-            raise NoScaleFoundException.new(scale)
+            raise NoUnitFoundException.new(scale)
           else
             base_amount += scale.from(amount)
           end
@@ -80,19 +146,32 @@ module Measurement
       @amount = self.class.from(amount, scale)
     end
   
+    # The base unit as an integer
     def to_i
       @amount.to_i
     end
   
+    # The base unit as a float
     def to_f
       @amount.to_f
     end
   
-    def as(scale)
-      self.class.to(@amount, scale)
+    # This measurement converted to the specified unit.
+    #
+    # Example:
+    #
+    #   Length.new(10).as(:feet) => 32.8083989501312
+    #
+    # This method can also be called using helper methods:
+    #
+    #   Length.new(10).in_feet
+    #   Length.new(10).as_feet
+    #
+    def as(unit)
+      self.class.to(@amount, unit)
     end
     
-    def method_missing(method, *args)
+    def method_missing(method, *args) # :nodoc:
       if method.to_s =~ /^(as|in)_(.*)/
         scale = $2
         if scale =~ /and/
@@ -105,23 +184,43 @@ module Measurement
       end
     end
   
-    def to_s(scale = nil, precision = 2)
-      if scale.to_s =~ /_and_/
-        scales = scale.to_s.split('_and_')
+    # Format the measurement and return as a string. 
+    # This will format using the base unit if no unit
+    # is specified.
+    #
+    # Example:
+    #
+    #   Length.new(1.8034).to_s(:feet) => 6'
+    #
+    # Multiple units can be specified allowing for a
+    # more naturally formatted measurement. For example:
+    #
+    #   Length.new(1.8034).to_s(:feet_and_inches) => 5' 11"
+    #
+    # Naturally formatted measurements can be returned using
+    # shorthand functions:
+    #
+    #   Length.new(1.8034).in_feet_and_inches => 5' 11"
+    #
+    # A precision can be specified, otherwise the measurement
+    # is rounded to the nearest integer.
+    def to_s(unit = nil, precision = 0)
+      if unit.to_s =~ /_and_/
+        units = unit.to_s.split('_and_')
         amount = @amount
         strs = []
     
-        while scale = scales.shift
-          n_in = self.class.to(amount, scale.to_sym)
-          n_in = n_in.floor unless scales.empty?        
-          n_out = self.class.from(n_in, scale.to_sym)
-          amount -= self.class.from(n_in, scale.to_sym)
-          strs << self.class.format(n_out, scale.to_sym, 0)
+        while unit = units.shift
+          n_in = self.class.to(amount, unit.to_sym)
+          n_in = n_in.floor unless units.empty?        
+          n_out = self.class.from(n_in, unit.to_sym)
+          amount -= self.class.from(n_in, unit.to_sym)
+          strs << self.class.format(n_out, unit.to_sym, 0)
         end
     
         strs.join(' ')
       else
-        self.class.format(@amount, scale, precision)
+        self.class.format(@amount, unit, precision)
       end
     end
     alias_method :format, :to_s

data/measurement.gemspec

@@ -2,15 +2,15 @@
 
 Gem::Specification.new do |s|
   s.name = %q{measurement}
-  s.version = "0.1"
+  s.version = "0.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
   s.authors = ["Jeremy Wells"]
   s.date = %q{2010-02-27}
   s.description = %q{A library for holding, converting and formatting measurements}
   s.email = %q{jemmyw@gmail.com}
-  s.extra_rdoc_files = ["CHANGELOG", "LICENSE", "README.rdoc", "lib/measurement.rb", "lib/measurement/conversion.rb", "lib/measurement/length.rb", "lib/measurement/weight.rb"]
-  s.files = ["CHANGELOG", "LICENSE", "Manifest", "README.rdoc", "Rakefile", "lib/measurement.rb", "lib/measurement/conversion.rb", "lib/measurement/length.rb", "lib/measurement/weight.rb", "spec/lib/conversion_spec.rb", "spec/lib/length_spec.rb", "spec/lib/measurement_spec.rb", "spec/lib/weight_spec.rb", "spec/spec.opts", "spec/spec_helper.rb", "measurement.gemspec"]
+  s.extra_rdoc_files = ["CHANGELOG", "LICENSE", "README.rdoc", "lib/measurement.rb", "lib/measurement/length.rb", "lib/measurement/unit.rb", "lib/measurement/weight.rb"]
+  s.files = ["CHANGELOG", "LICENSE", "Manifest", "README.rdoc", "Rakefile", "lib/measurement.rb", "lib/measurement/length.rb", "lib/measurement/unit.rb", "lib/measurement/weight.rb", "spec/lib/length_spec.rb", "spec/lib/measurement_spec.rb", "spec/lib/unit_spec.rb", "spec/lib/weight_spec.rb", "spec/spec.opts", "spec/spec_helper.rb", "measurement.gemspec"]
   s.homepage = %q{}
   s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Measurement", "--main", "README.rdoc"]
   s.require_paths = ["lib"]

data/spec/lib/length_spec.rb

@@ -1,8 +1,8 @@
 require 'spec_helper'
 
 describe Length do
-  it 'should have 10 conversions' do
-    Length.conversions.size.should == 10
+  it 'should have 10 units' do
+    Length.units.size.should == 10
   end
   
   it 'should use metres as a base' do

data/spec/lib/measurement_spec.rb

@@ -29,7 +29,7 @@ describe Measurement::Base do
     it 'should raise a NoScaleFoundException if there is no scale matching the one passed' do
       lambda do
         Length.parse('10giglygoops')
-      end.should raise_error(Measurement::NoScaleFoundException)
+      end.should raise_error(Measurement::NoUnitFoundException)
     end
   end
   

data/spec/lib/unit_spec.rb

@@ -0,0 +1,42 @@
+require 'spec_helper'
+
+describe Measurement::Unit do
+  describe '#instance methods' do
+    before do
+      @unit = Measurement::Unit.new(150.0, :test, :other)
+    end
+        
+    describe '#from' do
+      it 'should multiply the amount by the unit scale' do
+        @unit.from(1).should == 150.0
+      end
+    end
+  
+    describe '#to' do
+      it 'should divide the amount by the unit scale' do
+        @unit.to(150).should == 1
+      end
+    end
+  
+    describe '#format' do
+      it 'should return a string' do
+        @unit.format(1).should be_a(String)
+      end
+      
+      it 'should format using the given precision' do
+        @unit.format(200,1).should == "1.3"
+        @unit.format(200,2).should == "1.33"
+      end
+      
+      it 'should apply the suffix' do
+        @unit = Measurement::Unit.new(150.0, :test, :suffix => 'test')
+        @unit.format(150, 0).should == "1test"
+      end
+      
+      it 'should apply the prefix' do
+        @unit = Measurement::Unit.new(150.0, :test, :prefix => 'test')
+        @unit.format(150, 0).should == "test1"
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: measurement
 version: !ruby/object:Gem::Version 
-  version: "0.1"
+  version: "0.2"
 platform: ruby
 authors: 
 - Jeremy Wells
@@ -24,8 +24,8 @@ extra_rdoc_files:
 - LICENSE
 - README.rdoc
 - lib/measurement.rb
-- lib/measurement/conversion.rb
 - lib/measurement/length.rb
+- lib/measurement/unit.rb
 - lib/measurement/weight.rb
 files: 
 - CHANGELOG
@@ -34,12 +34,12 @@ files:
 - README.rdoc
 - Rakefile
 - lib/measurement.rb
-- lib/measurement/conversion.rb
 - lib/measurement/length.rb
+- lib/measurement/unit.rb
 - lib/measurement/weight.rb
-- spec/lib/conversion_spec.rb
 - spec/lib/length_spec.rb
 - spec/lib/measurement_spec.rb
+- spec/lib/unit_spec.rb
 - spec/lib/weight_spec.rb
 - spec/spec.opts
 - spec/spec_helper.rb

data/spec/lib/conversion_spec.rb

@@ -1,42 +0,0 @@
-require 'spec_helper'
-
-describe Measurement::Conversion do
-  describe '#instance methods' do
-    before do
-      @conversion = Measurement::Conversion.new(150.0, :test, :other)
-    end
-        
-    describe '#from' do
-      it 'should multiply the amount by the conversion scale' do
-        @conversion.from(1).should == 150.0
-      end
-    end
-  
-    describe '#to' do
-      it 'should divide the amount by the conversion scale' do
-        @conversion.to(150).should == 1
-      end
-    end
-  
-    describe '#format' do
-      it 'should return a string' do
-        @conversion.format(1).should be_a(String)
-      end
-      
-      it 'should format using the given precision' do
-        @conversion.format(200,1).should == "1.3"
-        @conversion.format(200,2).should == "1.33"
-      end
-      
-      it 'should apply the suffix' do
-        @conversion = Measurement::Conversion.new(150.0, :test, :suffix => 'test')
-        @conversion.format(150, 0).should == "1test"
-      end
-      
-      it 'should apply the prefix' do
-        @conversion = Measurement::Conversion.new(150.0, :test, :prefix => 'test')
-        @conversion.format(150, 0).should == "test1"
-      end
-    end
-  end
-end