minting 1.5.1 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40050495b5105709bf403740b7373079ee354a005bd3057891a28f756043025a
-  data.tar.gz: b6635617152e7794aefbf3b5ff2a601e8c6cf6a6f0b9660b69b985bde1d7f6d6
+  metadata.gz: 293a64ebe3fd00ed8f6d062b596234550f85ead517b7f8094648dd9502be2f86
+  data.tar.gz: 3a98bb94ce601340b9cced8b275ee0be3e578d7e3cf781245cdd0fe5ee8038f1
 SHA512:
-  metadata.gz: 2fa5d0bcbe484c2cb2ae87f2bb770f4a9fe4aadbcc123ed8b5ae1cc3b20553bfcfc73bb76e85d90d363cf428ef38bebb687531bb687cec249579ccc0fcda3b21
-  data.tar.gz: 4bcc01dea9e15a88552c171206b867aba3bf97a22cdd7e16b596b597527ae280ba9079e7ccd9bb61e498ba3f36c4bd17b4a29be949c8fea9caaaaa7f761a555d
+  metadata.gz: fe587b6b5180c831b1e32092dfe9857ae37516f7fd274215be27e21af1263e99a93725f019e3be96962c5f20c13519326fc2b18b81b88e22aab43dc0d93a9b49
+  data.tar.gz: b0b8ca0b0dd832668e7b37dfbcca6e3606c673496c8149de90e9d2ffd21a166205e37ae9b455e36b1a71b07729a1d8c5bac074022991d45906ec7c410ec73740

data/README.md

@@ -148,7 +148,7 @@ price.clamp(min_price, 100) #=> [USD 75.00]
 
 **Zero equality** — Any zero amount is considered equal across currencies and to numeric zero `Mint.money(0, 'USD') == Mint.money(0, 'EUR')` is intentionally `true`. Non-zero amounts must match currency and value.
 
-**Custom currencies** — `Mint.register_currency` returns the existing entry if the code is already registered; use `register_currency!` to detect duplicates.
+**Custom currencies** — `Mint.register_currency`, Only registered currency codes and symbolos are recoginized by the parser.
 
 **Built-in currencies** — ISO-style codes ship in `lib/minting/data/currencies.yaml` and load when the registry is first accessed.
 
@@ -188,10 +188,10 @@ gem install minting
 ## Parsing strings
 
 ```ruby
-Mint::Money.parse('$19.99')           #=> [USD 19.99]
-Mint::Money.parse('19,99 €')          #=> [EUR 19.99]
-Mint::Money.parse('1.234,56', 'EUR')  #=> [EUR 1234.56]
-Mint::Money.parse('USD 1,234.56')     #=> [USD 1234.56]
+Mint.parse('$19.99')           #=> [USD 19.99]
+Mint.parse('19,99 €')          #=> [EUR 19.99]
+Mint.parse('1.234,56', 'EUR')  #=> [EUR 1234.56]
+Mint.parse('USD 1,234.56')     #=> [USD 1234.56]
 ```
 
 - Pass a currency code when the string has no symbol or code. 

data/doc/agents/recommendations.md

@@ -208,7 +208,7 @@ property test:
 
 ```ruby
 m = Mint.money(9.99, 'USD')
-assert_equal m, Mint::Money.parse(m.inspect.delete_prefix('[').delete_suffix(']'))
+assert_equal m, Mint.parse(m.inspect.delete_prefix('[').delete_suffix(']'))
 ```
 
 Make it a one-liner or a property-based test with 10–20 random

data/lib/minting/data/currencies.yaml

@@ -709,3 +709,9 @@
   symbol: T$
   name: Tongan Paʻanga
   priority: 1
+- code: XXX
+  country:
+  subunit: 0
+  symbol: ¤
+  name: No Currency
+  priority: 0

data/lib/minting/mint/currency.rb

@@ -4,11 +4,16 @@ module Mint
   # Represents a specific currency unit, identified by ISO 4217 alphabetic code
   #
   # @see https://www.iso.org/iso-4217-currency-codes.html
-  class Currency
-    attr_reader :code, :subunit, :symbol,
-                :country,
-                :fractional_multiplier, :minimum_amount,
-                :name, :priority
+  Currency = Data.define(:code, :subunit, :symbol, :priority, :country, :name,
+                         :fractional_multiplier, :minimum_amount) do
+    def initialize(code:, symbol:, subunit: 0, priority: 0, country: nil, name: nil)
+      subunit = subunit.to_i
+      priority = priority.to_i
+      fractional_multiplier = 10**subunit
+      minimum_amount = Rational(1, fractional_multiplier)
+      super(code:, subunit:, symbol:, priority:, country:, name:,
+            fractional_multiplier:, minimum_amount:)
+    end
 
     def inspect = "<Currency:(#{code} #{symbol} #{subunit} #{name})>"
 
@@ -16,19 +21,5 @@ module Mint
     # 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
-      @subunit = subunit.to_i
-      @symbol = symbol
-      @priority = priority.to_i
-      @country = country
-      @name = name
-      @fractional_multiplier = 10**@subunit
-      @minimum_amount = Rational(1, fractional_multiplier)
-      freeze
-    end
   end
 end

data/lib/minting/mint/currency_store.rb

@@ -4,25 +4,24 @@ require 'yaml'
 
 # Mint currency store (internal)
 module Mint
-  # Internal currency storage and loading.
+  # Internal currency registry
   # Manages the registry cache and currency symbol lookups.
-  module CurrencyStore
+  module Registry
+    module_function
+
     # 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
+    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 self.currency_symbols
+    def currency_symbols
       @currency_symbols ||= begin
         currencies.values
                   .reject { |currency| currency.symbol.empty? }
@@ -35,34 +34,8 @@ module Mint
     # Called when currencies are registered.
     #
     # @api private
-    def self.invalidate_symbols_cache
+    def 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/mint.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# Mint currency registration and factory (public API)
+module Mint
+  # Unknown currency excpetion
+  class UnknownCurreny < StandardError
+  end
+
+  # Creates a new {Money} instance with the given amount and currency code.
+  #
+  # @param amount [Numeric] the financial value
+  # @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)
+
+  # 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 nil      then nil
+    when Currency then currency
+    when String   then Registry.currencies[currency]
+    else raise ArgumentError, "currency must be [Currency] ot [String] (#{currency})"
+    end
+  end
+end

data/lib/minting/mint/parser.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+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 = Mint.currency(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.
+  def parse_amount(input)
+    # Remove any charater that is not a digit, comma or period
+    numeric = input.scan(/[\d.,-]/).join
+    numeric = normalize_separators(numeric)
+    Rational(numeric)
+  end
+
+  # Converts locale-specific decimal/thousand separators into a plain decimal string.
+  def normalize_separators(numeric)
+    case [numeric.count(','), numeric.count('.')]
+    in [0, 0] | [0, 1] then numeric              # Nothing to normalize (e.g. "1500" or "34.21").
+    in [1, 0]          then numeric.tr(',', '.') # Only one comma: decimal (e.g. 19,99 or 1,234).
+    in [c, p] if c > 1 && p > 1 # Both separators appear multiple times
+      raise ArgumentError, "could not distinguish decimal and thousand separators in '#{numeric}'"
+    in [c, p] if c > 0 && p > 0 # Commas and dots: the rightmost one is the decimal separator.
+      if numeric.rindex(',') > numeric.rindex('.')
+        numeric.delete('.').tr(',', '.')
+      else
+        numeric.delete(',')
+      end
+    else # Multiple of the same separator only (e.g. 1,234,567) — all are thousands.
+      numeric.delete(',.')
+    end
+  end
+
+  def parse_currency(input)
+    case input
+    when nil then return nil
+    when String
+      # Prefer an explicit ISO 4217 code (e.g. "USD 1,234.56") over symbol matching.
+      currency = Mint.currency(input[/\b([A-Z_]+)\b/, 1])
+      return currency if currency
+
+      # Fall back to registered symbols, longest first (HK$ before $).
+      Mint.currency_symbols.each do |symbol, currency|
+        return currency if input.include?(symbol)
+      end
+    end
+    raise ArgumentError, 'Currency could not be detected'
+  end
+end

data/lib/minting/mint/refinements.rb

@@ -25,8 +25,6 @@ module Mint
   end
 
   refine String do
-    def to_money(currency)
-      Mint.money(to_r, currency)
-    end
+    def to_money(currency) = Mint.money(to_r, currency)
   end
 end

data/lib/minting/mint/registry.rb

@@ -2,61 +2,27 @@
 
 # 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] 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."
-  end
-
-  # 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)
-    currency.is_a?(Currency) ? currency : CurrencyStore.currencies[currency]
-  end
-
-  # Registers a new currency if not already registered.
-  #
-  # @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: 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.
+  # Registers a new currency, raising a KeyError if already registered.
   #
   # @param code [String] the unique currency code
-  # @param subunit [Integer] the decimal subunit precision
+  # @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:, symbol: '', priority: 0)
+  def self.register_currency(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 only letters or '_' ('USD',, 'MY_COIN')"
+            "Currency code must have only letters or '_' ('USD',, 'MY_COIN')"
     end
 
-    currencies = CurrencyStore.currencies
+    currencies = Registry.currencies
     raise KeyError, "Currency: #{code} already registered" if currencies[code]
 
     currency = currencies[code] = Currency.new(code:, subunit:, symbol:, priority:)
-    CurrencyStore.invalidate_symbols_cache
+    Registry.invalidate_symbols_cache
     currency
   end
 
@@ -66,6 +32,6 @@ module Mint
   # @return [Array<Array<String, Currency>>] sorted symbol-to-currency mappings
   # @api private
   def self.currency_symbols
-    CurrencyStore.currency_symbols
+    Registry.currency_symbols
   end
 end

data/lib/minting/mint/world_currencies.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Mint
+  module_function
+
+  # Loads ISO world currencies from YAML file into the registry.
+  #
+  # @return [Hash{String => Currency}] ISO-4217 world currencies mapped by code
+  # @api private
+  def world_currencies
+    @world_currencies ||= begin
+      path = File.join(File.expand_path('../data', __dir__), 'currencies.yaml')
+
+      YAML.load_file(path).to_h { |entry| [entry['code'], Currency.new(**entry.transform_keys(&:to_sym))] }
+    end.freeze
+  end
+end

data/lib/minting/mint.rb

@@ -2,5 +2,16 @@
 
 require 'minting/mint/currency'
 require 'minting/mint/currency_store'
+require 'minting/mint/mint'
+require 'minting/mint/parser'
 require 'minting/mint/registry'
 require 'minting/mint/refinements'
+require 'minting/mint/world_currencies'
+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'

data/lib/minting/money/allocation.rb

@@ -18,7 +18,7 @@ module Mint
       raise ArgumentError, 'Proportions total must not be zero' if whole.zero?
 
       subunit = currency.subunit
-      amounts = proportions.map { |rate| (amount * rate.to_r / whole).round(subunit) }
+      amounts = proportions.map { |rate| Rational(amount * rate, whole).round(subunit) }
       allocate_left_over!(amounts: amounts, left_over: amount - amounts.sum)
     end
 

data/lib/minting/money/arithmetics.rb

@@ -53,9 +53,7 @@ module Mint
     # Unary negation operator. Returns a new {Money} instance with the inverted sign.
     #
     # @return [Money] negated Money instance
-    def -@
-      mint(-amount)
-    end
+    def -@ = mint(-amount)
 
     # Performs multiplication of the monetary value by a standard scalar Numeric.
     #

data/lib/minting/money/comparable.rb

@@ -7,9 +7,11 @@ 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?
-
-      eql?(other)
+      case other
+      when 0           then zero?
+      when Mint::Money then amount == other.amount && currency == other.currency
+      else                  false
+      end
     end
 
     def eql?(other)

data/lib/minting/money/constructors.rb

@@ -5,7 +5,7 @@ module Mint
   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
+    # @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)
       raise ArgumentError, 'amount must be Numeric' unless amount.is_a?(Numeric)

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.5.1'
+  VERSION = '1.6.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: minting
 version: !ruby/object:Gem::Version
-  version: 1.5.1
+  version: 1.6.0
 platform: ruby
 authors:
 - Gilson Ferraz
@@ -44,9 +44,11 @@ files:
 - lib/minting/mint.rb
 - lib/minting/mint/currency.rb
 - lib/minting/mint/currency_store.rb
+- lib/minting/mint/mint.rb
+- lib/minting/mint/parser.rb
 - lib/minting/mint/refinements.rb
 - lib/minting/mint/registry.rb
-- lib/minting/money.rb
+- lib/minting/mint/world_currencies.rb
 - lib/minting/money/allocation.rb
 - lib/minting/money/arithmetics.rb
 - lib/minting/money/coercion.rb
@@ -55,7 +57,6 @@ files:
 - lib/minting/money/conversion.rb
 - lib/minting/money/formatting.rb
 - lib/minting/money/money.rb
-- lib/minting/money/parse.rb
 - lib/minting/version.rb
 - minting.gemspec
 homepage: https://github.com/gferraz/minting

data/lib/minting/money/parse.rb

@@ -1,79 +0,0 @@
-# frozen_string_literal: true
-
-module Mint
-  # Money parser
-  class Money
-    # 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 self.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 = parse_currency(currency) || parse_currency(input)
-      raise ArgumentError, "Currency [#{currency}] not registered" unless currency
-
-      amount = currency.normalize_amount(parse_amount(input))
-      new(amount, currency)
-    end
-
-    # Extracts a numeric value from input that should only contain an amount.
-    def self.parse_amount(input)
-      # Remove any charater that is not a digit, comma or period
-      numeric = input.scan(/[\d.,-]/).join
-      numeric = normalize_separators(numeric)
-      Rational(numeric)
-    end
-
-    # Converts locale-specific decimal/thousand separators into a plain decimal string.
-    def self.normalize_separators(numeric)
-      case [numeric.count(','), numeric.count('.')]
-      in [0, 0] | [0, 1] then numeric              # Nothing to normalize (e.g. "1500" or "34.21").
-      in [1, 0]          then numeric.tr(',', '.') # Only one comma: decimal (e.g. 19,99 or 1,234).
-      in [c, p] if c > 1 && p > 1 # Both separators appear multiple times
-        raise ArgumentError, "could not distinguish decimal and thousand separators in '#{numeric}'"
-      in [c, p] if c > 0 && p > 0 # Commas and dots: the rightmost one is the decimal separator.
-        if numeric.rindex(',') > numeric.rindex('.')
-          numeric.delete('.').tr(',', '.')
-        else
-          numeric.delete(',')
-        end
-      else # Multiple of the same separator only (e.g. 1,234,567) — all are thousands.
-        numeric.delete(',.')
-      end
-    end
-
-    def self.parse_currency(input)
-      case input
-      when NilClass, Mint::Currency then return input
-      when String
-        # Prefer an explicit ISO 4217 code (e.g. "USD 1,234.56") over symbol matching.
-        currency = Mint.currency(input[/\b([A-Z]+)\b/, 1])
-        return currency if currency
-
-        # Fall back to registered symbols, longest first (HK$ before $).
-        Mint.currency_symbols.each do |symbol, currency|
-          return currency if input.include?(symbol)
-        end
-      end
-      raise ArgumentError, 'currency could not be detected; pass a currency code as the second argument'
-    end
-
-    private_class_method :parse_amount, :normalize_separators,
-                         :parse_currency
-  end
-end

data/lib/minting/money.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-require 'minting/money/parse'
-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'