minting 1.7.2 → 1.8.0

data/lib/minting/money/constructors.rb

@@ -7,15 +7,56 @@ module Mint
     # @param amount [Numeric] The monetary amount
     # @param currency [Currency, String] The currency code or currency object
     # @raise [ArgumentError] If amount is not numeric or currency is invalid
-    def self.create(amount, currency)
+    def self.from(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
+      currency = Currency.resolve!(currency)
+      amount = currency.normalize_amount(amount)
+
+      amount.zero? ? currency.zero : new(amount, currency)
+    end
+
+    # 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, nil]
+    #
+    # @example With explicit currency
+    #   Money.parse('19.99', 'USD')    #=> [USD 19.99]
+    #   Money.parse('garbage', 'USD')  #=> nil
+    #
+    # @example With symbol or code in the string
+    #   Money.parse('$19.99')            #=> [USD 19.99]
+    #   Money.parse('USD 1,234.56')    #=> [USD 1234.56]
+    def self.parse(input, currency = nil) = Mint.parse(input, currency)
+
+    # 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
+    #   Money.parse!('19.99', 'USD')    #=> [USD 19.99]
+    #   Money.parse!('garbage', 'USD')  #=> ArgumentError
+    def self.parse!(input, currency = nil) = Mint.parse!(input, currency)
 
-      amount = checked_currency.normalize_amount(amount)
+    # Returns a frozen zero Money in the given currency.
+    #
+    # @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) = Currency.resolve!(currency).zero
 
-      amount.zero? ? Mint.zero(checked_currency) : new(amount, checked_currency)
+    # Backwards-compatible alias for previous API
+    # TODO: deprecate in a future major release
+    def self.create(amount, currency)
+      warn 'Money.create is now deprecated. Use Money.from'
+      from(amount, currency)
     end
 
     # Builds a Money from a fractional (smallest-unit) Integer amount.
@@ -39,36 +80,38 @@ module Mint
     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)
-
-      amount.zero? ? Mint.zero(checked_currency) : new(amount, checked_currency)
+      currency = Currency.resolve!(currency)
+      amount = Rational(fractional, currency.fractional_multiplier)
+      amount.zero? ? currency.zero : new(amount, currency)
     end
 
     # Returns a new Money object with the specified amount, or self if unchanged.
     # This is the primary method for creating a modified copy of a Money instance
     # while preserving immutability.
     #
-    # @param new_amount [Numeric] The new monetary amount
+    # @param amount [Numeric] The new monetary amount
     # @return [Money] A new Money object with the new amount, or self if the amount is unchanged
     # @example
     #   price = Mint.money(10.00, 'USD')
-    #   price.mint(15.00)  #=> [USD 15.00]
-    #   price.mint(10.00)  #=> [USD 10.00] (returns self)
-    def mint(new_amount)
-      new_amount = currency.normalize_amount(new_amount)
+    #   price.copy_with(amount: 15.00)  #=> [USD 15.00]
+    #   price.copy_with(amount: 10.00)  #=> [USD 10.00] (returns self)
+    def copy_with(amount:)
+      amount = currency.normalize_amount(amount)
 
-      if new_amount == amount
+      if amount == self.amount
         self
-      elsif new_amount.zero?
-        Mint.zero(currency)
+      elsif amount.zero?
+        currency.zero
       else
-        Money.new(new_amount, currency)
+        Money.new(amount, currency)
       end
     end
 
+    def mint(new_amount)
+      warn 'Money#mint is now deprecated and will be removed in v2'
+      copy_with(amount: new_amount)
+    end
+
     private
 
     # Initializes a new Money object with the given amount and currency.

data/lib/minting/money/format/formatting.rb

@@ -5,6 +5,22 @@ module Mint
   class Money
     private
 
+    # Resolves format/decimal/thousand from locale_backend when not explicitly given.
+    # @private
+    def resolve_locale_for(format, decimal, thousand)
+      locale = locale_backend
+      [format || locale[:format] || '%<symbol>s%<amount>f',
+       decimal || locale[:decimal] || '.',
+       thousand || locale[:thousand] || ',']
+    end
+
+    def locale_backend
+      bk = Mint.locale_backend
+      return {} unless bk.respond_to?(:call)
+
+      bk.call
+    end
+
     # Selects the appropriate format template and value based on the amount's sign.
     # @private
     def select_format(format)

data/lib/minting/money/format/to_s.rb

@@ -5,7 +5,7 @@ module Mint
   class Money
     # Formats money as a string with customizable format, thousand delimiter, and decimal
     #
-    # @param format [String, Hash] Either a Format string with placeholders
+    # @param format [String, Hash, nil] 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:
@@ -15,8 +15,12 @@ module Mint
     #   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 ',')
+    #   When +nil+, falls back to +Mint.locale_backend+ if set, otherwise
+    #   +"%<symbol>s%<amount>f"+.
+    # @param thousand [String, false, nil] Thousands delimiter (e.g., ',' for 1,000).
+    #   When +nil+, falls back to +Mint.locale_backend+ if set, otherwise +","+.
+    # @param decimal [String, nil] Decimal separator (e.g., '.' or ',').
+    #   When +nil+, falls back to +Mint.locale_backend+ if set, otherwise +"."+.
     # @return [String] Formatted money string
     #
     # @raise [ArgumentError] if +format+ is not a String or Hash, the Hash
@@ -43,7 +47,12 @@ module Mint
     #   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)
+    # @example Locale-aware formatting (with Mint.locale_backend set)
+    #   money.to_s  # decimal and thousand come from locale_backend
+    #
+    def to_s(format: nil, decimal: nil, thousand: nil, width: nil)
+      format, decimal, thousand = resolve_locale_for(format, decimal, thousand)
+
       case format
       when {}, '' then raise ArgumentError, 'format must not be empty'
       when Hash   then validate_format_hash(format)

data/lib/minting/money/money.rb

@@ -1,5 +1,17 @@
 # frozen_string_literal: true
 
+require_relative 'allocation/allocation'
+require_relative 'allocation/split'
+require_relative 'arithmetics/methods'
+require_relative 'arithmetics/operators'
+require_relative 'clamp'
+require_relative 'coercion'
+require_relative 'comparable'
+require_relative 'constructors'
+require_relative 'conversion'
+require_relative 'format/formatting'
+require_relative 'format/to_s'
+
 module Mint
   # Money constructors
   class Money
@@ -37,11 +49,5 @@ module Mint
     def inspect
       Kernel.format "[#{currency_code} %0.#{currency.subunit}f]", amount
     end
-
-    # Helper method to verify if another object has the identical currency.
-    #
-    # @param other [Currency] the target currency to compare
-    # @return [Boolean] true if currencies match, false otherwise
-    def same_currency?(other) = other.currency == currency
   end
 end

data/lib/minting/version.rb

@@ -3,5 +3,5 @@
 # Root namespace for the Minting library.
 module Minting
   # Current version of the Minting gem.
-  VERSION = '1.7.2'
+  VERSION = '1.8.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: minting
 version: !ruby/object:Gem::Version
-  version: 1.7.2
+  version: 1.8.0
 platform: ruby
 authors:
 - Gilson Ferraz
@@ -41,14 +41,18 @@ files:
 - doc/Mint/CurrencyRegistry.html
 - doc/Mint/Money.html
 - doc/Mint/RangeStepPatch.html
+- doc/Mint/Registry.html
+- doc/Mint/Rounding.html
 - doc/Mint/UnknownCurrency.html
 - doc/Minting.html
 - doc/_index.html
-- doc/agents/AGENTS.md
+- doc/agents/api_review-2026-06-15.md
 - doc/agents/copilot-instructions.md
-- doc/agents/gemini_gem_evaluation.md
-- doc/agents/recommendations.md
-- doc/agents/rubocop-issues.md
+- doc/agents/expired/AGENTS.md
+- doc/agents/expired/copilot-instructions.md
+- doc/agents/expired/gemini_gem_evaluation.md
+- doc/agents/expired/recommendations.md
+- doc/agents/expired/rubocop-issues.md
 - doc/class_list.html
 - doc/css/common.css
 - doc/css/full_list.css
@@ -64,8 +68,6 @@ files:
 - doc/top-level-namespace.html
 - lib/minting.rb
 - lib/minting/currency/currency.rb
-- lib/minting/currency/currency_registry.rb
-- lib/minting/currency/world_currencies.rb
 - lib/minting/data/world-currencies.yaml
 - lib/minting/mint.rb
 - lib/minting/mint/aliases.rb
@@ -73,9 +75,15 @@ files:
 - lib/minting/mint/dsl/range.rb
 - lib/minting/mint/dsl/string.rb
 - lib/minting/mint/dsl/top_level.rb
+- lib/minting/mint/locale_backend.rb
 - lib/minting/mint/mint.rb
 - lib/minting/mint/parser/parser.rb
 - lib/minting/mint/parser/separators.rb
+- lib/minting/mint/registry/registration.rb
+- lib/minting/mint/registry/registry.rb
+- lib/minting/mint/registry/symbols.rb
+- lib/minting/mint/registry/zeros.rb
+- lib/minting/mint/rounding.rb
 - lib/minting/money/allocation/allocation.rb
 - lib/minting/money/allocation/split.rb
 - lib/minting/money/arithmetics/methods.rb

data/lib/minting/currency/currency_registry.rb

@@ -1,67 +0,0 @@
-# frozen_string_literal: true
-
-require 'yaml'
-
-# Mint currency store (internal)
-module Mint
-  # Internal currency registry
-  # Manages the registry cache and currency symbol lookups.
-  module CurrencyRegistry
-    extend self
-
-    # Returns the hash of all registered currencies.
-    #
-    # @return [Hash{String => Currency}] registered currencies mapped by code
-    # @api private
-    def currencies
-      @currencies ||= Mint.world_currencies.dup
-    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 currency_symbols
-      @currency_symbols ||= begin
-        currencies.values
-                  .reject { |c| c.symbol.empty? }
-                  .map { |currency| [currency.symbol, currency] }
-                  .sort_by { |symbol, currency| [-symbol.length, -currency.priority] }
-      end.freeze
-    end
-
-    # 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 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
-
-      currencies = CurrencyRegistry.currencies
-      raise KeyError, "Currency: #{code} already registered" if currencies[code]
-
-      currency = currencies[code] = Currency.new(code:, subunit:, symbol:, priority:)
-      invalidate_symbols_cache
-      currency
-    end
-
-    private
-
-    # Clears and refreshes the currency symbol cache.
-    # Called when currencies are registered.
-    #
-    # @api private
-    def invalidate_symbols_cache
-      @currency_symbols = nil
-    end
-  end
-end

data/lib/minting/currency/world_currencies.rb

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-
-# Mint list of world currencies
-module Mint
-  # Loads ISO world currencies from YAML file into the registry.
-  #
-  # @return [Hash{String => Currency}] ISO-4217 world currencies mapped by code
-  # @api private
-  def self.world_currencies
-    @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