minting 1.7.0 → 1.7.3

data/doc/top-level-namespace.html

@@ -102,8 +102,7 @@
         <dt id="Money-constant" class="">Money =
           <div class="docstring">
   <div class="discussion">
-    <p>Optional top‑level aliases for application use.
-Not required automatically.</p>
+    <p>Alias for <span class='object_link'><a href="Mint/Money.html" title="Mint::Money (class)">Mint::Money</a></span> — enables <code>Money.new(...)</code> shorthand.</p>
 
   </div>
 </div>
@@ -115,7 +114,16 @@ Not required automatically.</p>
         <dd><pre class="code"><span class='const'><span class='object_link'><a href="Mint.html" title="Mint (module)">Mint</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Mint/Money.html" title="Mint::Money (class)">Money</a></span></span></pre></dd>
       
         <dt id="Currency-constant" class="">Currency =
-          
+          <div class="docstring">
+  <div class="discussion">
+    <p>Alias for <span class='object_link'><a href="Mint/Currency.html" title="Mint::Currency (class)">Mint::Currency</a></span> — enables <code>Currency.new(...)</code> shorthand.</p>
+
+  </div>
+</div>
+<div class="tags">
+  
+
+</div>
         </dt>
         <dd><pre class="code"><span class='const'><span class='object_link'><a href="Mint.html" title="Mint (module)">Mint</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Mint/Currency.html" title="Mint::Currency (class)">Currency</a></span></span></pre></dd>
       
@@ -133,9 +141,9 @@ Not required automatically.</p>
 </div>
 
       <div id="footer">
-  Generated on Wed Jun 10 01:35:30 2026 by
+  Generated on Mon Jun 15 19:57:57 2026 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
-  0.9.44 (ruby-4.0.1).
+  0.9.44 (ruby-4.0.5).
 </div>
 
     </div>

data/lib/minting/currency/currency.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+# :nodoc:
+module Mint
+  # Represents a specific currency unit, identified by ISO 4217 alphabetic code.
+  # Currency objects are immutable and define the properties of a monetary unit
+  # including its subunit precision, display symbol, and formatting rules.
+  #
+  # @see https://www.iso.org/iso-4217-currency-codes.html
+  # @attr_reader code [String] ISO 4217 currency code (e.g., "USD", "EUR")
+  # @attr_reader subunit [Integer] Number of decimal places (0 for JPY, 2 for USD, 3 for IQD)
+  # @attr_reader symbol [String] Display symbol (e.g., "$", "€", "R$")
+  # @attr_reader priority [Integer] Parser precedence for symbol detection
+  # @attr_reader country [String, nil] Associated country code
+  # @attr_reader name [String, nil] Currency name
+  # @attr_reader fractional_multiplier [Integer] 10^subunit, used for fractional conversions
+  # @attr_reader minimum_amount [Rational] Smallest representable amount (1/fractional_multiplier)
+  Currency = Data.define(:code, :subunit, :symbol, :priority, :country, :name,
+                         :fractional_multiplier) do
+    # @param code [String] ISO 4217 currency code
+    # @param symbol [String] Display symbol
+    # @param subunit [Integer] Number of decimal places (default 0)
+    # @param priority [Integer] Parser precedence for symbol detection (default 0)
+    # @param country [String, nil] Associated country code (default nil)
+    # @param name [String, nil] Currency name (default nil)
+    def initialize(code:, symbol:, subunit: 0, priority: 0, country: nil, name: nil)
+      subunit = subunit.to_i
+      priority = priority.to_i
+      fractional_multiplier = 10**subunit
+      super(code:, subunit:, symbol:, priority:, country:, name:,
+            fractional_multiplier:)
+    end
+
+    # @return [String] debug representation
+    def inspect = "<Currency:(#{code} #{symbol} #{subunit} #{name})>"
+
+    # @return [Rational] smallest representable amount (1/fractional_multiplier)
+    def minimum_amount = Rational(1, fractional_multiplier)
+
+    # 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)
+  end
+
+  # Resolves an object into a {Currency}, returning +nil+ when it can't.
+  #
+  # Accepts +nil+, +String+, {Currency}, or {Money}.
+  # Passing a {Money} extracts its currency
+  #
+  # @param object [String, Currency, Money, nil] a currency code, object, or +nil+
+  # @return [Currency, nil] the resolved Currency, or +nil+ if +object+ is +nil+
+  #   or the code is not registered
+  # @raise [ArgumentError] if +object+ is an unsupported type (e.g. +Integer+)
+  def Currency.resolve(object)
+    case object
+    when NilClass then nil
+    when Currency then object
+    when Money    then object.currency
+    when String   then Mint.currency_for_code object
+    else          raise ArgumentError, "currency must be [Currency], [Money], [String] or nil (#{object})"
+    end
+  end
+
+  # Resolves an object into a {Currency}, raising on failure.
+  #
+  # Like {.resolve} but raises when the result would be +nil+.
+  #
+  # @param object [String, Currency, Money, nil] a currency code, object, or +nil+
+  # @return [Currency] the resolved Currency
+  # @raise [ArgumentError] if +object+ cannot be resolved into a registered currency
+  def Currency.resolve!(object)
+    resolve(object) or raise ArgumentError, "Could not resolve (#{object}) into a currency"
+  end
+end

data/lib/minting/mint/aliases.rb

@@ -3,5 +3,8 @@
 # Optional top‑level aliases for application use.
 # Not required automatically.
 
+# Alias for {Mint::Money} — enables `Money.new(...)` shorthand.
 Money = Mint::Money
+
+# Alias for {Mint::Currency} — enables `Currency.new(...)` shorthand.
 Currency = Mint::Currency

data/lib/minting/mint/dsl/{refinements.rb → numeric.rb}

@@ -1,22 +1,23 @@
 # frozen_string_literal: true
 
-# Mint refinements
+# Mint Numeric refinements
 module Mint
   refine Numeric do
+    # @return [Money] self interpreted as BRL
     def reais = Mint.money(self, 'BRL')
 
+    # @return [Money] self interpreted as USD
     def dollars = Mint.money(self, 'USD')
 
+    # @return [Money] self interpreted as EUR
     def euros = Mint.money(self, 'EUR')
 
+    # @param currency [String, Symbol, Currency] target currency
+    # @return [Money] self interpreted as the given currency
     def to_money(currency) = Mint.money(self, currency)
 
     alias_method :dollar, :dollars
     alias_method :euro, :euros
     alias_method :mint, :to_money
   end
-
-  refine String do
-    def to_money(currency) = Mint.money(to_r, currency)
-  end
 end

data/lib/minting/mint/dsl/range.rb

@@ -9,43 +9,56 @@ module Mint
     # iteration (+ / <=>) for non-numeric steps natively, so this patch is
     # only needed on older Rubies.
     module RangeStepPatch
-      def step(step_size = nil, &)
+      # Iterates over the range using a Money step value.
+      # Overrides Range#step to handle Mint::Money step sizes on Ruby < 4.0.
+      #
+      # @param step_size [Mint::Money, nil] step amount
+      # @return [self, Enumerator] self if block given, Enumerator otherwise
+      def step(step_size = nil, &block)
         return super unless step_size.is_a?(Mint::Money)
 
         raise TypeError, "can't iterate from NilClass" unless self.begin
         raise ArgumentError, "step can't be 0" if step_size.zero?
 
-        if block_given?
-          each_money_step(step_size, &)
+        if block
+          each_money_step(step_size, &block)
           self
         else
-          Enumerator.new do |yielder|
-            each_money_step(step_size) { |v| yielder << v }
-          end
+          Enumerator.new { |yielder| each_money_step(step_size) { |value| yielder << value } }
         end
       end
 
       private
 
-      def each_money_step(step_amount)
+      # Dispatches to the appropriate iteration strategy based on range bounds.
+      # @private
+      def each_money_step(step, &)
+        self.end ? bounded_step(step, &) : unbounded_step(step, &)
+      end
+
+      # Iterates an open-ended range (no upper bound) with a Money step.
+      # @private
+      def unbounded_step(step)
         current = self.begin
-        last = self.end
-
-        unless last
-          loop do
-            yield current
-            current += step_amount
-          end
-          return
+        loop do
+          yield current
+          current += step
         end
+      end
+
+      # Iterates a bounded range with a Money step, respecting direction and exclude_end?.
+      # @private
+      def bounded_step(step)
+        current = self.begin
+        last    = self.end
+        asc     = step.positive?
 
-        ascending = step_amount.positive?
         loop do
-          break if ascending ? current > last : current < last
+          break if asc ? current > last : current < last
           break if exclude_end? && current == last
 
           yield current
-          current += step_amount
+          current += step
         end
       end
     end

data/lib/minting/mint/dsl/string.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Mint String refinement
+module Mint
+  refine String do
+    # Parses self as a numeric string and creates a Money in the given currency.
+    #
+    # @param currency [String, Symbol, Currency] target currency
+    # @return [Money]
+    def to_money(currency) = Mint.money(to_r, currency)
+  end
+end

data/lib/minting/mint/dsl/top_level.rb

@@ -2,6 +2,9 @@
 
 # Mint refinements
 module Mint
+  # Registers top-level ::Money and ::Currency constants as aliases for Mint's classes.
+  #
+  # @raise [NameError] if ::Money or ::Currency are already defined and differ
   def self.use_top_level_constants!
     if !defined?(::Money) && !defined?(::Currency)
       require 'minting/mint/aliases'

data/lib/minting/mint/locale_backend.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# :nodoc:
+module Mint
+  class << self
+    # Optional callable that returns a Hash with locale-aware formatting defaults.
+    #
+    # The callable receives no arguments and returns a Hash with these keys:
+    #   [+:decimal+]   Decimal separator (e.g. +","+)
+    #   [+:thousand+]  Thousands delimiter (e.g. +"."+)
+    #   [+:format+]    Format template string (e.g. +"%<amount>f %<symbol>s"+)
+    #
+    # When set, +#to_s+ and +#format+ use these values as fallbacks when the
+    # corresponding parameter is not explicitly provided.
+    #
+    # @example Rails I18n integration (in minting-rails railtie)
+    #   Mint.locale_backend = -> {
+    #     fmt = I18n.t('number.currency.format')
+    #     {
+    #       decimal: fmt[:separator],
+    #       thousand: fmt[:delimiter],
+    #       format: fmt[:format] == '%n %u' ? '%<amount>f %<symbol>s' : '%<symbol>s%<amount>f'
+    #     }
+    #   }
+    #
+    # @return [Proc, #call, nil]
+    attr_accessor :locale_backend
+  end
+end

data/lib/minting/mint/mint.rb

@@ -14,20 +14,36 @@ module Mint
   # @raise [ArgumentError] if the currency code is not registered
   def self.money(amount, currency_code) = Money.create(amount, currency_code)
 
-  # Finds a registered currency by its code, symbol,
-  # or retrieves it directly if already a Currency object.
+  # @return [Hash{String => Currency}] the frozen world-currencies hash
+  # @api private
+  def self.world_currencies = Registry.world_currencies
+
+  # Looks up a registered currency by its alpha code.
+  #
+  # Unlike {.currency}, this performs a direct hash lookup and only accepts strings.
   #
-  # @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 NilClass then nil
-    when Currency then currency
-    when String   then CurrencyRegistry.currencies[currency]
-    else          raise ArgumentError, "currency must be [Currency] ot [String] (#{currency})"
-    end
+  # @param code [String] the currency code
+  # @return [Currency, nil] the registered Currency, or +nil+ if not found
+  def self.currency_for_code(code)
+    Registry.currencies[code]
   end
 
+  # Looks up a currency by its display symbol.
+  #
+  # @param symbol [String] the display symbol (e.g. "$", "R$")
+  # @return [Currency, nil] the highest-priority currency for the symbol
+  def self.currency_for_symbol(symbol)
+    Registry.currency_for_symbol(symbol)
+  end
+
+  # Returns a zero {Money} in the given currency, useful as a default value
+  # for discounts, totals, or placeholders.
+  #
+  # @param currency [String, Currency] a currency code or object
+  # @return [Money] a frozen zero-Money
+  # @raise [ArgumentError] if the currency can't be resolved
+  def self.zero(currency) = Registry.zero_for(Currency.resolve!(currency))
+
   # Registers a new currency, raising a KeyError if already registered.
   #
   # @param code [String] the unique currency code
@@ -38,6 +54,6 @@ 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: 0, symbol: '', priority: 0)
-    CurrencyRegistry.register(code:, subunit:, symbol:, priority:)
+    Registry.register(code:, subunit:, symbol:, priority:)
   end
 end

data/lib/minting/mint/parser/parser.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# Mint Money parsing
+module Mint
+  extend self
+
+  # Parses a human-readable money string into a {Money} object.
+  #
+  # @param input [String] Amount input, optionally including a currency symbol or code
+  # @param currency [String, Symbol, Currency, nil] ISO code when not present in +input+
+  # @return [Money]
+  # @raise [ArgumentError] when +input+ is invalid or currency cannot be determined
+  #
+  # @example With explicit currency
+  #   Money.parse('19.99', 'USD')    #=> [USD 19.99]
+  #   Money.parse('1.234,56', 'EUR') #=> [EUR 1234.56]
+  #
+  # @example With symbol or code in the string
+  #   Money.parse('$19.99')            #=> [USD 19.99]
+  #   Money.parse('19,99 €')         #=> [EUR 19.99]
+  #   Money.parse('USD 1,234.56')    #=> [USD 1234.56]
+  def parse(input, currency = nil)
+    raise ArgumentError, 'input must be a String' unless input.is_a?(String)
+
+    input = input.strip
+    raise ArgumentError, 'input cannot be empty' if input.empty?
+
+    currency = Currency.resolve(currency) || parse_currency(input)
+    raise ArgumentError, "Currency [#{currency}] not registered" unless currency
+
+    amount = currency.normalize_amount(parse_amount(input))
+    Mint::Money.new(amount, currency)
+  end
+
+  private
+
+  # Extracts a numeric value from input that should only contain an amount.
+  # @private
+  def parse_amount(input)
+    accounting_negative = input.start_with?('(') && input.end_with?(')')
+
+    # Remove any charater that is not a digit, comma or period
+    numeric = input.scan(/[\d.,-]/).join
+    amount = Rational(normalize_separators(numeric))
+    accounting_negative ? -amount : amount
+  end
+
+  # Extracts currency from a string by matching ISO code or symbol.
+  #
+  # Scans all uppercase words and returns the first registered code, falling
+  # back to symbol matching. This correctly handles inputs like
+  # "MAX 10.00 USD" where the first uppercase word isn't a currency code.
+  # @private
+  def parse_currency(input)
+    input.scan(/\b([A-Z_]+)\b/) do |(code)|
+      currency = Mint.currency_for_code(code)
+      return currency if currency
+    end
+
+    Registry.detect_currency(input) or raise ArgumentError, 'Currency could not be detected'
+  end
+end

data/lib/minting/mint/parser/separators.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# Mint Money parsing
+module Mint
+  extend self
+
+  private
+
+  # Classifies the separator pattern in a numeric string.
+  # @private
+  def classify_separators(numeric)
+    case [numeric.count('.'), numeric.count(',')]
+    in [0, 1] if numeric[-4] == ',' then :thousands_comma  # Comma is a thousand separator
+    in [0, 1]                       then :decimal_comma    # Only one comma: decimal (e.g. 19,99 or 1,4 or 1,2345).
+    in [0, 0] | [1, 0]              then :decimal_period   # e.g. "1500" or "34.21".
+    in [p, c] if p > 1 && c > 1     then :ambiguous        # Both separators appear multiple times
+    in [p, c] if p > 0 && c > 0     then :mixed            # Commas and dots: the rightmost one is the decimal
+    else                                 :thousands        # Multiple of the same separator only (e.g. 1,234,567)
+    end
+  end
+
+  # Converts locale-specific decimal/thousand separators into a plain decimal string.
+  # @private
+  def normalize_separators(numeric)
+    case classify_separators(numeric)
+    when :decimal_period   then numeric # Nothing to normalize (e.g. "1500" or "34.21").
+    when :decimal_comma    then numeric.tr(',', '.') # Only one comma: decimal (e.g. 19,99 or 1,234).
+    when :thousands_comma  then numeric.delete(',')
+    when :thousands        then numeric.delete('.,')
+    when :ambiguous then   raise ArgumentError, "could not distinguish decimal and thousand separators in '#{numeric}'"
+    when :mixed # Commas and dots: the rightmost one is the decimal separator.
+      if numeric.rindex(',') > numeric.rindex('.')
+        numeric.delete('.').tr(',', '.')
+      else
+        numeric.delete(',')
+      end
+    end
+  end
+end

data/lib/minting/mint/registry/registration.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Mint
+  # :nodoc:
+  module Registry
+    # Registers a new currency, raising a KeyError if already registered.
+    #
+    # @param code [String] the unique currency code
+    # @param subunit [Integer] the decimal subunit precision, defaults to 0
+    # @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(code:, subunit: 0, symbol: '', priority: 0)
+      raise ArgumentError, 'Currency code must be String' unless code.is_a? String
+      unless code.match?(/^[A-Z_]+$/)
+        raise ArgumentError,
+              "Currency code must have only letters or '_' ('USD',, 'MY_COIN')"
+      end
+
+      MUTEX.synchronize do
+        raise KeyError, "Currency: #{code} already registered" if currencies[code]
+
+        currency = Currency.new(code:, subunit:, symbol:, priority:)
+        @currencies = @currencies.merge(code => currency).freeze
+        @currency_symbols = nil
+        @currency_symbol_map = nil
+        currency
+      end
+    end
+  end
+end

data/lib/minting/mint/registry/registry.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require_relative 'symbols'
+require_relative 'registration'
+require_relative 'zeros'
+
+# Mint registry: manages all cached state
+module Mint
+  # Internal registry for currencies, symbols, and zero-money cache.
+  # All mutable shared state lives here.
+  module Registry
+    MUTEX = Monitor.new
+
+    private_constant :MUTEX
+
+    # Loads ISO world currencies from YAML file.
+    #
+    # @return [Hash{String => Currency}] ISO-4217 world currencies mapped by code
+    # @api private
+    def self.world_currencies
+      @world_currencies || MUTEX.synchronize do
+        @world_currencies = begin
+          path = File.join(File.expand_path('../../data', __dir__), 'world-currencies.yaml')
+          YAML.load_file(path).to_h { |entry| [entry['code'], Currency.new(**entry.transform_keys(&:to_sym))] }
+        end.freeze
+      end
+    end
+
+    # Returns the frozen hash of all registered currencies (world + custom).
+    #
+    # @return [Hash{String => Currency}] registered currencies mapped by code
+    # @api private
+    def self.currencies
+      @currencies || MUTEX.synchronize { @currencies = world_currencies.dup.freeze }
+    end
+  end
+end

data/lib/minting/mint/registry/symbols.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Mint
+  # :nodoc:
+  module Registry
+    extend self
+
+    # Looks up a currency by its display symbol.
+    #
+    # @param symbol [String] the display symbol (e.g. "$", "R$")
+    # @return [Currency, nil] the highest-priority currency for the symbol
+    # @api private
+    def currency_for_symbol(symbol)
+      @currency_symbol_map || MUTEX.synchronize { @currency_symbol_map = currency_symbols.to_h.freeze }
+      @currency_symbol_map[symbol]
+    end
+
+    # Scans +input+ for registered currency symbols and returns the first match.
+    #
+    # @param input [String] the string to scan
+    # @return [Currency, nil]
+    # @api private
+    def detect_currency(input)
+      currency_symbols.each do |symbol, currency|
+        return currency if input.include?(symbol)
+      end
+      nil
+    end
+
+    private
+
+    # Registered symbols sorted for detection: longest match wins, then parser priority.
+    # Duplicate symbols are deduplicated — the highest-priority currency wins.
+    #
+    # @return [Array<Array<String, Currency>>] sorted symbol-to-currency mappings
+    # @api private
+    def currency_symbols
+      @currency_symbols || MUTEX.synchronize do
+        @currency_symbols =
+          currencies.values
+                    .reject { |currency| currency.symbol.empty? }
+                    .map { |currency| [currency.symbol, currency] }
+                    .sort_by { |symbol, currency| [-symbol.length, -currency.priority] }
+                    .uniq { |symbol, _| symbol }
+                    .freeze
+      end
+    end
+  end
+end

data/lib/minting/mint/registry/zeros.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Mint
+  # :nodoc:
+  module Registry
+    # Returns the cached zero-Money for a currency, creating it if needed.
+    #
+    # @param currency [Currency] the currency object
+    # @return [Money] a frozen zero-Money
+    # @api private
+    def self.zero_for(currency)
+      MUTEX.synchronize do
+        @zeros ||= {}
+        @zeros[currency] ||= Mint::Money.send(:new, 0, currency)
+      end
+    end
+  end
+end

data/lib/minting/mint.rb

@@ -1,18 +1,15 @@
 # frozen_string_literal: true
 
-require 'minting/mint/currency/currency'
-require 'minting/mint/currency/currency_registry'
-require 'minting/mint/currency/world_currencies'
-require 'minting/mint/dsl/range'
-require 'minting/mint/dsl/refinements'
-require 'minting/mint/dsl/top_level'
-require 'minting/mint/mint'
-require 'minting/mint/parser'
-require 'minting/money/allocation'
-require 'minting/money/arithmetics'
-require 'minting/money/coercion'
-require 'minting/money/comparable'
-require 'minting/money/constructors'
-require 'minting/money/conversion'
-require 'minting/money/formatting'
-require 'minting/money/money'
+require_relative 'currency/currency'
+
+require_relative 'mint/dsl/numeric'
+require_relative 'mint/dsl/range'
+require_relative 'mint/dsl/string'
+require_relative 'mint/dsl/top_level'
+require_relative 'mint/locale_backend'
+require_relative 'mint/mint'
+require_relative 'mint/parser/parser'
+require_relative 'mint/parser/separators'
+require_relative 'mint/registry/registry'
+
+require_relative 'money/money'

data/lib/minting/money/allocation/allocation.rb

@@ -0,0 +1,25 @@
+# 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
+    # @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?
+      raise ArgumentError, 'Proportions total must not be zero' if whole.zero?
+
+      subunit = currency.subunit
+      amounts = proportions.map { |rate| Rational(amount * rate, whole).round(subunit) }
+      allocate_left_over(amounts: amounts, left_over: amount - amounts.sum)
+    end
+  end
+end