minting 1.9.7 → 2.0.0

data/lib/minting/money/money.rb

@@ -8,9 +8,13 @@ require_relative 'clamp'
 require_relative 'coercion'
 require_relative 'comparable'
 require_relative 'constructors'
+require_relative 'parse'
 require_relative 'conversion'
-require_relative 'format/formatting'
+require_relative 'format/validator'
+require_relative 'format/formatter'
 require_relative 'format/to_s'
+require_relative 'format/format'
+require_relative 'rounding'
 
 module Mint
   # Represents a monetary value paired with a currency.
@@ -19,11 +23,14 @@ module Mint
   class Money
     attr_reader :amount, :currency
 
+    # Money::Currency is the canonical way to access Currency class
+    Currency = Mint::Currency
+
     # Returns the ISO 3-letter currency code string.
     #
     # @return [String] the ISO currency code (e.g., "USD", "EUR", "BRL")
     # @example
-    #   Mint.money(100, 'USD').currency_code  #=> "USD"
+    #   Money.from(100, 'USD').currency_code  #=> "USD"
     def currency_code = currency.code
 
     # Returns the monetary amount expressed in the currency's smallest unit (fractional units).
@@ -31,17 +38,26 @@ module Mint
     #
     # @return [Integer] the amount in fractional units
     # @example
-    #   Mint.money(1234.56, 'USD').subunits  #=> 123456
-    #   Mint.money(1000, 'JPY').subunits     #=> 1000
-    #   Mint.money(123.456, 'IQD').subunits  #=> 123456
+    #   Money.from(1234.56, 'USD').subunits  #=> 123456
+    #   Money.from(1000, 'JPY').subunits     #=> 1000
+    #   Money.from(123.456, 'IQD').subunits  #=> 123456
     def subunits = (amount * currency.fractional_multiplier).to_i
 
+    # Returns the whole-unit (integral) part of the amount.
+    # @example
+    #   Money.from(1234.56, 'USD').integral  #=> 1234
+    #   Money.from(1000, 'JPY').integral     #=> 1000
+    #   Money.from(-9.99, 'USD').integral    #=> -9
+    def integral = amount.to_i
+
+    alias to_i integral
+
     # Returns the fractional part of the amount.
     # @example
-    #   Mint.money(1234.56, 'USD').fractional  #=> 56
-    #   Mint.money(1000, 'JPY').fractional     #=> 0
-    #   Mint.money(123.456, 'IQD').fractional  #=> 456
-    def fractional = ((amount.abs % 1) * currency.fractional_multiplier).to_i
+    #   Money.from(1234.56, 'USD').fractional  #=> 56
+    #   Money.from(1000, 'JPY').fractional     #=> 0
+    #   Money.from(123.456, 'IQD').fractional  #=> 456
+    def fractional = ((amount - amount.to_i) * currency.fractional_multiplier).to_i
 
     # Generates a stable hash key for Money instances.
     #

data/lib/minting/money/parse.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Mint
+  # :nodoc:
+  class Money
+    # 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)
+      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)
+      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
+    #   Money.parse!('19.99', 'USD')    #=> [USD 19.99]
+    #   Money.parse!('garbage', 'USD')  #=> ArgumentError
+    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(input, currency)
+      raise ArgumentError, "Currency [#{currency}] not found" unless currency
+
+      amount = parse_amount(input)
+      raise ArgumentError, "Could not parse [#{input}]" unless amount
+
+      amount = currency.normalize_amount(amount)
+      new(amount, currency)
+    end
+
+    class << self
+      private
+
+      # Extracts a numeric value from input that should only contain an amount.
+      def parse_amount(input)
+        accounting_negative = input.start_with?('(') && input.end_with?(')')
+
+        numeric_input = input.gsub(/[^\d.,-]/, '')
+        numeric = parse_separators(numeric_input)
+        return nil unless numeric
+
+        amount = Rational(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.
+      def parse_currency(input, currency = nil)
+        input.scan(/\b([A-Z_]+)\b/) do |(code)|
+          found = Currency.for_code(code)
+          return found if found
+        end
+
+        found = Registry.detect_currency(input)
+        return found if found
+
+        Currency.resolve(currency)
+      end
+
+      # Converts locale-specific decimal/thousand separators into a plain decimal string.
+      def parse_separators(numeric)
+        return nil unless numeric.match?(/\d/)
+
+        case classify_separators(numeric)
+        when :decimal_period   then numeric
+        when :decimal_comma    then numeric.tr(',', '.')
+        when :thousands_comma  then numeric.delete(',')
+        when :thousands        then numeric.delete('.,')
+        when :invalid          then nil
+        when :mixed
+          if numeric.rindex(',') > numeric.rindex('.')
+            numeric.delete('.').tr(',', '.')
+          else
+            numeric.delete(',')
+          end
+        end
+      end
+
+      # Classifies the separator pattern in a numeric string.
+      def classify_separators(numeric)
+        case [numeric.count('.'), numeric.count(',')]
+        in [0, 1] if numeric[-4] == ',' then :thousands_comma
+        in [0, 1]                       then :decimal_comma
+        in [0, 0] | [1, 0]              then :decimal_period
+        in [p, c] if p > 1 && c > 1     then :invalid
+        in [p, c] if p > 0 && c > 0     then :mixed
+        else                                 :thousands
+        end
+      end
+    end
+  end
+end

data/lib/minting/money/rounding.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Mint
+  # :nodoc:
+  class Money
+    # Executes a block with a specific rounding mode applied to all money
+    # construction, parsing, change, allocation, and split operations.
+    #
+    # Restores the previous mode (or default) when the block exits, even on
+    # exception.
+    #
+    # Rounding-mode support is loaded lazily on first call. Once loaded,
+    # +Currency#normalize_amount+ is patched to dispatch through the
+    # rounding module, 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.
+    #
+    # @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, &)
+      require_relative '../mint/rounding' unless defined?(Mint::Rounding)
+      Mint::Rounding.with_mode(mode, &)
+    end
+  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.9.7'
+  VERSION = '2.0.0'
 end

data/lib/minting.rb

@@ -3,12 +3,21 @@
 require 'minting/mint'
 require 'minting/version'
 
-# By default, expose Mint::Money as the top-level Money constant for
-# convenience. If Money is already defined (e.g. by the `money` gem), warn
-# and skip so both libraries can coexist in the same process without
-# corrupting either class.
-if defined?(Money) && Money != Mint::Money
-  warn "minting: top-level Money is already defined (#{Money}); skipping auto-bind. Use Mint::Money."
-else
-  Money = Mint::Money unless defined?(Money)
+# @!parse
+#   # Top-level constant auto-bound to {Mint::Money} for convenience.
+#   Money = Mint::Money
+
+# Top-level constant auto-bound to {Mint::Money} for convenience.
+#
+# Set at require-time via `require 'minting'`. If {::Money} is already
+# defined (e.g. by the `money` gem), a warning is emitted and the existing
+# constant is preserved — use {Mint::Money} explicitly in that case.
+#
+# @see Mint::Money
+# @note This is a **breaking change from v1.x** where both +Money+ and
+#   +Currency+ required explicit opt-in via +Mint.use_top_level_constants!+.
+Money = Mint::Money unless defined?(Money)
+
+if Money != Mint::Money
+  warn "minting: top-level Money was already defined (#{Money}); skipping auto-bind! Use Mint::Money."
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: minting
 version: !ruby/object:Gem::Version
-  version: 1.9.7
+  version: 2.0.0
 platform: ruby
 authors:
 - Gilson Ferraz
@@ -36,17 +36,6 @@ files:
 - bin/check-currencies
 - bin/console
 - bin/setup
-- doc/Mint.html
-- doc/Mint/Currency.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/Numeric.html
-- doc/String.html
-- doc/_index.html
 - doc/agents/api_review-2026-06-15.md
 - doc/agents/copilot-instructions.md
 - doc/agents/expired/AGENTS.md
@@ -54,31 +43,18 @@ files:
 - 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
-- doc/css/style.css
-- doc/file.README.html
-- doc/file_list.html
-- doc/frames.html
-- doc/index.html
-- doc/js/app.js
-- doc/js/full_list.js
-- doc/js/jquery.js
-- doc/method_list.html
-- doc/top-level-namespace.html
 - lib/minting.rb
+- lib/minting/aliases.rb
 - lib/minting/currency/currency.rb
+- lib/minting/data/crypto-currencies.yaml
 - lib/minting/data/world-currencies.yaml
 - lib/minting/mint.rb
-- lib/minting/mint/aliases.rb
 - lib/minting/mint/dsl/numeric.rb
 - lib/minting/mint/dsl/range.rb
 - lib/minting/mint/dsl/string.rb
 - lib/minting/mint/i18n.rb
 - lib/minting/mint/mint.rb
-- lib/minting/mint/parser/parser.rb
-- lib/minting/mint/parser/separators.rb
+- lib/minting/mint/registry/crypto.rb
 - lib/minting/mint/registry/registration.rb
 - lib/minting/mint/registry/registry.rb
 - lib/minting/mint/registry/symbols.rb
@@ -93,9 +69,13 @@ files:
 - lib/minting/money/comparable.rb
 - lib/minting/money/constructors.rb
 - lib/minting/money/conversion.rb
-- lib/minting/money/format/formatting.rb
+- lib/minting/money/format/format.rb
+- lib/minting/money/format/formatter.rb
 - lib/minting/money/format/to_s.rb
+- lib/minting/money/format/validator.rb
 - lib/minting/money/money.rb
+- lib/minting/money/parse.rb
+- lib/minting/money/rounding.rb
 - lib/minting/version.rb
 - minting.gemspec
 homepage: https://github.com/gferraz/minting