minting 2.1.1 → 2.3.0

data/lib/minting/money/parse.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'parse/separator_parser'
+
 module Mint
   # :nodoc:
   class Money
@@ -8,7 +10,15 @@ module Mint
     # 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+
+    # @param positional_currency [String, Currency, nil] deprecated positional
+    #   fallback currency when none is present in +input+
+    # @param default_currency [String, Currency, nil] fallback currency when none is present in +input+
+    #   An embedded currency code or symbol takes precedence over this argument.
+    #   The positional form is deprecated; use +default_currency:+ instead.
+    # @param decimal [String, nil] decimal separator used by the input source.
+    #   When omitted, it is inferred from +thousand:+ or separator positions.
+    # @param thousand [String, nil] thousands separator used by the input source.
+    #   When omitted, it is inferred from +decimal:+ or separator positions.
     # @return [Money, nil]
     #
     # @example With explicit currency
@@ -18,63 +28,95 @@ module Mint
     # @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)
+    #   Money.parse('123,456', 'EUR', decimal: ',') #=> [EUR 123.46]
+    #   Money.parse('123,456', 'USD', thousand: ',') #=> [USD 123456.00]
+    # @deprecated Pass the fallback currency as +default_currency:+.
+    def self.parse(input, positional_currency = nil, default_currency: nil, decimal: nil, thousand: nil)
+      if positional_currency
+        warn 'DEPRECATION: Money.parse positional currency is deprecated; use default_currency: instead.', uplevel: 1
+      end
       return nil unless input.is_a?(String)
 
       input = input.strip
       return nil if input.empty?
 
+      currency = default_currency || positional_currency
       currency = parse_currency(input, currency)
       return nil unless currency
 
-      amount = parse_amount(input)
+      amount = parse_amount(input, currency, decimal:, thousand:)
       return nil unless amount
 
       amount = currency.normalize_amount(amount)
-      new(amount, currency)
+      amount.zero? ? currency.zero : 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+
+    # @param positional_currency [String, Currency, nil] deprecated positional
+    #   fallback currency when none is present in +input+
+    # @param default_currency [String, Currency, nil] fallback currency when none is present in +input+
+    #   An embedded currency code or symbol takes precedence over this argument.
+    #   The positional form is deprecated; use +default_currency:+ instead.
+    # @param decimal [String, nil] decimal separator used by the input source.
+    #   When omitted, it is inferred from +thousand:+ or separator positions.
+    # @param thousand [String, nil] thousands separator used by the input source.
+    #   When omitted, it is inferred from +decimal:+ or separator positions.
     # @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)
+    # @deprecated Pass the fallback currency as +default_currency:+.
+    def self.parse!(input, positional_currency = nil, default_currency: nil, decimal: nil, thousand: nil)
+      if positional_currency
+        warn 'DEPRECATION: Money.parse! positional currency is deprecated; use default_currency: instead.', uplevel: 1
+      end
       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 = default_currency || positional_currency
       currency = parse_currency(input, currency)
       raise ArgumentError, "Currency [#{currency}] not found" unless currency
 
-      amount = parse_amount(input)
+      amount = parse_amount(input, currency, decimal:, thousand:)
       raise ArgumentError, "Could not parse [#{input}]" unless amount
 
       amount = currency.normalize_amount(amount)
-      new(amount, currency)
+      amount.zero? ? currency.zero : new(amount, currency)
     end
 
     class << self
       private
 
-      # Extracts a numeric value from input that should only contain an amount.
-      def parse_amount(input)
+      # Extracts one valid numeric value, allowing surrounding currency markers
+      # and uppercase annotation words (for example, "MAX 10.00 USD").
+      def parse_amount(input, currency, decimal: nil, thousand: nil)
         accounting_negative = input.start_with?('(') && input.end_with?(')')
+        return nil if (input.include?('(') || input.include?(')')) && !accounting_negative
 
-        numeric_input = input.gsub(/[^\d.,-]/, '')
-        numeric = parse_separators(numeric_input)
+        numeric_input = accounting_negative ? input[1...-1] : input
+        numeric_input = remove_currency_markers(numeric_input, currency)
+        numeric_input = numeric_input.gsub(/\b[A-Z_]+\b/, ' ').delete('[]').strip
+        numeric_input.sub!(/\A([+-])\s+/, '\\1')
+        return nil unless numeric_input.match?(/\A[+-]?\d[\d.,]*\z/)
+
+        numeric = parse_separators(numeric_input, decimal:, thousand:)
         return nil unless numeric
 
         amount = Rational(numeric)
         accounting_negative ? -amount : amount
       end
 
+      def remove_currency_markers(input, currency)
+        markers = [currency.symbol, currency.disambiguate_symbol].compact.uniq
+        markers.reduce(input) { |result, marker| result.gsub(marker, ' ') }
+      end
+
       # Extracts currency from a string by matching ISO code or symbol.
       #
       # Scans all uppercase words and returns the first registered code, falling
@@ -92,9 +134,17 @@ module Mint
         Currency.resolve(currency)
       end
 
-      # Converts locale-specific decimal/thousand separators into a plain decimal string.
-      def parse_separators(numeric)
+      # Converts decimal/thousand separators into a plain decimal string.
+      # An explicit decimal separator resolves otherwise ambiguous values.
+      def parse_separators(numeric, decimal: nil, thousand: nil)
+        return SeparatorParser.parse(numeric, decimal, thousand) if decimal || thousand
+
+        parse_heuristic_separators(numeric)
+      end
+
+      def parse_heuristic_separators(numeric)
         return nil unless numeric.match?(/\d/)
+        return nil unless valid_numeric_syntax?(numeric)
 
         case classify_separators(numeric)
         when :decimal_period   then numeric
@@ -122,6 +172,16 @@ module Mint
         else                                 :thousands
         end
       end
+
+      def valid_numeric_syntax?(numeric)
+        unsigned = numeric.delete_prefix('-').delete_prefix('+')
+        unsigned.match?(/\A\d+\z/) ||
+          unsigned.match?(/\A\d+[.,]\d+\z/) ||
+          unsigned.match?(/\A\d+(?:,\d{3})+\.\d+\z/) ||
+          unsigned.match?(/\A\d+(?:\.\d{3})+,\d+\z/) ||
+          unsigned.match?(/\A\d+(?:,\d{3})+\z/) ||
+          unsigned.match?(/\A\d+(?:\.\d{3})+\z/)
+      end
     end
   end
 end

data/lib/minting/money/rounding.rb

@@ -9,11 +9,10 @@ module Mint
     # Restores the previous mode (or default) when the block exits, even on
     # exception.
     #
-    # Rounding-mode support is activated on first call. Once activated,
-    # +Currency#normalize_amount+ dispatches through +Currency.rounding_mode+,
-    # adding ~10–35&ns of overhead to every money creation or mutation.
-    # When rounding modes are never used (the common case), the fast path
-    # incurs zero overhead.
+    # Rounding-mode support is activated on first call. Before activation,
+    # +Currency#normalize_amount+ uses a direct +Rational#round+ fast path with
+    # no thread-local lookup. Once activated, normalization reads the
+    # thread-local mode so custom rounding remains isolated per thread.
     #
     # @param mode [Symbol] one of: +:up+, +:down+, +:even+
     # @yield block to execute with the rounding mode active

data/lib/minting/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: minting
 version: !ruby/object:Gem::Version
-  version: 2.1.1
+  version: 2.3.0
 platform: ruby
 authors:
 - Gilson Ferraz
@@ -36,6 +36,7 @@ files:
 - bin/check-currencies
 - bin/console
 - bin/setup
+- doc/agents/AGENTS.md
 - doc/agents/api_review-2026-06-15.md
 - doc/agents/copilot-instructions.md
 - doc/agents/expired/AGENTS.md
@@ -43,6 +44,8 @@ files:
 - doc/agents/expired/gemini_gem_evaluation.md
 - doc/agents/expired/recommendations.md
 - doc/agents/expired/rubocop-issues.md
+- doc/api_review-2026-08-13.md
+- doc/security-report.md
 - lib/minting.rb
 - lib/minting/aliases.rb
 - lib/minting/currency/currency.rb
@@ -76,6 +79,7 @@ files:
 - lib/minting/money/format/validator.rb
 - lib/minting/money/money.rb
 - lib/minting/money/parse.rb
+- lib/minting/money/parse/separator_parser.rb
 - lib/minting/money/rounding.rb
 - lib/minting/version.rb
 - minting.gemspec
@@ -104,7 +108,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.17
+rubygems_version: 4.0.18
 specification_version: 4
 summary: Library to manipulate currency values
 test_files: []