minting 1.1.0 → 1.1.1

data/lib/minting/mint/currency.rb

@@ -3,7 +3,7 @@ module Mint
   #
   # @see https://www.iso.org/iso-4217-currency-codes.html
   class Currency
-    attr_reader :code, :subunit, :symbol, :priority, :minimum_amount
+    attr_reader :code, :subunit, :symbol, :priority, :minimum_amount, :country, :name
 
     def inspect
       "<Currency:(#{code} #{symbol} #{subunit})>"
@@ -11,12 +11,14 @@ module Mint
 
     private
 
-    def initialize(code, subunit:, symbol:, priority: 0)
+    def initialize(code:, symbol:, subunit: 0, priority: 0, country: nil, name: nil)
       @code = code.to_s
       @subunit = subunit.to_i
-      @symbol = symbol.to_s
+      @symbol = symbol
       @priority = priority.to_i
-      @minimum_amount = 10r**-subunit
+      @country = country
+      @name = name
+      @minimum_amount = 10r**-@subunit
       freeze
     end
   end

data/lib/minting/mint/registry.rb

@@ -1,7 +1,12 @@
 require 'yaml'
 
-# :nodoc
 module Mint
+  # Creates a new {Money} instance with the given amount and currency code.
+  #
+  # @param amount [Numeric] the financial value
+  # @param currency_code [String, Symbol] the ISO currency code or symbol
+  # @return [Money] the instantiated Money object
+  # @raise [ArgumentError] if the currency code is not registered
   def self.money(amount, currency_code)
     currency = currency(currency_code)
     return Money.new(amount, currency) if currency
@@ -9,6 +14,11 @@ module Mint
     raise ArgumentError, "Currency [#{currency_code}] not registered. Check Mint.currencies"
   end
 
+  # Finds a registered currency by its code, symbol,
+  # or retrieves it directly if already a Currency object.
+  #
+  # @param currency [String, Symbol, Currency] the currency identifier or object
+  # @return [Currency, nil] the registered Currency instance or nil if not found
   def self.currency(currency)
     case currency
     when Currency
@@ -20,13 +30,29 @@ module Mint
     end
   end
 
-  def self.register_currency(code, subunit: 2, symbol: '$', priority: 0)
+  # Registers a new currency if not already registered.
+  #
+  # @param code [String, Symbol] the unique currency code (e.g. 'USD', :EUR)
+  # @param subunit [Integer] the decimal subunit precision (defaults to 2)
+  # @param symbol [String] the display symbol (defaults to '$')
+  # @param priority [Integer] parser precedence priority (defaults to 0)
+  # @return [Currency] the registered or existing Currency instance
+  # @raise [ArgumentError] if the code layout is invalid or register throws an error
+  def self.register_currency(code:, subunit: 2, symbol: '$', priority: 0)
     code = code.to_s
-    currencies[code] || register_currency!(code, subunit: subunit, symbol: symbol,
-                                                 priority: priority)
+    currencies[code] || register_currency!(code:, subunit:, symbol:, priority:)
   end
 
-  def self.register_currency!(code, subunit:, symbol: '', priority: 0)
+  # Strictly registers a new currency, raising a KeyError if already registered.
+  #
+  # @param code [String, Symbol] the unique currency code
+  # @param subunit [Integer] the decimal subunit precision
+  # @param symbol [String] the display symbol
+  # @param priority [Integer] parser precedence priority
+  # @return [Currency] the newly registered Currency instance
+  # @raise [ArgumentError] if the code contains invalid characters
+  # @raise [KeyError] if the currency code is already registered
+  def self.register_currency!(code:, subunit:, symbol: '', priority: 0)
     code = code.to_s
     unless code.match?(/^[A-Z_]+$/)
       raise ArgumentError,
@@ -37,14 +63,19 @@ module Mint
             "Currency: #{code} already registered"
     end
 
-    currencies[code] =
-      Currency.new(code, subunit: subunit, symbol: symbol, priority: priority)
+    currencies[code] = Currency.new(code:, subunit:, symbol:, priority:)
     @currency_symbols = nil
     currencies[code]
   end
 
+  # Returns the hash of all registered currencies.
+  #
+  # @return [Hash{String => Currency}] registered currencies mapped by code
   def self.currencies
-    @currencies ||= load_currencies
+    @currencies ||= begin
+      registry = { 'XXX' => Currency.new(code: 'XXX', name: 'No currency', symbol: '¤') }
+      load_currencies(registry)
+    end
   end
 
   # Registered symbols sorted for detection: longest match wins, then parser priority.
@@ -57,16 +88,23 @@ module Mint
     end.freeze
   end
 
-  def self.load_currencies
-    path = File.expand_path('../data/currencies.yaml', __dir__)
-    YAML.load_file(path).each_with_object({}) do |(code, attrs), registry|
+  def self.load_currencies(registry)
+    base = File.expand_path('../data', __dir__)
+    path = File.join(base, 'currencies.yaml')
+
+    data = YAML.load_file(path)
+    data.each do |entry|
+      code = entry['code']
       registry[code] = Currency.new(
-        code,
-        subunit: attrs['subunit'],
-        symbol: attrs['symbol'],
-        priority: attrs['priority']
+        code: code,
+        subunit: entry['subunit'],
+        symbol: entry['symbol'],
+        priority: entry['priority'],
+        country: entry['country'],
+        name: entry['name']
       )
     end
+    registry
   end
 
   private_class_method :load_currencies

data/lib/minting/money/allocation.rb

@@ -1,7 +1,14 @@
 module Mint
-  # :nodoc
-  # split and allocation methods
   class Money
+    # Proportionally allocates the monetary amount among a list of ratios.
+    # Disperses any subunit rounding amounts across the initial slots
+    # @param proportions [Array<Numeric>] a list of numeric proportions/ratios to allocate by
+    # @return [Array<Money>] the list of newly allocated Money objects
+    # @raise [ArgumentError] if the proportions list is empty or sums to zero
+    #
+    # @example Proportional allocation
+    #   money = Mint.money(10.00, 'USD')
+    #   money.allocate([1, 2, 3]) #=> [[USD 1.67], [USD 3.33], [USD 5.00]]
     def allocate(proportions)
       whole = proportions.sum.to_r
       raise ArgumentError, 'Need at least 1 proportion element' if proportions.empty?
@@ -11,6 +18,17 @@ module Mint
       allocate_left_over!(amounts: amounts, left_over: amount - amounts.sum)
     end
 
+    # Splits the monetary amount into a given quantity of equal parts.
+    # Disperses any fractional subunit rounding differences across the initial slots
+    # so that the sum is preserved.
+    #
+    # @param quantity [Integer] the number of equal parts to divide the money into (must be > 0)
+    # @return [Array<Money>] the list of newly split Money objects
+    # @raise [ArgumentError] if quantity is not a positive integer
+    #
+    # @example Even split
+    #   money = Mint.money(10.00, 'USD')
+    #   money.split(3) #=> [[USD 3.34], [USD 3.33], [USD 3.33]]
     def split(quantity)
       unless  quantity.positive? && quantity.integer?
         raise ArgumentError,

data/lib/minting/money/arithmetics.rb

@@ -1,15 +1,31 @@
 module Mint
-  # :nodoc
-  # Arithmetic functions for money objects
   class Money
+    # Returns the absolute value of the monetary amount as a new {Money} instance.
+    #
+    # @return [Money] the absolute value
     def abs =     mint(amount.abs)
 
+    # Returns true if the monetary amount is less than zero.
+    #
+    # @return [Boolean] true if negative, false otherwise
     def negative? = amount.negative?
 
+    # Returns true if the monetary amount is greater than zero.
+    #
+    # @return [Boolean] true if positive, false otherwise
     def positive? = amount.positive?
 
+    # Returns the successor of the Money instance by adding the minimum possible subunit amount.
+    # Enables standard ranges and stepping (e.g. `1.dollar..10.dollars`).
+    #
+    # @return [Money] successor Money instance
     def succ = mint(amount + currency.minimum_amount)
 
+    # Performs addition with another {Money} instance or standard zero Numeric.
+    #
+    # @param addend [Money, Numeric] the value to add
+    # @return [Money] the sum of the addition
+    # @raise [TypeError] if addition involves a different currency or incompatible types
     def +(addend)
       return self if addend.respond_to?(:zero?) && addend.zero?
       return mint(amount + addend.amount) if addend.is_a?(Money) && same_currency?(addend)
@@ -17,6 +33,11 @@ module Mint
       raise TypeError, "#{addend} can't be added to #{self}"
     end
 
+    # Performs subtraction with another {Money} instance or standard zero Numeric.
+    #
+    # @param subtrahend [Money, Numeric] the value to subtract
+    # @return [Money] the difference of the subtraction
+    # @raise [TypeError] if subtraction involves a different currency or incompatible types
     def -(subtrahend)
       return self if subtrahend.respond_to?(:zero?) && subtrahend.zero?
       if subtrahend.is_a?(Money) && same_currency?(subtrahend)
@@ -26,16 +47,30 @@ module Mint
       raise TypeError, "#{subtrahend} can't be subtracted from #{self}"
     end
 
+    # Unary negation operator. Returns a new {Money} instance with the inverted sign.
+    #
+    # @return [Money] negated Money instance
     def -@
       mint(-amount)
     end
 
+    # Performs multiplication of the monetary value by a standard scalar Numeric.
+    #
+    # @param multiplicand [Numeric] the scalar multiplier
+    # @return [Money] the multiplied Money instance
+    # @raise [TypeError] if multiplier is not Numeric or is a Money object
     def *(multiplicand)
       return mint(amount * multiplicand.to_r) if multiplicand.is_a?(Numeric)
 
       raise TypeError, "#{self} can't be multiplied by #{multiplicand}"
     end
 
+    # Performs division of the monetary value by a scalar Numeric or identical currency {Money}.
+    #
+    # @param divisor [Numeric, Money] the divisor
+    # @return [Money, Numeric] a new Money (scalar division) or a numeric ratio (Money division)
+    # @raise [TypeError] if divisor is of incompatible type or different currency
+    # @raise [ZeroDivisionError] if division by zero is attempted
     def /(divisor)
       return mint(amount / divisor) if divisor.is_a?(Numeric)
       return amount / divisor.amount if same_currency? divisor

data/lib/minting/money/coercion.rb

@@ -1,40 +1,50 @@
 module Mint
-  # :nodoc
-  # Coercion logic
   class Money
+    # Implements the standard Ruby coercion protocol.
+    # Allows {Money} to interact seamlessly as the right-hand operand in Numeric arithmetic.
+    #
+    # @param other [Numeric] the left-hand operand to coerce
+    # @return [Array(CoercedNumber, Money)] coerced operand array
     def coerce(other)
       [CoercedNumber.new(other), self]
     end
 
-    # :nodoc
+    # @private
     # Coerced Number contains the arithmetic logic for numeric compatible ops.
+    # @private
     class CoercedNumber
       include Comparable
 
+      # @private
       def initialize(value)
         @value = value
       end
 
+      # @private
       def +(other)
         return other if @value.zero?
 
         raise_coercion_error(:+, other)
       end
 
+      # @private
       def -(other)
         return -other if @value.zero?
 
         raise_coercion_error(:-, other)
       end
 
+      # @private
       def *(other)
         other.mint(@value * other.amount)
       end
 
+      # @private
       def /(other)
         raise_coercion_error(:/, other)
       end
 
+      # @private
       def <=>(other)
         return nil if @value.nil? || other.nil?
         return @value <=> other.amount if @value.zero? || other.zero?
@@ -42,6 +52,7 @@ module Mint
         raise_coercion_error(:<=>, other)
       end
 
+      # @private
       def raise_coercion_error(operation, operand)
         raise TypeError,
               "#{self} #{operation} #{operand} : incompatible operands"

data/lib/minting/money/comparable.rb

@@ -7,9 +7,14 @@ module Mint
     # @return true if both are zero, or both have same amount and same currency
     def ==(other)
       return true if zero? && other.respond_to?(:zero?) && other.zero?
-      return false unless other.is_a?(Mint::Money)
 
-      amount == other.amount && currency == other.currency
+      eql?(other)
+    end
+
+    def eql?(other)
+      other.is_a?(Mint::Money) &&
+        amount == other.amount &&
+        currency == other.currency
     end
 
     # @example
@@ -31,16 +36,8 @@ module Mint
       raise TypeError, "#{inspect} can't be compared to #{other.inspect}"
     end
 
-    def eql?(other)
-      self == other
-    end
-
-    def nonzero?
-      amount.nonzero?
-    end
+    def nonzero? = amount.nonzero?
 
-    def zero?
-      amount.zero?
-    end
+    def zero? = amount.zero?
   end
 end

data/lib/minting/money/conversion.rb

@@ -1,28 +1,48 @@
 require 'erb'
 
 module Mint
-  # Conversion logic
+  # Conversion and serialization logic for {Money} instances.
   class Money
+    # Converts the monetary amount to a {BigDecimal} object.
+    #
+    # @return [BigDecimal] the decimal representation of the money amount
+    # @raise [NoMethodError] if the bigdecimal gem is not loaded/available
     def to_d
       raise NoMethodError, 'decimal gem required' unless defined?(BigDecimal)
 
       amount.to_d 0
     end
 
+    # Converts the monetary amount to a standard float.
+    # Note: Using float conversion loses precision guarantees.
+    #
+    # @return [Float] the floating-point representation of the money amount
     def to_f
       amount.to_f
     end
 
+    # Renders a safe HTML5 `<data>` element containing the formatted currency.
+    # Embeds the ISO currency description and raw value as the metadata `title` attribute.
+    #
+    # @param format [String] the display format to apply to the visible HTML text
+    # @return [String] HTML5 `<data>` representation
     def to_html(format = DEFAULT_FORMAT)
       title = Kernel.format("#{currency_code} %0.#{currency.subunit}f", amount)
       body = to_s(format: format)
       %(<data class='money' title='#{ERB::Util.html_escape(title)}'>#{ERB::Util.html_escape(body)}</data>)
     end
 
+    # Truncates and converts the monetary amount to an Integer.
+    #
+    # @return [Integer] the integer representation of the money amount
     def to_i
       amount.to_i
     end
 
+    # Serializes the money instance to a standard JSON object containing the amount and currency.
+    # Highly optimized to run without external dependencies.
+    #
+    # @return [String] the JSON serialized string representation
     def to_json(*_args)
       subunit = currency.subunit
       Kernel.format(
@@ -31,6 +51,9 @@ module Mint
       )
     end
 
+    # Returns the exact internal Rational representation of the monetary amount.
+    #
+    # @return [Rational] the rational representation of the money amount
     def to_r
       amount
     end

data/lib/minting/money/formatting.rb

@@ -11,7 +11,7 @@ module Mint
     # @example Basic formatting
     #   money = Mint.money(1234.56, 'USD')
     #   money.to_s                               #=> "$1,234.56"
-    #   money.to_s(thousand: '.', decimal: ',')  #=> "$.1234,56"
+    #   money.to_s(thousand: '.', decimal: ',')  #=> "$1.234,56"
     #   money.to_s(decimal: ',', thousand: '')   #=> "$1234,56"
     #
     # @example Custom formats
@@ -41,6 +41,8 @@ module Mint
       formatted
     end
 
+    private
+
     def format_amount(format)
       format = { positive: format } if format.is_a?(String)
       value = amount

data/lib/minting/money/money.rb

@@ -1,5 +1,7 @@
 module Mint
   class Money
+    # The default display format pattern for formatting monetary values.
+    # Uses `%<symbol>s` for the currency symbol and `%<amount>f` for the rounded amount.
     DEFAULT_FORMAT = '%<symbol>s%<amount>f'.freeze
 
     attr_reader :amount, :currency
@@ -10,24 +12,22 @@ module Mint
     # @raise [ArgumentError] If amount is not numeric or currency is invalid
     def initialize(amount, currency)
       raise ArgumentError, 'amount must be Numeric' unless amount.is_a?(Numeric)
-
-      unless currency.is_a?(Currency)
-        raise ArgumentError,
-              'currency must be a Currency object'
-      end
+      raise ArgumentError, 'currency must be a Currency object' unless currency.is_a?(Currency)
 
       @amount = amount.to_r.round(currency.subunit)
       @currency = currency
       freeze
     end
 
-    def currency_code
-      currency.code
-    end
+    # Returns the ISO 3-letter currency code string.
+    #
+    # @return [String] the ISO currency code
+    def currency_code = currency.code
 
-    def hash
-      zero? ? 0.hash : [amount, currency.code].hash
-    end
+    # Generates a stable hash key for Money instances.
+    #
+    # @return [Integer] the calculated hash value
+    def hash = [amount, currency_code].hash
 
     # Returns a new Money object with the specified amount, or self if unchanged
     # @param new_amount [Numeric] The new amount
@@ -36,12 +36,20 @@ module Mint
       new_amount.to_r == amount ? self : Money.new(new_amount, currency)
     end
 
+    # Returns a standard developer-oriented string inspection of the Money object.
+    #
+    # @return [String] the formatted inspect representation
     def inspect
       Kernel.format "[#{currency_code} %0.#{currency.subunit}f]", amount
     end
 
-    def same_currency?(other)
-      other.respond_to?(:currency) && other.currency == currency
-    end
+    # Helper method to verify if another object has the identical currency.
+    #
+    # @param other [Object] the target object to compare
+    # @return [Boolean] true if currencies match, false otherwise
+    def same_currency?(other) = other.respond_to?(:currency) && other.currency == currency
+
+    # Returns default zero no currency money
+    def self.zero = @zero ||= new(0, Mint.currencies('XXX'))
   end
 end

data/lib/minting/version.rb

@@ -1,3 +1,5 @@
+# Root namespace for the Minting library.
 module Minting
-  VERSION = '1.1.0'.freeze
+  # Current version of the Minting gem.
+  VERSION = '1.1.1'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: minting
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Gilson Ferraz