latinum 0.2.0 → 0.2.3

data/README.md

@@ -7,6 +7,83 @@ Latinum
 
 Latinum is a framework for resource and currency calculations. *It is currently a work in progress and not designed to be taken seriously at this time*.
 
+Basic Usage
+-----------
+
+Latinum has several core concepts:
+
+- A `Resource` represents an immutable value with a specific face name (e.g. `'USD'`).
+- A `Resource` can only be combined with resources with the same face name.
+- A `Bank` is responsible for managing currencies and formatting options.
+- A `Bank` can exchange currencies explicitly with a given set of exchange rates.
+- A `Collection` is responsible for adding currencies together and is completely deterministic.
+
+### Resources and Collections ###
+
+To create a new resource, use a string for accuracy:
+
+	> ten = Latinum::Resource.new("10.00", "NZD")
+	=> 10.0 NZD
+	> ten.amount == "10.00".to_d
+	=> true
+
+You can add resources of different values but with the same name:
+
+	> ten + ten
+	=> 20.0 NZD
+
+But, you can't add resources of different names together:
+
+	> twenty = Latinum::Resource.new("20.00", "AUD")
+	=> 20.0 AUD
+	> ten + twenty
+	ArgumentError: Cannot operate on different currencies!
+
+To add multiple currencies together, use a collection:
+
+	> currencies = Set.new
+	> collection = Latinum::Collection.new(currencies)
+	> collection << ten
+	> collection << twenty
+	> currencies.collect {|currency| collection[currency]}
+	=> [10.0 NZD, 20.0 AUD]
+
+### Banks and Exchange Rates ###
+
+The bank is responsible for formatting and exchange rates:
+
+	require 'latinum/bank'
+	require 'latinum/currencies/global'
+	
+	> bank = Latinum::Bank.new(Latinum::Currencies::Global)
+	> bank << Latinum::ExchangeRate.new("NZD", "AUD", "0.5")
+	
+	> nzd = Latinum::Resource.new("10", "NZD")
+	=> 10.0 NZD
+	> aud = bank.exchange nzd, "AUD"
+	=> 5.0 AUD
+
+Formatting an amount is typically required for presentation to the end user:
+
+	> bank.format(nzd)
+	=> "$10.00 NZD"
+	
+	> bank.format(aud, :format => :compact)
+	=> "$5.00"
+
+The bank can also be used to parse currency, which will depend on the priority of currencies if a symbol that matches multiple currencies is supplied:
+
+	> bank.parse("$5")
+	=> 5.0 USD
+	
+	> bank.parse("€5")
+	=> 5.0 EUR
+
+Currency codes take priority over symbols if specified:
+
+	> bank.parse("€5 NZD")
+	=> 5.0 NZD
+
 License
 -------
 

data/lib/latinum.rb

@@ -18,5 +18,13 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
+require 'latinum/bank'
 require 'latinum/resource'
-require 'latinum/collection'
+require 'latinum/collection'
+
+require 'bigdecimal'
+require 'bigdecimal/util'
+
+if RUBY_VERSION < "1.9"
+	require 'latinum/extensions/bigdecimal-1.8'
+end

data/lib/latinum/bank.rb

@@ -25,7 +25,7 @@ module Latinum
 		def initialize(input, output, factor)
 			@input = input
 			@output = output
-			@factor = BigDecimal(factor)
+			@factor = factor.to_d
 		end
 		
 		attr :input
@@ -38,6 +38,8 @@ module Latinum
 			@rates = []
 			@exchange = {}
 			
+			# This implementation may change:
+			@currencies = {}
 			@formatters = {}
 			
 			# Symbols and their associated priorities
@@ -52,8 +54,10 @@ module Latinum
 			resources.each do |name, config|
 				name = (config[:name] || name).to_s
 				
+				@currencies[name] = config
+				
 				# Create a formatter:
-				self[name] = config[:formatter].new(config)
+				@formatters[name] = config[:formatter].new(config)
 				
 				if config[:symbol]
 					symbols = (@symbols[config[:symbol]] ||= [])
@@ -63,30 +67,32 @@ module Latinum
 			end
 		end
 		
+		def [] name
+			@currencies[name]
+		end
+		
 		attr :rates
 		attr :symbols
-		attr :formatters
+		attr :currencies
 		
-		def << object
+		def << rate
 			@rates << rate
 			
 			@exchange[rate.input] ||= {}
 			@exchange[rate.input][rate.output] = rate
 		end
 		
-		def []= name, formatter
-			@formatters[name] = formatter
-		end
-		
 		def exchange(resource, for_name)
 			rate = @exchange[resource.name][for_name]
 			raise ArgumentError.new("Invalid rate specified #{rate}") if rate == nil
 			
-			Resource.new(resource.amount * rate.factor, for_name)
+			config = self[for_name]
+			
+			resource.exchange(rate.factor, for_name, config[:precision])
 		end
 		
 		def parse(string)
-			parts = string.strip.split(/\s+, 2/)
+			parts = string.strip.split(/\s+/, 2)
 			
 			if parts.size == 2
 				Resource.new(parts[0].gsub(/[^\.0-9]/, ''), parts[1])

data/lib/latinum/collection.rb

@@ -25,7 +25,7 @@ module Latinum
 	class Collection
 		def initialize(names = Set.new)
 			@names = names
-			@resources = Hash.new {|hash, key| @names << key; BigDecimal.new(0)}
+			@resources = Hash.new {|hash, key| @names << key; BigDecimal.new("0")}
 		end
 		
 		attr :names
@@ -33,6 +33,8 @@ module Latinum
 		
 		def << resource
 			@resources[resource.name] += resource.amount
+			
+			return self
 		end
 		
 		def [] key

data/lib/latinum/currencies/global.rb

@@ -27,6 +27,7 @@ module Latinum
 		Global = {}
 		
 		Global[:NZD] = {
+			:precision => 2,
 			:symbol => '$',
 			:name => 'NZD',
 			:description => 'New Zealand Dollar',
@@ -34,6 +35,7 @@ module Latinum
 		}
 		
 		Global[:GBP] = {
+			:precision => 2,
 			:symbol => '£',
 			:name => 'GBP',
 			:description => 'Pound Sterling',
@@ -41,6 +43,7 @@ module Latinum
 		}
 		
 		Global[:AUD] = {
+			:precision => 2,
 			:symbol => '$',
 			:name => 'AUD',
 			:description => 'Australian Dollar',
@@ -48,6 +51,7 @@ module Latinum
 		}
 		
 		Global[:USD] = {
+			:precision => 2,
 			:symbol => '$',
 			:name => 'USD',
 			:description => 'United States Dollar',
@@ -55,6 +59,7 @@ module Latinum
 		}
 		
 		Global[:EUR] = {
+			:precision => 2,
 			:symbol => '€',
 			:name => 'EUR',
 			:description => 'Euro',
@@ -62,5 +67,13 @@ module Latinum
 			#:delimeter => '.',
 			#:separator => ','
 		}
+		
+		Global[:JPY] = {
+			:precision => 0,
+			:symbol => '¥',
+			:name => 'JPY',
+			:description => 'Japanese Yen',
+			:formatter => Formatters::DecimalCurrencyFormatter
+		}
 	end
 end

data/lib/latinum/extensions/bigdecimal-1.8.rb

@@ -0,0 +1,6 @@
+
+class BigDecimal
+	def to_d
+		self
+	end
+end

data/lib/latinum/formatters.rb

@@ -39,14 +39,14 @@ module Latinum
 				@symbol = options[:symbol] || '$'
 				@separator = options[:separator] || '.'
 				@delimeter = options[:delimter] || ','
-				@places = options[:places] || 2
+				@places = options[:precision] || 2
 				@zero = options[:zero] || '0'
 
 				@name = options[:name]
 			end
 
 			def format(amount, options = DEFAULT_OPTIONS)
-				fix, frac = amount.to_s('F').split(/\./, 2)
+				fix, frac = amount.abs.to_s('F').split(/\./, 2)
 
 				# The sign of the number
 				sign = amount.sign < 0 ? '-' : ''

data/lib/latinum/resource.rb

@@ -29,19 +29,19 @@ module Latinum
 		attr :name
 		
 		def initialize(amount, name)
-			@amount = BigDecimal(amount)
+			@amount = amount.to_d
 			@name = name
 		end
 		
 		# By default, we can only add and subtract if the name is the same
 		def + other
-			throw ArgumentError.new("Cannot operate on different currencies!") if @name != other.name
+			raise ArgumentError.new("Cannot operate on different currencies!") if @name != other.name
 			
 			self.class.new(@amount + other.amount, @name)
 		end
 		
 		def - other
-			throw ArgumentError.new("Cannot operate on different currencies!") if @name != other.name
+			raise ArgumentError.new("Cannot operate on different currencies!") if @name != other.name
 			
 			self.class.new(@amount - other.amount, @name)
 		end
@@ -54,6 +54,14 @@ module Latinum
 			self.class.new(@amount * factor, @name)
 		end
 		
+		def exchange(rate, name, precision = nil)
+			exchanged_amount = @amount * rate
+			
+			exchanged_amount = exchanged_amount.round(precision) if precision
+			
+			self.class.new(exchanged_amount, name)
+		end
+		
 		def to_s(options = {})
 			@amount.to_s('F') + ' ' + @name.to_s
 		end

data/lib/latinum/version.rb

@@ -22,7 +22,7 @@ module Latinum
 	module VERSION
 		MAJOR = 0
 		MINOR = 2
-		TINY  = 0
+		TINY  = 3
 
 		STRING = [MAJOR, MINOR, TINY].join('.')
 	end

data/test/test_bank.rb

@@ -1,13 +1,15 @@
 
 require 'helper'
 
-require 'latinum/bank'
+require 'latinum'
 require 'latinum/currencies/global'
 
 class BankTest < Test::Unit::TestCase
 	def setup
 		@bank = Latinum::Bank.new
 		@bank.import(Latinum::Currencies::Global)
+		
+		@bank << Latinum::ExchangeRate.new("NZD", "AUD", "0.5")
 	end
 	
 	def test_formatting
@@ -17,5 +19,23 @@ class BankTest < Test::Unit::TestCase
 		
 		resource = Latinum::Resource.new("391", "AUD")
 		assert_equal "$391.00 AUD", @bank.format(resource)
+		
+		resource = Latinum::Resource.new("-100", "NZD")
+		assert_equal "-$100.00 NZD", @bank.format(resource)
+	end
+	
+	def test_exchange
+		nzd = Latinum::Resource.new("10", "NZD")
+		
+		aud = @bank.exchange nzd, "AUD"
+		assert_equal Latinum::Resource.new("5", "AUD"), aud
+	end
+	
+	def test_parsing
+		assert_equal Latinum::Resource.new("5", "USD"), @bank.parse("$5")
+		assert_equal Latinum::Resource.new("5", "NZD"), @bank.parse("$5 NZD")
+		assert_equal Latinum::Resource.new("5", "EUR"), @bank.parse("€5")
+		
+		assert_equal Latinum::Resource.new("5", "NZD"), @bank.parse("5 NZD")
 	end
 end

data/test/test_collection.rb

@@ -0,0 +1,27 @@
+
+require 'helper'
+
+require 'latinum'
+require 'latinum/currencies/global'
+
+require 'set'
+
+class CollectionTest < Test::Unit::TestCase
+	def setup
+		@bank = Latinum::Bank.new
+		@bank.import(Latinum::Currencies::Global)
+	end
+	
+	def test_collections
+		resource = Latinum::Resource.new("10", "NZD")
+		
+		currencies = Set.new
+		collection = Latinum::Collection.new(currencies)
+		
+		collection << resource
+		assert_equal resource, collection["NZD"]
+		
+		collection << resource
+		assert_equal resource * 2, collection["NZD"]
+	end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: latinum
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-07-23 00:00:00.000000000 Z
+date: 2012-07-27 00:00:00.000000000 Z
 dependencies: []
 description: 
 email: samuel.williams@oriontransfer.co.nz
@@ -20,12 +20,14 @@ files:
 - lib/latinum/bank.rb
 - lib/latinum/collection.rb
 - lib/latinum/currencies/global.rb
+- lib/latinum/extensions/bigdecimal-1.8.rb
 - lib/latinum/formatters.rb
 - lib/latinum/resource.rb
 - lib/latinum/version.rb
 - lib/latinum.rb
 - test/helper.rb
 - test/test_bank.rb
+- test/test_collection.rb
 - README.md
 homepage: http://www.oriontransfer.co.nz/gems/latinum
 licenses: []