latinum 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8884a3ef10ea2656d2c0016be0a46808783d66f6b6245cfadf3df03e5352e452
-  data.tar.gz: 6ee07cd171635e5cc879b2dada4d52d2a0e31911090c125feb239093bc8850c2
+  metadata.gz: dc3529356aeebbfb020336961b359bd2a78f3473504bd8d5e81e5c19fb709f5a
+  data.tar.gz: bc57d00b4a80bf91a059709a973941a017e3c63324936942956ae5962c499640
 SHA512:
-  metadata.gz: c38564220688bd0bb5e920bf3159bfedfef3d044e5d0073d0cbb294617c3fdb5f676f2da315a5e17363e10dc406775f156614bc18a3cbebaaa58ce899fe7b880
-  data.tar.gz: cd68db69fc29c633611f3b96c7af99b29fcf1283db4ad6a861712f713863de4d2339dec789b3e1551e51b069282fea3ea4ca8a6178918bddab7d1a9b953739ca
+  metadata.gz: 134e6a9444aac017ce38d3239fbec37d11f7407324b386aa6ac3d56b06ccc9f4af2b9b7df6295382d4f33c3c7d171fdc4351da748d9ce2b8cd7993d2b01b77b2
+  data.tar.gz: 8b4b674b1ba7a8d3170c190674eecb7efb741a2814f3d0a55751794baa2f974cf098c2798b85560c1b75b56f0423005b0e7a5e2aa2a8a3d2d057cd4c0adab463

data/lib/latinum/bank.rb

@@ -23,19 +23,31 @@
 require 'latinum/resource'
 
 module Latinum
+	# A basic exchange rate for a named resource.
 	class ExchangeRate
+		# @parameter input [String] The name of the input resource.
+		# @parameter output [String] The name of the output resource.
+		# @parameter factor [Numeric] The rate of exchange.
 		def initialize(input, output, factor)
 			@input = input
 			@output = output
 			@factor = factor.to_d
 		end
 		
+		# The name of the input resource.
+		# @attribute [String]
 		attr :input
+		
+		# The name of the output resource.
+		# @attribute [String]
 		attr :output
+		
+		# The rate of exchange.
+		# @attribute [String]
 		attr :factor
 	end
 	
-	# A bank defines exchange rates and formatting rules for resources. It is a centralised location for resource related state.
+	# A bank defines exchange rates and formatting rules for resources. It is a centralised location for resource formatting and metadata.
 	class Bank
 		# Imports all given currencies.
 		def initialize(*imports)
@@ -62,7 +74,7 @@ module Latinum
 				@currencies[name] = config
 				
 				# Create a formatter:
-				@formatters[name] = config[:formatter].new(config)
+				@formatters[name] = config[:formatter].new(**config)
 				
 				if config[:symbol]
 					symbols = (@symbols[config[:symbol]] ||= [])
@@ -73,16 +85,23 @@ module Latinum
 		end
 		
 		# Look up a currency by name.
-		def [] name
+		def [](name)
 			@currencies[name]
 		end
 		
 		attr :rates
+		
+		# A map of all recognised symbols ordered by priority.
+		# @attribute [Hash(String, Tuple(Integer, Name))]
 		attr :symbols
+		
+		# The supported currents and assocaited formatting details.
+		# @attribute [Hash(String, Hash)]
 		attr :currencies
 		
 		# Add an exchange rate to the bank.
-		def << rate
+		# @parameter rate [ExchangeRate] The exchange rate to add.
+		def <<(rate)
 			@rates << rate
 			
 			@exchange[rate.input] ||= {}
@@ -91,12 +110,13 @@ module Latinum
 		
 		# Exchange one resource for another using internally specified rates.
 		def exchange(resource, for_name)
-			rate = @exchange[resource.name][for_name] rescue nil
-			raise ArgumentError.new("Rate #{rate} unavailable") if rate == nil
+			unless rate = @exchange.dig(resource.name, for_name)
+				raise ArgumentError.new("Rate #{rate} unavailable")
+			end
 			
 			config = self[for_name]
 			
-			resource.exchange(rate.factor, for_name, config[:precision])
+			return resource.exchange(rate.factor, for_name, config[:precision])
 		end
 		
 		# Parse a string according to the loaded currencies.
@@ -104,37 +124,45 @@ module Latinum
 			parts = string.strip.split(/\s+/, 2)
 			
 			if parts.size == 2
-				Resource.new(parts[0].gsub(/[^\-\.0-9]/, ''), parts[1])
+				return Resource.new(parts[0].gsub(/[^\-\.0-9]/, ''), parts[1])
 			else
 				# Lookup the named symbol, e.g. '$', and get the highest priority name:
 				symbol = @symbols.fetch(string.gsub(/[\-\.,0-9]/, ''), []).last
 				
 				if symbol
-					Resource.new(string.gsub(/[^\-\.0-9]/, ''), symbol.last.to_s)
+					return Resource.new(string.gsub(/[^\-\.0-9]/, ''), symbol.last.to_s)
 				elsif default_name
-					Resource.new(string.gsub(/[^\-\.0-9]/, ''), default_name.to_s)
+					return Resource.new(string.gsub(/[^\-\.0-9]/, ''), default_name.to_s)
 				else
 					raise ArgumentError.new("Could not parse #{string}, could not determine currency!")
 				end
 			end
 		end
 		
+		# Rounds the specified resource to the maximum precision as specified by the formatter. Whe computing things like tax, you often get fractional amounts which are unpayable because they are smaller than the minimum discrete unit of the currency. This method helps to round a currency to a payable amount.
+		# @parameter resource [Resource] The resource to round.
+		# @returns [Resource] A copy of the resource with the amount rounded as per the formatter.
 		def round(resource)
-			formatter = @formatters[resource.name]
-			raise ArgumentError.new("No formatter found for #{resource.name}") unless formatter
+			unless formatter = @formatters[resource.name]
+				raise ArgumentError.new("No formatter found for #{resource.name}")
+			end
 			
-			Latinum::Resource.new(formatter.round(resource.amount), resource.name)
+			return Resource.new(formatter.round(resource.amount), resource.name)
 		end
 		
 		# Format a resource as a string according to the loaded currencies.
-		def format(resource, *args)
-			formatter = @formatters[resource.name]
-			raise ArgumentError.new("No formatter found for #{resource.name}") unless formatter
+		# @parameter resource [Resource] The resource to format.
+		def format(resource, *arguments, **options)
+			unless formatter = @formatters[resource.name]
+				raise ArgumentError.new("No formatter found for #{resource.name}")
+			end
 			
-			formatter.format(resource.amount, *args)
+			formatter.format(resource.amount, *arguments, **options)
 		end
 		
 		# Convert the resource to an integral representation based on the currency's precision.
+		# @parameter resource [Resource] The resource to convert.
+		# @returns [Integer] The integer representation.
 		def to_integral(resource)
 			formatter = @formatters[resource.name]
 			
@@ -142,10 +170,13 @@ module Latinum
 		end
 		
 		# Convert the resource from an integral representation based on the currency's precision.
-		def from_integral(amount, resource_name)
-			formatter = @formatters[resource_name]
+		# @parameter amount [Integer] The integral resource amount.
+		# @parameter name [String] The resource name.
+		# @returns [Resource] The converted resource.
+		def from_integral(amount, name)
+			formatter = @formatters[name]
 			
-			Resource.new(formatter.from_integral(amount), resource_name)
+			Resource.new(formatter.from_integral(amount), name)
 		end
 	end
 end

data/lib/latinum/collection.rb

@@ -24,29 +24,34 @@ require 'bigdecimal'
 require 'set'
 
 module Latinum
-	# Aggregates a set of resources, typically used for summing values.
+	# Aggregates a set of resources, typically used for summing values to compute a total.
 	class Collection
 		include Enumerable
 		
 		# Initialize the collection with a given set of resource names.
 		def initialize(names = Set.new)
 			@names = names
-			@resources = Hash.new {|hash, key| @names << key; BigDecimal("0")}
+			@resources = Hash.new {|hash, key| @names << key; BigDecimal(0)}
 		end
 		
-		# All resource names which have been added to the collection, e.g. `['NZD', 'USD']`.
+		# All resource names which have been added to the collection.
+		# e.g. `['NZD', 'USD']`.
+		# @attribute [Set]
 		attr :names
 		
-		# A map of `name` => `total` for all added resources. Totals are stored as BigDecimal instances.
+		# Keeps track of all added resources.
+		# @attribute [Hash(String, BigDecimal)]
 		attr :resources
 		
 		# Add a resource into the totals.
-		def add resource
+		# @parameter resource [Resource] The resource to add.
+		def add(resource)
 			@resources[resource.name] += resource.amount
 		end
 		
 		# Add a resource, an array of resources, or another collection into this one.
-		def << object
+		# @parameter object [Resource | Array(Resource) | Collection] The resource(s) to add.
+		def <<(object)
 			case object
 			when Resource
 				add(object)
@@ -67,7 +72,8 @@ module Latinum
 			self << -other
 		end
 		
-		# Allow negation of all values within the collection:
+		# Allow negation of all values within the collection.
+		# @returns [Collection] A new collection with the inverted values.
 		def -@
 			collection = self.class.new
 			
@@ -78,16 +84,23 @@ module Latinum
 			return collection
 		end
 		
-		# Get a `Resource` for the given name:
+		# @returns [Resource | Nil] A resource for the specified name.
 		def [] key
-			Resource.new(@resources[key], key)
+			if amount = @resources[key]
+				Resource.new(@resources[key], key)
+			end
 		end
 		
-		# Set a `BigDecimal` value for the given name:
+		# Set the amount for the specified resource name.
+		# @parameter key [String] The resource name.
+		# @parameter value [BigDecimal] The resource amount.
 		def []= key, amount
 			@resources[key] = amount
 		end
 		
+		# Iterates over all the resources.
+		# @yields {|resource| ...} The resources if a block is given.
+		#		@parameter resource [Resource]
 		def each
 			return to_enum(:each) unless block_given?
 			
@@ -96,15 +109,20 @@ module Latinum
 			end
 		end
 		
+		# Whether the collection is empty.
+		# @returns [Boolean]
 		def empty?
 			@resources.empty?
 		end
 		
+		# Whether the collection contains the specified resource (may be zero).
+		# @returns [Boolean]
 		def include?(key)
 			@resources.include?(key)
 		end
 		
 		# Generate a new collection but ignore zero values.
+		# @returns [Collection] A new collection.
 		def compact
 			collection = self.class.new
 			
@@ -117,6 +135,9 @@ module Latinum
 			return collection
 		end
 		
+		# A human readable representation of the collection.
+		# e.g. `"5.0 NZD; 10.0 USD"`
+		# @returns [String]
 		def to_s
 			@resources.map{|name, amount| "#{amount.to_s('F')} #{name}"}.join("; ")
 		end

data/lib/latinum/currencies/global.rb

@@ -28,6 +28,8 @@ module Latinum
 	module Currencies
 		Global = {}
 		
+		# @name Global[:NZD]
+		# @attribute [Hash] The New Zealand Dollar configuration.
 		Global[:NZD] = {
 			:precision => 2,
 			:symbol => '$',
@@ -36,6 +38,8 @@ module Latinum
 			:formatter => Formatters::DecimalCurrencyFormatter,
 		}
 		
+		# @name Global[:GBP]
+		# @attribute [Hash] The Great British Pound configuration.
 		Global[:GBP] = {
 			:precision => 2,
 			:symbol => '£',
@@ -44,6 +48,8 @@ module Latinum
 			:formatter => Formatters::DecimalCurrencyFormatter,
 		}
 		
+		# @name Global[:AUD]
+		# @attribute [Hash] The Australian Dollar configuration.
 		Global[:AUD] = {
 			:precision => 2,
 			:symbol => '$',
@@ -52,6 +58,8 @@ module Latinum
 			:formatter => Formatters::DecimalCurrencyFormatter,
 		}
 		
+		# @name Global[:USD]
+		# @attribute [Hash] The United States Dollar configuration.
 		Global[:USD] = {
 			:precision => 2,
 			:symbol => '$',
@@ -60,6 +68,8 @@ module Latinum
 			:formatter => Formatters::DecimalCurrencyFormatter,
 		}
 		
+		# @name Global[:EUR]
+		# @attribute [Hash] The Euro configuration.
 		Global[:EUR] = {
 			:precision => 2,
 			:symbol => '€',
@@ -70,6 +80,8 @@ module Latinum
 			#:separator => ','
 		}
 		
+		# @name Global[:JPY]
+		# @attribute [Hash] The Japanese Yen configuration.
 		Global[:JPY] = {
 			:precision => 0,
 			:symbol => '¥',
@@ -78,6 +90,8 @@ module Latinum
 			:formatter => Formatters::DecimalCurrencyFormatter
 		}
 		
+		# @name Global[:BTC]
+		# @attribute [Hash] The Bitcoin configuration.
 		Global[:BTC] = {
 			:precision => 8,
 			:symbol => 'B⃦',

data/{spec/latinum/comparison_spec.rb → lib/latinum/error.rb}

@@ -20,23 +20,11 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
-require 'latinum/resource'
-
-RSpec.describe Latinum::Resource do
-	it "should be comparable to numeric values" do
-		resource = Latinum::Resource.load("10 NZD")
-		
-		expect(resource).to be < 20
-		expect(resource).to be > 5
-		expect(resource).to be == 10
-	end
-	
-	it "should compare with nil" do
-		a = Latinum::Resource.load("10 NZD")
-		
-		expect{a <=> nil}.to_not raise_exception
-		expect{a == nil}.to_not raise_exception
-		expect(a <=> nil).to be == nil
-		expect(a == nil).to be == false
+module Latinum
+	# Represents an error when trying to perform arithmetic on differently named resources.
+	class DifferentResourceNameError < ArgumentError
+		def initialize
+			super "Cannot operate on different currencies!"
+		end
 	end
 end

data/lib/latinum/formatters.rb

@@ -22,76 +22,93 @@
 
 module Latinum
 	module Formatters
-		DEFAULT_OPTIONS = {
-		}
-		
+		# Formats a currency using a standard decimal notation.
 		class PlainFormatter
 			def initialize(name:)
 				@name = name
 			end
 			
+			# Formats the amount using a general notation.
+			# e.g. "5.0 NZD".
+			# @returns [String] The formatted string.
 			def format(amount)
 				"#{amount.to_s('F')} #{@name}"
 			end
 			
+			# Converts the amount directly to an integer, truncating any decimal part.
+			# @parameter amount [BigDecimal] The amount to convert to an integral.
+			# @returns [Integer] The converted whole number integer.
 			def to_integral(amount)
 				amount.to_i
 			end
 			
+			# Converts the amount to a decimal.
+			# @parameter amount [Integer] The amount to convert to a decimal.
+			# @returns [BigDecimal] The converted amount.
 			def from_integral(amount)
 				amount.to_d
 			end
 		end
-
+		
+		# Formats a currency using a standard decimal notation.
 		class DecimalCurrencyFormatter
-			def initialize(options = {})
+			def initialize(**options)
 				@symbol = options[:symbol] || '$'
 				@separator = options[:separator] || '.'
 				@delimeter = options[:delimter] || ','
 				@places = options[:precision] || 2
 				@zero = options[:zero] || '0'
-
+				
 				@name = options[:name]
 			end
-
+			
 			def round(amount)
 				return amount.round(@places)
 			end
-
-			def format(amount, options = DEFAULT_OPTIONS)
+			
+			# Formats the amount using the configured symbol, separator, delimeter, and places.
+			# e.g. "$5,000.00 NZD". Rounds the amount to the specified number of decimal places.
+			# @returns [String] The formatted string.
+			def format(amount, **options)
 				# Round to the desired number of places. Truncation used to be the default.
 				amount = amount.round(@places)
 				
-				fix, frac = amount.abs.to_s('F').split(/\./, 2)
-
+				integral, fraction = amount.abs.to_s('F').split(/\./, 2)
+				
 				# The sign of the number
 				sign = '-' if amount < 0
-
+				
 				# Decimal places, e.g. the '.00' in '$10.00'
-				frac = frac[0...@places].ljust(@places, @zero)
-
+				fraction = fraction[0...@places].ljust(@places, @zero)
+				
 				# Grouping, e.g. the ',' in '$10,000.00'
-				remainder = fix.size % 3
-				groups = fix[remainder..-1].scan(/.{3}/).to_a
-				groups.unshift(fix[0...remainder]) if remainder > 0
-
+				remainder = integral.size % 3
+				groups = integral[remainder..-1].scan(/.{3}/).to_a
+				groups.unshift(integral[0...remainder]) if remainder > 0
+				
 				symbol = options.fetch(:symbol, @symbol)
 				value = "#{sign}#{symbol}#{groups.join(@delimeter)}"
-
+				
 				name = options.fetch(:name, @name)
 				suffix = name ? " #{name}" : ''
-
+				
 				if @places > 0
-					"#{value}#{@separator}#{frac}#{suffix}"
+					"#{value}#{@separator}#{fraction}#{suffix}"
 				else
 					"#{value}#{suffix}"
 				end
 			end
 			
+			# Converts the amount directly to an integer, truncating any decimal part, taking into account the number of specified decimal places.
+			# @parameter amount [BigDecimal] The amount to convert to an integral.
+			# @returns [Integer] The converted whole number integer.
 			def to_integral(amount)
 				(amount * 10**@places).to_i
 			end
 			
+			# Converts the amount to a decimal, taking into account the number of specified decimal places.
+			# @parameter amount [Integer] The amount to convert to a decimal.
+			# @returns [BigDecimal] The converted amount.
 			def from_integral(amount)
 				(amount.to_d / 10**@places)
 			end