unitwise 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 59c17c683ada5799884a58c772a51eb20b59a5b8
-  data.tar.gz: f8fb3b7099821b43a090d3253edb6e93a728dad3
+  metadata.gz: b743603a818807533ed423c0317ac33b05976d78
+  data.tar.gz: ac6d5fb45058fecc3575e771f2e605cbc3e4afe0
 SHA512:
-  metadata.gz: 7ebe5b4426d7adf2a107fa4ab122ebffffcc79468b342e9592b06e0dc434fe90582db96a5e563c1c755bdd8b66fa26c5146c59879c8e66c9e2d697a9d1e4762f
-  data.tar.gz: 685a1a81769b575066d608572038ebaf43eab8c04bf9e635971ec7ff8080fee248ea1f549ba1d9e94d95af8032959f5080fcbec091846e346cb4e8d28fa7b8dc
+  metadata.gz: 39a648b7693240696ff80404452c1b19bd67569dea17a394d84a4b9cf69e4874f3645ca7e83bb4149ce0304a973adfb9f55ed110a9833036e3c418ecaf0b3e97
+  data.tar.gz: ba6432d868b98e2d0c93d1a821b400a54e9e837e09ee8a13ca41986ccf61a9e1a1586186f04e7cfb40297c6b07ae923109ca6593b634abad2057060148c15af0

data/README.md

@@ -15,42 +15,113 @@ Unitwise supports a vast number of units. At the time of writing, it supports 95
 
 ### Initialization:
 
-```ruby
+Instantiate measurements with `Unitwise()`
 
+```ruby
 require 'unitwise'
 
-2.3.kilogram # => <Unitwise::Measurement 2.3 kilogram>
+Unitwise(2.3, 'kilogram') # => <Unitwise::Measurement 2.3 kilogram>
+Unitwise('pound')         # => <Unitwise::Measurement 1 pound>
+```
+
+or require the core extensions for some syntactic sugar.
+
+```ruby
+require 'unitwise/ext'
 
-4.convert('pound') # => <Unitwise::Measurement 4 pound>
+1.convert(liter)
+# => <Unitwise::Measurement 1 liter>
 
+4.teaspoon
+# => <Unitwise::Measurement 4 teaspoon>
 ```
 
 ### Conversion
 
+Obviously, Unitwise handles simple unit conversion. You can convert to any
+compatible unit (Unitwise won't let you convert say inches to pounds) with the 
+`convert(unit)` method.
+
 ```ruby
+distance = Unitwise(5, 'kilometer') 
+# => <Unitwise::Measurement 5 kilometer>
+
+distance.convert('mile')
+# => <Unitwise::Measurement 3.106849747474748 mile>
+```
 
-26.2.mile.kilometer # => <Unitwise::Measurement 42.164897129794255 kilometer>
+The prettier version of `convert(unit)` is just calling the unit name method:
 
-5.kilometer.convert('mile') # => <Unitwise::Measurement 3.106849747474748 mile>
+```ruby
+distance = 26.2.mile
+# => <Unitwise::Measurement 26.2 mile>
 
+distance.kilometer
+# => <Unitwise::Measurement 42.164897129794255 kilometer>
 ```
 
 ### Comparison
 
-```ruby
+It also has the ability to compare measurements with the same or different units.
 
+```ruby
 12.inch == 1.foot # => true
 
 1.meter > 1.yard # => true
+```
+
+Again, you have to compare compatible units. Dissimilar units will fail. 
+For example, comparing two temperatures will work, comparing a mass to a length would fail.
+
+### SI abbreviations
+
+You can use shorthand for SI units.
+
+```ruby
+1.m  # => <Unitwise::Measurement 1 meter>
+1.ml #=> <Unitwise::Measurement 1 milliliter>
+```
+
+### Complex Units
+
+Units can be combined to make more complex ones. There is nothing special about
+them -- they can still be converted, compared, or operated on.
+
+```ruby
+speed = Unitwise(60, 'mile/hour')
+# => <Unitwise::Measurement 60 mile/hour>
 
+speed.convert('m/s')
+# => <Unitwise::Measurement 26.822453644907288 m/s>
+```
+
+Exponents and parenthesis are supported as well.
+
+```ruby
+Unitwise(1000, 'kg.s-1.(m/s)2').watt
+# => <Unitwise::Measurement 1000 watt>
 ```
 
 ### Math
 
-Note that you can also use SI abbreviations for units instead of names (i.e. ms for millisecond).
+You can add or subtract compatible measurements.
 
 ```ruby
+2.meter + 3.inch - 1.yard
+# => <Unitwise::Measurement 1.1618 meter>
+```
+
+You can multiply or divide measurements and numbers.
 
+```ruby
+110.volt * 2
+=> <Unitwise::Measurement 220 volt>
+```
+
+You can multiply or divide measurements with measurements. Here is a fun example
+from Physics 101
+
+```ruby
 m = 20.kg # => <Unitwise::Measurement 20 kg>
 
 a = 10.m / 1.s2 # => <Unitwise::Measurement 10 m/s2>
@@ -58,32 +129,48 @@ a = 10.m / 1.s2 # => <Unitwise::Measurement 10 m/s2>
 f = m * a # => <Unitwise::Measurement 50 kg.m/s2>
 
 f.newton # => <Unitwise::Measurement 50 newton>
-
 ```
 
-## UCUM Atom Codes
+### Unit Compatibility
 
-There are several units that share names in the UCUM specification. There are a few versions of inch and foot, for example. So, specifying `1.foot` may not always be appropriate. You may have to use a UCUM Atom code instead of the unit name:
+Unitwise is fairly intelligent about unit compatibility. It boils each unit down
+to it's basic composition to determine if they are compatible. For instance,
+energy (say a Joule, which can be expressed as kg*m2/s2) would have the 
+components mass<sup>1</sup>, length<sup>2</sup>, and 
+time<sup>-2</sup>. Any unit that could be reduced to this same composition 
+would be considered compatible. 
 
-```ruby
+I've extracted this datatype into it's own gem ([SignedMultiset](//github.com/joshwlewis/signed_multiset)) if you find this construct interesting.
 
-1.convert('[ft_i]') == 1.convert('[ft_us]') # => false
+### Unit Names and Atom Codes
 
-3.convert('[in_br]') == 3.convert('[in_i]') # => false
+This library is based around the units in the UCUM specification, which is
+extensive and well thought out. However, not all of our unit systems throughout
+the world and history are consistent or logical. UCUM has devised a system where
+each unit has a unique atom code to try and solve this. The previous code examples
+don't show this, because for the most part you won't need it. Unitwise can
+figure out most of the units by their name or symbol. If you find you need to
+(or just want to be explicit) you use the UCUM atom codes without any
+modification.
 
-```
+Just as an example, you can see here that there are actually a few versions of inch
+and foot:
 
-## Compound Units
+```ruby
+1.convert('[ft_i]') == 1.convert('[ft_us]') # => false
 
-You can create compound units by multiplying or dividing measurements, or by using a compound string.
+3.convert('[in_br]') == 3.convert('[in_i]') # => false
+```
 
-```ruby
+### List of available units
 
-20.mile / 1.hour == 20.convert("mile/hour") # => true
+- You can get the official list from the UCUM website in XML format.
+  [unitsofmeasure.org/ucum-essence.xml](http://unitsofmeasure.org/ucum-essence.xml)
 
-4.convert("kg.(m/s)2") == 4.joule # => true
+- Unitwise occasionally converts the above XML into YAML for use by this
+  library.
+  [github.com/joshwlewis/unitwise/tree/master/data](//github.com/joshwlewis/unitwise/tree/master/data)
 
-```
 
 ## Installation
 

data/lib/unitwise.rb

@@ -11,7 +11,6 @@ require 'unitwise/term'
 require 'unitwise/unit'
 require 'unitwise/function'
 require 'unitwise/errors'
-require 'unitwise/ext'
 
 module Unitwise
   def self.path
@@ -23,3 +22,11 @@ module Unitwise
   end
 end
 
+def Unitwise(first_arg, last_arg=nil)
+  if last_arg
+    Unitwise::Measurement.new(first_arg, last_arg)
+  else
+    Unitwise::Measurement.new(1, first_arg)
+  end
+end
+

data/lib/unitwise/base.rb

@@ -38,7 +38,9 @@ module Unitwise
     end
 
     def slugs
-      names.map(&:to_slug)
+      names.map do |n|
+        n.downcase.strip.gsub(/\s/, '_').gsub(/\W/, '')
+      end
     end
 
   end

data/lib/unitwise/ext.rb

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

data/lib/unitwise/version.rb

@@ -1,3 +1,3 @@
 module Unitwise
-  VERSION = "0.2.2"
+  VERSION = "0.3.0"
 end

data/test/unitwise/ext/numeric_test.rb

@@ -1,5 +1,5 @@
 require 'test_helper'
-
+require 'unitwise/ext'
 describe Numeric do
 
   describe "#convert" do

data/test/unitwise_test.rb

@@ -1,7 +1,15 @@
 require 'test_helper'
 
 describe Unitwise do
+  describe '()' do
+    it "should accept a number and string" do
+      Unitwise(2, 'm/s').must_be_instance_of Unitwise::Measurement
+    end
+    it "should accept a lonely string" do
+      Unitwise('kg').must_be_instance_of Unitwise::Measurement
+    end
+  end
   it "should have a path" do
-    Unitwise.path.must_match /unitwise$/
+    Unitwise.path.must_match(/unitwise$/)
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: unitwise
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Josh Lewis
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-12-16 00:00:00.000000000 Z
+date: 2014-02-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: signed_multiset
@@ -138,7 +138,6 @@ files:
 - lib/unitwise/expression/transformer.rb
 - lib/unitwise/ext.rb
 - lib/unitwise/ext/numeric.rb
-- lib/unitwise/ext/string.rb
 - lib/unitwise/function.rb
 - lib/unitwise/functional.rb
 - lib/unitwise/measurement.rb
@@ -162,7 +161,6 @@ files:
 - test/unitwise/expression/matcher_test.rb
 - test/unitwise/expression/parser_test.rb
 - test/unitwise/ext/numeric_test.rb
-- test/unitwise/ext/string_test.rb
 - test/unitwise/function_test.rb
 - test/unitwise/measurement_test.rb
 - test/unitwise/prefix_test.rb
@@ -203,7 +201,6 @@ test_files:
 - test/unitwise/expression/matcher_test.rb
 - test/unitwise/expression/parser_test.rb
 - test/unitwise/ext/numeric_test.rb
-- test/unitwise/ext/string_test.rb
 - test/unitwise/function_test.rb
 - test/unitwise/measurement_test.rb
 - test/unitwise/prefix_test.rb

data/lib/unitwise/ext/string.rb

@@ -1,5 +0,0 @@
-class String
-  def to_slug
-    self.downcase.strip.gsub(/\s/, '_').gsub(/\W/, '')
-  end
-end

data/test/unitwise/ext/string_test.rb

@@ -1,13 +0,0 @@
-require 'test_helper'
-
-describe String do
-  describe '#to_slug' do
-    it "should convert 'Pascal' to 'pascal'" do
-      "Pascal".to_slug.must_equal 'pascal'
-    end
-
-    it "should convert 'degree Celsius' to 'degree_celsius'" do
-      "degree Celsius".to_slug.must_equal 'degree_celsius'
-    end
-  end
-end