minting 1.3.0 → 1.5.0

data/lib/minting/mint/currency.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Mint
   # Represents a specific currency unit, identified by ISO 4217 alphabetic code
   #
@@ -8,25 +10,24 @@ module Mint
                 :fractional_multiplier, :minimum_amount,
                 :name, :priority
 
-    def inspect
-      "<Currency:(#{code} #{symbol} #{subunit})>"
-    end
+    def inspect = "<Currency:(#{code} #{symbol} #{subunit} #{name})>"
 
-    def normalize_amount(amount)
-      amount.to_r.round(subunit)
-    end
+    # Normalizes numeric amounts for this currency
+    # 1. Converts to Rational
+    # 2. Rounds to respect currency subunit
+    def normalize_amount(amount) = amount.to_r.round(subunit)
 
     private
 
     def initialize(code:, symbol:, subunit: 0, priority: 0, country: nil, name: nil)
-      @code = code.to_s
+      @code = code
       @subunit = subunit.to_i
       @symbol = symbol
       @priority = priority.to_i
       @country = country
       @name = name
       @fractional_multiplier = 10**@subunit
-      @minimum_amount = 1r / fractional_multiplier
+      @minimum_amount = Rational(1, fractional_multiplier)
       freeze
     end
   end

data/lib/minting/mint/currency_store.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+# Mint currency store (internal)
+module Mint
+  # Internal currency storage and loading.
+  # Manages the registry cache and currency symbol lookups.
+  module CurrencyStore
+    # Returns the hash of all registered currencies.
+    #
+    # @return [Hash{String => Currency}] registered currencies mapped by code
+    # @api private
+    def self.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.
+    #
+    # @return [Array<Array<String, Currency>>] sorted symbol-to-currency mappings
+    # @api private
+    def self.currency_symbols
+      @currency_symbols ||= begin
+        currencies.values
+                  .reject { |currency| currency.symbol.empty? }
+                  .map { |currency| [currency.symbol, currency] }
+                  .sort_by { |symbol, currency| [-symbol.length, -currency.priority] }
+      end.freeze
+    end
+
+    # Clears and refreshes the currency symbol cache.
+    # Called when currencies are registered.
+    #
+    # @api private
+    def self.invalidate_symbols_cache
+      @currency_symbols = nil
+    end
+
+    # Loads currencies from YAML file into the registry.
+    #
+    # @param registry [Hash] the registry hash to populate
+    # @return [Hash] the populated registry
+    # @api private
+    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: code,
+          subunit: entry['subunit'],
+          symbol: entry['symbol'],
+          priority: entry['priority'],
+          country: entry['country'],
+          name: entry['name']
+        )
+      end
+      registry
+    end
+
+    private_class_method :load_currencies
+  end
+end

data/lib/minting/mint/refinements.rb

@@ -1,4 +1,6 @@
-# Mint is a library to operate with monetary values
+# frozen_string_literal: true
+
+# Mint refinements
 module Mint
   refine Numeric do
     def reais

data/lib/minting/mint/registry.rb

@@ -1,17 +1,18 @@
-require 'yaml'
+# frozen_string_literal: true
 
+# Mint currency registration and factory (public API)
 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
+  # @param currency_code [String] the ISO currency code
   # @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.create(amount, currency) if currency
 
-    raise ArgumentError, "[#{currency.inspect}] is not a registered currency. Check Mint.currencies"
+    raise ArgumentError, "[#{currency.inspect}] is not a registered currency."
   end
 
   # Returns default zero, no currency money
@@ -20,35 +21,27 @@ module Mint
   # 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
+  # @param currency [String, 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
-      currency
-    when Symbol
-      currencies[currency.to_s]
-    else
-      currencies[currency]
-    end
+    currency.is_a?(Currency) ? currency : CurrencyStore.currencies[currency]
   end
 
   # Registers a new currency if not already registered.
   #
-  # @param code [String, Symbol] the unique currency code (e.g. 'USD', :EUR)
+  # @param code [String] 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:, symbol:, priority:)
+  def self.register_currency(code:, subunit: 0, symbol: '', priority: 0)
+    CurrencyStore.currencies[code] || register_currency!(code:, subunit:, symbol:, priority:)
   end
 
   # Strictly registers a new currency, raising a KeyError if already registered.
   #
-  # @param code [String, Symbol] the unique currency code
+  # @param code [String] the unique currency code
   # @param subunit [Integer] the decimal subunit precision
   # @param symbol [String] the display symbol
   # @param priority [Integer] parser precedence priority
@@ -56,59 +49,26 @@ module Mint
   # @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
+    raise ArgumentError, 'Currency code must be String' unless code.is_a? String
     unless code.match?(/^[A-Z_]+$/)
       raise ArgumentError,
-            "Currency code must be String or Symbol ('USD', :EUR, 'FUEL', 'MY_COIN')"
-    end
-    if currencies[code]
-      raise KeyError,
-            "Currency: #{code} already registered"
+            "Currency code must only letters or '_' ('USD',, 'MY_COIN')"
     end
 
+    currencies = CurrencyStore.currencies
+    raise KeyError, "Currency: #{code} already registered" if currencies[code]
+
     currency = currencies[code] = Currency.new(code:, subunit:, symbol:, priority:)
-    @currency_symbols = nil
+    CurrencyStore.invalidate_symbols_cache
     currency
   end
 
-  # Returns the hash of all registered currencies.
-  #
-  # @return [Hash{String => Currency}] registered currencies mapped by code
-  def self.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.
+  # Internal API - used by Money parser.
+  #
+  # @return [Array<Array<String, Currency>>] sorted symbol-to-currency mappings
+  # @api private
   def self.currency_symbols
-    @currency_symbols ||= begin
-      currencies.values
-                .map { |currency| [currency.symbol, currency] }
-                .reject { |symbol, _| symbol.empty? }
-                .sort_by { |symbol, currency| [-symbol.length, -currency.priority] }
-    end.freeze
-  end
-
-  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: code,
-        subunit: entry['subunit'],
-        symbol: entry['symbol'],
-        priority: entry['priority'],
-        country: entry['country'],
-        name: entry['name']
-      )
-    end
-    registry
+    CurrencyStore.currency_symbols
   end
-
-  private_class_method :load_currencies
 end

data/lib/minting/mint.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
 require 'minting/mint/currency'
-require 'minting/mint/refinements'
+require 'minting/mint/currency_store'
 require 'minting/mint/registry'
+require 'minting/mint/refinements'

data/lib/minting/money/allocation.rb

@@ -1,4 +1,7 @@
+# frozen_string_literal: true
+
 module Mint
+  # Allocation and splitting
   class Money
     # Proportionally allocates the monetary amount among a list of ratios.
     # Disperses any subunit rounding amounts across the initial slots
@@ -50,7 +53,7 @@ module Mint
         last_slot = (left_over / minimum).to_i - 1
         (0..last_slot).each { |slot| amounts[slot] += minimum }
       end
-      amounts.map { Money.new(it, currency) }
+      amounts.map { |amount| Money.new(amount, currency) }
     end
   end
 end

data/lib/minting/money/arithmetics.rb

@@ -1,4 +1,7 @@
+# frozen_string_literal: true
+
 module Mint
+  # Money Arithmetics
   class Money
     # Returns the absolute value of the monetary amount as a new {Money} instance.
     #
@@ -27,9 +30,10 @@ module Mint
     # @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)
-
+      case addend
+      when 0     then return self
+      when Money then return mint(amount + addend.amount) if same_currency?(addend)
+      end
       raise TypeError, "#{addend} can't be added to #{self}"
     end
 
@@ -39,11 +43,10 @@ module Mint
     # @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)
-        return mint(amount - subtrahend.amount)
+      case subtrahend
+      when 0     then return self
+      when Money then return mint(amount - subtrahend.amount) if same_currency?(subtrahend)
       end
-
       raise TypeError, "#{subtrahend} can't be subtracted from #{self}"
     end
 
@@ -72,10 +75,22 @@ module Mint
     # @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
-
+      case divisor
+      when Numeric then return mint(amount / divisor)
+      when Money   then return amount / divisor.amount if same_currency? divisor
+      end
       raise TypeError, "#{self} can't be divided by #{divisor}"
     end
+
+    # Performs exponentiation of the monetary value by a standard scalar Numeric.
+    #
+    # @param exponent [Numeric]
+    # @return [Money] reult of amount ** exponent
+    # @raise [TypeError] if exponent is not Numeric
+    def **(exponent)
+      return mint(amount**exponent) if exponent.is_a?(Numeric)
+
+      raise TypeError, "#{self} can't be powered by #{exponent}"
+    end
   end
 end

data/lib/minting/money/coercion.rb

@@ -1,6 +1,8 @@
+# frozen_string_literal: true
+
 module Mint
+  # Implements the standard Ruby coercion protocol.
   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

data/lib/minting/money/comparable.rb

@@ -1,5 +1,6 @@
+# frozen_string_literal: true
+
 module Mint
-  # :nodoc
   # Comparison methods
   class Money
     include Comparable
@@ -28,12 +29,10 @@ module Mint
     #
     def <=>(other)
       case other
-      when Numeric
-        return amount <=> other if other.zero?
-      when Mint::Money
-        return amount <=> other.amount if currency == other.currency
+      in 0                                    then amount <=> other
+      in Mint::Money if same_currency?(other) then amount <=> other.amount
+      else                                    raise TypeError, "#{inspect} can't be compared to #{other.inspect}"
       end
-      raise TypeError, "#{inspect} can't be compared to #{other.inspect}"
     end
 
     def nonzero? = amount.nonzero?

data/lib/minting/money/constructors.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Mint
+  # Money constructors
+  class Money
+    # Creates a new Money immutable object with the specified amount and currency
+    # @param amount [Numeric] The monetary amount
+    # @param currency [Currency] The currency object
+    # @raise [ArgumentError] If amount is not numeric or currency is invalid
+    def self.create(amount, currency)
+      raise ArgumentError, 'amount must be Numeric' unless amount.is_a?(Numeric)
+
+      checked_currency = Mint.currency(currency)
+      raise ArgumentError, "Currency not found (#{currency})" unless checked_currency
+
+      new(checked_currency.normalize_amount(amount), checked_currency)
+    end
+
+    # Builds a Money from a fractional (smallest-unit) Integer amount.
+    # This is the inverse of {#fractional}: for USD, the fractional unit is
+    # 1 cent; for JPY it is 1 yen; for IQD it is 1 dinar (subunit 3).
+    #
+    # @param fractional [Integer] the amount expressed in the currency's
+    #   smallest unit (e.g. cents). Must be an Integer to preserve exactness.
+    # @param currency [String, Symbol, Currency] the currency identifier
+    # @return [Money] the resulting Money instance
+    # @raise [ArgumentError] if +fractional+ is not an Integer or +currency+
+    #   is not registered
+    #
+    # @example USD cents
+    #   Money.from_fractional(123_456, 'USD') #=> [USD 1234.56]
+    # @example JPY (subunit 0)
+    #   Money.from_fractional(1234, 'JPY')    #=> [JPY 1234]
+    # @example Round trip
+    #   m = Mint.money(9.99, 'USD')
+    #   Money.from_fractional(m.fractional, 'USD') == m #=> true
+    def self.from_fractional(fractional, currency)
+      raise ArgumentError, 'fractional must be an Integer' unless fractional.is_a?(Integer)
+
+      checked_currency = Mint.currency(currency)
+      raise ArgumentError, "Currency not found (#{currency})" unless checked_currency
+
+      amount = Rational(fractional, checked_currency.fractional_multiplier)
+      new(amount, checked_currency)
+    end
+
+    # Returns a new Money object with the specified amount, or self if unchanged
+    # @param new_amount [Numeric] The new amount
+    # @return [Money] A new Money object or self
+    def mint(new_amount)
+      new_amount = currency.normalize_amount(new_amount)
+      new_amount == amount ? self : Money.new(new_amount, currency)
+    end
+
+    private
+
+    # Initializes a new Money object with the given amount and currency.
+    # @param amount [Numeric] The monetary amount
+    # @param currency [Currency] The currency object
+    def initialize(amount, currency)
+      @amount = amount
+      @currency = currency
+      freeze
+    end
+  end
+end

data/lib/minting/money/conversion.rb

@@ -1,25 +1,21 @@
+# frozen_string_literal: true
+
+require 'bigdecimal'
 require 'erb'
 
 module Mint
   # Conversion and serialization logic for {Money} instances.
   class Money
-    # Converts the monetary amount to a {BigDecimal} object.
+    # 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
+    def to_d = amount.to_d 0
 
     # 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
+    def to_f = amount.to_f
 
     # Renders a safe HTML5 `<data>` element containing the formatted currency.
     # Embeds the ISO currency description and raw value as the metadata `title` attribute.
@@ -29,15 +25,13 @@ module Mint
     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>)
+      %(<data class='money' title='#{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
+    def to_i = amount.to_i
 
     def to_hash
       { currency: currency_code, amount: Kernel.format("%0.#{currency.subunit}f", amount) }
@@ -56,8 +50,6 @@ module Mint
     # Returns the exact internal Rational representation of the monetary amount.
     #
     # @return [Rational] the rational representation of the money amount
-    def to_r
-      amount
-    end
+    def to_r = amount
   end
 end

data/lib/minting/money/formatting.rb

@@ -1,13 +1,27 @@
+# frozen_string_literal: true
+
 module Mint
   # Formatting functionality for Money objects
   class Money
     # Formats money as a string with customizable format, thousand delimiter, and decimal
     #
-    # @param format [String] Format string with placeholders: %<symbol>s, %<amount>f, %<currency>s
+    # @param format [String, Hash] Either a Format string with placeholders
+    #   (%<symbol>s, %<amount>f, %<currency>s), or a Hash with per-sign keys
+    #   (:positive, :negative, :zero) each holding a format string. A Hash
+    #   is convenient for sign-aware formats such as accounting parentheses:
+    #
+    #     money.to_s(format: { negative: '(%<symbol>s%<amount>f)' })
+    #
+    #   Missing keys fall back to the module default, so a Hash with only
+    #   :negative will still format positives sensibly. The valid keys are
+    #   :positive, :negative, :zero; anything else raises ArgumentError.
     # @param thousand [String, false] Thousands delimiter (e.g., ',' for 1,000)
     # @param decimal [String] Decimal separator (e.g., '.' or ',')
     # @return [String] Formatted money string
     #
+    # @raise [ArgumentError] if +format+ is not a String or Hash, the Hash
+    #   is empty, or the Hash contains an unrecognised key.
+    #
     # @example Basic formatting
     #   money = Mint.money(1234.56, 'USD')
     #   money.to_s                               #=> "$1,234.56"
@@ -20,12 +34,22 @@ module Mint
     #   money.to_s(format: '%<amount>f %<symbol>s')         #=> "1234.56 $"
     #   money.to_s(format: '%<symbol>s%<amount>+f')         #=> "$+1234.56"
     #
+    # @example Per-sign Hash format (accounting parentheses)
+    #   loss = Mint.money(-1234.56, 'USD')
+    #   loss.to_s(format: { negative: '(%<symbol>s%<amount>f)' }) #=> "($1,234.56)"
+    #   Mint.money(0, 'BRL').to_s(format: { zero: '--' })        #=> "--"
+    #
     # @example Padding and alignment
     #   money.to_s(format: '%<amount>10.2f')                #=> "   1234.56"
     #   money.to_s(format: '%<symbol>s%<amount>010.2f')     #=> "$0001234.56"
     #
     def to_s(format: '%<symbol>s%<amount>f', decimal: '.', thousand: ',', width: nil)
-      raise ArgumentError, 'Invalid format' unless format.is_a?(String) || format.is_a?(Hash)
+      case format
+      when {}, '', nil then raise ArgumentError, 'format must not be empty or null'
+      when Hash        then validate_format_hash!(format)
+      when String # noop
+      else raise ArgumentError, 'Invalid format'
+      end
 
       formatted = format_amount(format)
 
@@ -43,17 +67,27 @@ module Mint
 
     private
 
+    def validate_format_hash!(format)
+      unknown = format.keys - %i[positive negative zero]
+
+      raise ArgumentError, "Unknown format parameter(s): #{unknown.inspect}. " unless unknown.empty?
+    end
+
     def format_amount(format)
       format = { positive: format } if format.is_a?(String)
-      value = amount
+      positive_format = format[:positive]
+      negative_format = format[:negative]
+      zero_format = format[:zero]
 
-      if amount.negative? && format[:negative]
-        format = format[:negative]
+      if amount.negative? && negative_format
+        format = negative_format
         value = -amount
-      elsif amount.zero? && format[:zero]
-        format = format[:zero]
+      elsif amount.zero? && zero_format
+        format = zero_format
+        value = amount
       else
-        format = format[:positive]
+        format = positive_format
+        value = amount
       end
       format ||= '%<symbol>s%<amount>f'