minting 1.7.2 → 1.8.0

data/lib/minting/mint/mint.rb

@@ -12,46 +12,21 @@ module Mint
   # @param currency_code [Currency, String] Currency code
   # @return [Money] the instantiated Money object
   # @raise [ArgumentError] if the currency code is not registered
-  def self.money(amount, currency_code) = Money.create(amount, currency_code)
+  def self.money(amount, currency_code) = Money.from(amount, currency_code)
 
-  # Finds a registered currency by its code, symbol,
-  # or retrieves it directly if already a Currency 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 NilClass then nil
-    when Currency then currency
-    when String   then CurrencyRegistry.currencies[currency]
-    else          raise ArgumentError, "currency must be [Currency], [String] or nil (#{currency})"
-    end
-  end
+  # @return [Hash{String => Currency}] the frozen world-currencies hash
+  # @api private
+  def self.world_currencies = Registry.world_currencies
 
-  # Returns a zero {Money} in the given currency, useful as a default value
-  # for discounts, totals, or placeholders.
+  # Executes a block with a specific rounding mode applied to all money
+  # construction, parsing, change, allocation, and split operations.
   #
-  # @param currency [String, Currency] a currency code or object
-  # @return [Money] a frozen zero-Money
-  # @raise [ArgumentError] if the currency is not registered
-  def self.zero(currency)
-    checked = Mint.currency(currency)
-    raise ArgumentError, "Invalid Currency: [#{currency}]" unless checked
-
-    @zeros ||= CurrencyRegistry.currencies.values.to_h { |currency| [currency, Mint::Money.send(:new, 0, currency)] }
-    @zeros[currency] ||= Money.send(:new, 0, currency)
-    @zeros[currency]
-  end
-
+  # Restores the previous mode (or default) when the block exits, even on
+  # exception.
   #
-  # @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_currency(code:, subunit: 0, symbol: '', priority: 0)
-    CurrencyRegistry.register(code:, subunit:, symbol:, priority:)
-  end
+  # @param mode [Symbol] one of: +:half_up+, +:half_down+, +:floor+,
+  #   +:ceil+, +:truncate+, +:down+
+  # @yield block to execute with the rounding mode active
+  # @raise [ArgumentError] if +mode+ is not a recognised rounding mode
+  def self.with_rounding(mode, &) = Rounding.with_mode(mode, &)
 end

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

@@ -6,29 +6,58 @@ module Mint
 
   # Parses a human-readable money string into a {Money} object.
   #
+  # Returns +nil+ when the input is invalid or currency cannot be determined.
+  #
   # @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
+  # @return [Money, nil]
   #
   # @example With explicit currency
-  #   Money.parse('19.99', 'USD')    #=> [USD 19.99]
-  #   Money.parse('1.234,56', 'EUR') #=> [EUR 1234.56]
+  #   Mint.parse('19.99', 'USD')    #=> [USD 19.99]
+  #   Mint.parse('garbage', 'USD')  #=> nil
   #
   # @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]
+  #   Mint.parse('$19.99')            #=> [USD 19.99]
+  #   Mint.parse('USD 1,234.56')    #=> [USD 1234.56]
   def parse(input, currency = nil)
+    return nil unless input.is_a?(String)
+
+    input = input.strip
+    return nil if input.empty?
+
+    currency = parse_currency(input, currency)
+    return nil unless currency
+
+    amount = parse_amount(input)
+    return nil unless amount
+
+    amount = currency.normalize_amount(amount)
+    Mint::Money.new(amount, currency)
+  end
+
+  # Like {.parse} but raises on failure.
+  #
+  # @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
+  #   Mint.parse!('19.99', 'USD')    #=> [USD 19.99]
+  #   Mint.parse!('garbage', 'USD')  #=> ArgumentError
+  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 = Mint.currency(currency) || parse_currency(input)
-    raise ArgumentError, "Currency [#{currency}] not registered" unless currency
+    currency = parse_currency(input, currency)
+    raise ArgumentError, "Currency [#{currency}] not found" unless currency
 
-    amount = currency.normalize_amount(parse_amount(input))
+    amount = parse_amount(input)
+    raise ArgumentError, "Could not parse [#{input}]" unless amount
+
+    amount = currency.normalize_amount(amount)
     Mint::Money.new(amount, currency)
   end
 
@@ -40,8 +69,11 @@ module Mint
     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))
+    numeric_input = input.scan(/[\d.,-]/).join
+    numeric = parse_separators(numeric_input)
+    return nil unless numeric
+
+    amount = Rational(numeric)
     accounting_negative ? -amount : amount
   end
 
@@ -51,16 +83,15 @@ module Mint
   # 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)
+  def parse_currency(input, currency = nil)
+    currency = Currency.resolve(currency)
+    return currency if currency
+
     input.scan(/\b([A-Z_]+)\b/) do |(code)|
-      currency = Mint.currency(code)
+      currency = Currency.for_code(code)
       return currency if currency
     end
 
-    CurrencyRegistry.currency_symbols.each do |symbol, currency|
-      return currency if input.include?(symbol)
-    end
-
-    raise ArgumentError, 'Currency could not be detected'
+    Registry.detect_currency(input)
   end
 end

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

@@ -10,24 +10,26 @@ module Mint
   # @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)
+    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 :invalid         # 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)
+  def parse_separators(numeric)
+    return nil unless numeric.match?(/\d/)
+
     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 :invalid          then nil
     when :mixed # Commas and dots: the rightmost one is the decimal separator.
       if numeric.rindex(',') > numeric.rindex('.')
         numeric.delete('.').tr(',', '.')

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,20 @@
+# 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)
+      raise ArgumentError, "Expect a Currency param. (#{currency})" unless currency.is_a?(Currency)
+
+      MUTEX.synchronize do
+        @zeros ||= {}
+        @zeros[currency] ||= Mint::Money.send(:new, 0, currency)
+      end
+    end
+  end
+end

data/lib/minting/mint/rounding.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Mint
+  # Rounding-mode dispatch table and block-scoped context.
+  # @api private
+  module Rounding
+    # Maps mode symbols to their corresponding +Rational+ rounding lambdas.
+    # @return [Hash{Symbol => Proc}]
+    # @api private
+    MODES = {
+      half_up: ->(amount, ndigits) { amount.round(ndigits, half: :up) },
+      half_down: ->(amount, ndigits) { amount.round(ndigits, half: :down) },
+      floor: ->(amount, ndigits) { amount.floor(ndigits) },
+      ceil: ->(amount, ndigits) { amount.ceil(ndigits) },
+      truncate: ->(amount, ndigits) { amount.truncate(ndigits) },
+      down: ->(amount, ndigits) { amount.truncate(ndigits) }
+    }.freeze
+
+    # Returns the currently active rounding mode, falling back to +:half_up+.
+    # @api private
+    # @return [Symbol]
+    def self.current_mode
+      Thread.current[:minting_rounding_mode] || :half_up
+    end
+
+    # Rounds +amount+ to +ndigits+ using the currently scoped rounding mode.
+    # @api private
+    # @param amount [Numeric]
+    # @param ndigits [Integer]
+    # @return [Rational]
+    def self.apply(amount, ndigits)
+      MODES.fetch(current_mode).call(amount.to_r, ndigits)
+    end
+
+    # Sets a rounding mode for the duration of a block, restoring the
+    # previous mode on exit (even on exception).
+    # @api private
+    # @param mode [Symbol]
+    # @yield block to execute with the mode active
+    # @raise [ArgumentError] on unknown mode
+    def self.with_mode(mode)
+      raise ArgumentError, "Unknown rounding mode: #{mode}" unless MODES.key?(mode)
+
+      prev = Thread.current[:minting_rounding_mode]
+      Thread.current[:minting_rounding_mode] = mode
+      yield
+    ensure
+      Thread.current[:minting_rounding_mode] = prev
+    end
+  end
+end

data/lib/minting/mint.rb

@@ -1,27 +1,16 @@
 # frozen_string_literal: true
 
-require 'minting/currency/currency'
-require 'minting/currency/currency_registry'
-require 'minting/currency/world_currencies'
+require_relative 'mint/rounding'
+require_relative 'currency/currency'
 
-require 'minting/mint/dsl/numeric'
-require 'minting/mint/dsl/range'
-require 'minting/mint/dsl/string'
-require 'minting/mint/dsl/top_level'
+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 'minting/mint/mint'
-require 'minting/mint/parser/parser'
-require 'minting/mint/parser/separators'
-
-require 'minting/money/allocation/allocation'
-require 'minting/money/allocation/split'
-require 'minting/money/arithmetics/methods'
-require 'minting/money/arithmetics/operators'
-require 'minting/money/clamp'
-require 'minting/money/coercion'
-require 'minting/money/comparable'
-require 'minting/money/constructors'
-require 'minting/money/conversion'
-require 'minting/money/format/formatting'
-require 'minting/money/format/to_s'
-require 'minting/money/money'
+require_relative 'money/money'

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

@@ -17,8 +17,7 @@ module Mint
       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) }
+      amounts = proportions.map { |rate| currency.normalize_amount(Rational(amount * rate, whole)) }
       allocate_left_over(amounts: amounts, left_over: amount - amounts.sum)
     end
   end

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

@@ -17,7 +17,7 @@ module Mint
     def split(slices)
       raise ArgumentError, 'Slices quantity must be an poitive integer' unless slices.positive? && slices.integer?
 
-      fraction = (amount / slices).round(currency.subunit)
+      fraction = currency.normalize_amount(amount / slices)
       allocate_left_over(amounts: Array.new(slices, fraction),
                          left_over: amount - (fraction * slices))
     end

data/lib/minting/money/arithmetics/methods.rb

@@ -6,7 +6,7 @@ module Mint
     # Returns the absolute value of the monetary amount as a new {Money} instance.
     #
     # @return [Money] the absolute value
-    def abs = mint(amount.abs)
+    def abs = copy_with(amount: amount.abs)
 
     # Returns true if the monetary amount is less than zero.
     #
@@ -22,6 +22,6 @@ module Mint
     # Enables standard ranges and stepping (e.g. `1.dollar..10.dollars`).
     #
     # @return [Money] successor Money instance
-    def succ = mint(amount + currency.minimum_amount)
+    def succ = copy_with(amount: amount + currency.minimum_amount)
   end
 end

data/lib/minting/money/arithmetics/operators.rb

@@ -11,7 +11,7 @@ module Mint
     def +(addend)
       case addend
       in 0 then self
-      in Money if same_currency?(addend) then mint(amount + addend.amount)
+      in Money if same_currency?(addend) then copy_with(amount: amount + addend.amount)
       else raise TypeError, "#{addend} can't be added to #{self}"
       end
     end
@@ -24,7 +24,7 @@ module Mint
     def -(subtrahend)
       case subtrahend
       when 0     then return self
-      when Money then return mint(amount - subtrahend.amount) if same_currency?(subtrahend)
+      when Money then return copy_with(amount: amount - subtrahend.amount) if same_currency?(subtrahend)
       end
       raise TypeError, "#{subtrahend} can't be subtracted from #{self}"
     end
@@ -32,7 +32,7 @@ module Mint
     # Unary negation operator. Returns a new {Money} instance with the inverted sign.
     #
     # @return [Money] negated Money instance
-    def -@ = mint(-amount)
+    def -@ = copy_with(amount: -amount)
 
     # Performs multiplication of the monetary value by a standard scalar Numeric.
     #
@@ -42,7 +42,7 @@ module Mint
     def *(multiplicand)
       raise TypeError, "#{self} can't be multiplied by #{multiplicand}" unless multiplicand.is_a?(Numeric)
 
-      mint(amount * multiplicand)
+      copy_with(amount: amount * multiplicand)
     end
 
     # Performs division of the monetary value by a scalar Numeric or identical currency {Money}.
@@ -53,7 +53,7 @@ module Mint
     # @raise [ZeroDivisionError] if division by zero is attempted
     def /(divisor)
       case divisor
-      when Numeric then return mint(amount / divisor)
+      when Numeric then return copy_with(amount: amount / divisor)
       when Money   then return amount / divisor.amount if same_currency? divisor
       end
       raise TypeError, "#{self} can't be divided by #{divisor}"
@@ -65,7 +65,7 @@ module Mint
     # @return [Money] reult of amount ** exponent
     # @raise [TypeError] if exponent is not Numeric
     def **(exponent)
-      return mint(amount**exponent) if exponent.is_a?(Numeric)
+      return copy_with(amount: amount**exponent) if exponent.is_a?(Numeric)
 
       raise TypeError, "#{self} can't be powered by #{exponent}"
     end

data/lib/minting/money/clamp.rb

@@ -47,7 +47,7 @@ module Mint
       else
         min = min_or_range
       end
-      mint(amount.clamp(normalize_boundary(min), normalize_boundary(max)))
+      copy_with(amount: amount.clamp(normalize_boundary(min), normalize_boundary(max)))
     end
 
     private

data/lib/minting/money/coercion.rb

@@ -44,7 +44,7 @@ module Mint
       # Multiplies a Money object by the wrapped numeric value.
       # This is the standard coercion path for `Numeric * Money`.
       def *(other)
-        other.mint(@value * other.amount)
+        other.copy_with(amount: @value * other.amount)
       end
 
       # @private

data/lib/minting/money/comparable.rb

@@ -44,6 +44,12 @@ module Mint
     # @return [self, nil] self if amount is non-zero, nil otherwise
     def nonzero? = amount.nonzero?
 
+    # Helper method to verify if another Money has the identical currency.
+    #
+    # @param other [Money] the target currency to compare
+    # @return [Boolean] true if currencies match, false otherwise
+    def same_currency?(other) = other.currency == currency
+
     # @return [Boolean] true if amount is zero
     def zero? = amount.zero?
   end