minting 1.8.2 → 1.9.0

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

@@ -1,29 +1,14 @@
 # frozen_string_literal: true
 
 module Mint
-  # Formatting functionality for Money objects
+  # :nodoc:
   class Money
     private
 
-    # Resolves format/decimal/thousand from locale_backend when not explicitly given.
+    # Resolves the format template and amount based on the amount's sign
+    # (negative_format/zero_format may override both the template and negate the value)
     # @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)
+    def resolve_format(format)
       negative_format = format[:negative]
       zero_format = format[:zero]
 
@@ -32,7 +17,7 @@ module Mint
       elsif amount.zero? && zero_format
         [zero_format,     amount]
       else
-        [format[:positive], amount]
+        [format[:positive] || '%<symbol>s%<amount>f', amount]
       end
     end
 
@@ -44,17 +29,62 @@ module Mint
       raise ArgumentError, "Unknown format parameter(s): #{unknown.inspect}. " unless unknown.empty?
     end
 
+    # Validates +decimal+ and +thousand+ separator arguments.
+    # @private
+    def validate_separators!(decimal:, thousand:)
+      case decimal
+      when '' then raise ArgumentError, 'decimal must be a non-empty'
+      when nil # :noop
+      when String
+        raise ArgumentError, "decimal and thousand cannot be identical: #{decimal.inspect}" if decimal == thousand
+      else raise ArgumentError, "decimal must be a String, false, or nil, got #{decimal.inspect}"
+      end
+
+      case thousand
+      when false, nil, String # :noop
+      else raise ArgumentError, "thousand must be a String, false, or nil, got #{thousand.inspect}"
+      end
+    end
+
+    def apply_thousand_separator(string, decimal:, thousand:)
+      return string if !thousand || thousand.empty?
+
+      # Apply thousands only to the integral portion, using the decimal as boundary
+      parts = string.split(/(?<=\d)#{Regexp.escape(decimal)}(?=\d)/, 2)
+      parts[0].gsub!(/(\d)(?=(?:\d{3})+(?:[^\d]|$))/, "\\1#{thousand}")
+      parts.join(decimal)
+    end
+
     # Applies a format template to produce a formatted string representation.
     # @private
-    def format_amount(format)
-      format, value = select_format(format)
-      format ||= '%<symbol>s%<amount>f'
-      # Automatically adjust decimal places based on currency subunit if missing
-      format = format.gsub(/%<amount>(\s*\+?\d*)f/, "%<amount>\\1.#{currency.subunit}f")
-
-      refs = format.scan(/%<(\w+)>/).flatten.map(&:to_sym)
-      all_args = { amount: value, currency: currency_code, symbol: currency.symbol }
-      Kernel.format(format, **all_args.slice(*refs))
+    #
+    def format_amount(format, decimal:, thousand:)
+      subunit = currency.subunit
+      resolved_format, adjusted_amount = resolve_format(format)
+
+      # Inject the currency's subunit precision into %<amount>f specifiers
+      # e.g. '%<amount>f' becomes '%<amount>.2f' for USD
+      resolved_format = resolved_format.gsub(/%<amount>(\s*\+?\d*)f/, "%<amount>\\1.#{subunit}f")
+
+      # Zero-subunit currencies (e.g. JPY) have no fractional part —
+      # strip %<fractional>d specifiers entirely since there's no valid integer for "nothing"
+      resolved_format.gsub!(/%<fractional>[^%]*?d/, '') if subunit.zero?
+
+      result = Kernel.format(resolved_format, {
+                               amount: adjusted_amount,
+                               currency: currency_code,
+                               symbol: currency.symbol,
+                               integral: adjusted_amount.to_i,
+                               fractional: fractional
+                             })
+
+      # Substitute decimal first, while the dot is still unambiguous
+      result.gsub!(/(?<=\d)\.(?=\d)/, decimal) if decimal != '.'
+
+      return result if adjusted_amount.abs < 1000
+
+      # Apply thousands only to the integral portion, using the decimal as boundary
+      apply_thousand_separator(result, decimal:, thousand:)
     end
   end
 end

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

@@ -1,14 +1,26 @@
 # frozen_string_literal: true
 
 module Mint
-  # Formatting functionality for Money objects
+  # :nodoc:
   class Money
+    PRESETS = {
+      amount: { format: '%<amount>f' },
+      accounting: { format: { negative: '(%<symbol>s%<amount>f)' } },
+      european: { format: '%<amount>f %<symbol>s', decimal: ',', thousand: '.' },
+      currency: { format: '%<currency>s %<amount>f' }
+    }.freeze
+
     # Formats money as a string with customizable format, thousand delimiter, and decimal
     #
+    # @param preset [Symbol, nil] Named format preset, one of:
+    #   +:accounting+, +:european+, +:amount+, +:currency+.
+    #   When provided, expands to the preset's format options and merges
+    #   with any explicit keyword arguments (kwargs override the preset).
     # @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:
+    #   (%<symbol>s, %<amount>f, %<currency>s, %<integral>d, %<fractional>d),
+    #   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:
     #
     #     money.to_s(format: { negative: '(%<symbol>s%<amount>f)' })
     #
@@ -23,8 +35,9 @@ module Mint
     #   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
-    #   is empty, or the Hash contains an unrecognised key.
+    # @raise [ArgumentError] if +preset+ is not a recognised name, or if
+    #   +format+ is not a String or Hash, the Hash is empty, or the Hash
+    #   contains an unrecognised key.
     #
     # @example Basic formatting
     #   money = Mint.money(1234.56, 'USD')
@@ -32,12 +45,25 @@ module Mint
     #   money.to_s(thousand: '.', decimal: ',')  #=> "$1.234,56"
     #   money.to_s(decimal: ',', thousand: '')   #=> "$1234,56"
     #
+    # @example Preset formats
+    #   loss = Mint.money(-1234.56, 'USD')
+    #   loss.to_s(:accounting)                   #=> "($1,234.56)"
+    #   money.to_s(:european)                    #=> "1.234,56 €"
+    #   money.to_s(:amount)                      #=> "1234.56"
+    #   money.to_s(:currency)                    #=> "USD 1234.56"
+    #
     # @example Custom formats
     #   money.to_s(format: '%<amount>f')                    #=> "1234.56"
     #   money.to_s(format: '%<currency>s %<amount>f')       #=> "USD 1234.56"
     #   money.to_s(format: '%<amount>f %<symbol>s')         #=> "1234.56 $"
     #   money.to_s(format: '%<symbol>s%<amount>+f')         #=> "$+1234.56"
     #
+    # @example Integral & fractional parts
+    #   money.to_s(format: '%<integral>d.%<fractional>02d')  #=> "1234.56"
+    #   price = Mint.money(0.99, 'USD')
+    #   price.to_s(format: '%<integral>d dollars and %<fractional>02d cents')
+    #   #=> "0 dollars and 99 cents"
+    #
     # @example Per-sign Hash format (accounting parentheses)
     #   loss = Mint.money(-1234.56, 'USD')
     #   loss.to_s(format: { negative: '(%<symbol>s%<amount>f)' }) #=> "($1,234.56)"
@@ -50,7 +76,17 @@ module Mint
     # @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)
+    def to_s(preset = nil, format: nil, decimal: nil, thousand: nil, width: nil)
+      if preset
+        config = PRESETS.fetch(preset) { raise ArgumentError, "Unknown format preset: #{preset.inspect}" }
+        format ||= config[:format]
+        decimal ||= config[:decimal]
+        thousand ||= config[:thousand]
+        width ||= config[:width]
+      end
+
+      validate_separators!(decimal:, thousand:)
+
       format, decimal, thousand = resolve_locale_for(format, decimal, thousand)
 
       case format
@@ -60,15 +96,7 @@ module Mint
       else        raise ArgumentError, 'Invalid format. Only String or Hash are accepted'
       end
 
-      formatted = format_amount(format)
-
-      formatted.tr!('.', decimal) if decimal != '.'
-
-      unless thousand.empty?
-        # Regular expression courtesy of Money gem
-        # Matches digits followed by groups of 3 digits until non-digit or end
-        formatted.gsub!(/(\d)(?=(?:\d{3})+(?:[^\d]{1}|$))/, "\\1#{thousand}")
-      end
+      formatted = format_amount(format, decimal: decimal, thousand: thousand)
 
       width ? formatted.rjust(width) : formatted
     end

data/lib/minting/money/money.rb

@@ -13,7 +13,9 @@ require_relative 'format/formatting'
 require_relative 'format/to_s'
 
 module Mint
-  # Money constructors
+  # Represents a monetary value paired with a currency.
+  # Money objects are immutable and support arithmetic, comparison,
+  # formatting, allocation, and parsing operations.
   class Money
     # The default display format pattern for formatting monetary values.
     # Uses `%<symbol>s` for the currency symbol and `%<amount>f` for the rounded amount.
@@ -33,10 +35,17 @@ module Mint
     #
     # @return [Integer] the amount in fractional units
     # @example
-    #   Mint.money(1234.56, 'USD').fractional  #=> 123456
-    #   Mint.money(1000, 'JPY').fractional     #=> 1000
-    #   Mint.money(123.456, 'IQD').fractional  #=> 123456
-    def fractional = (amount * currency.fractional_multiplier).to_i
+    #   Mint.money(1234.56, 'USD').subunits  #=> 123456
+    #   Mint.money(1000, 'JPY').subunits     #=> 1000
+    #   Mint.money(123.456, 'IQD').subunits  #=> 123456
+    def subunits = (amount * currency.fractional_multiplier).to_i
+
+    # 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
 
     # Generates a stable hash key for Money instances.
     #

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.8.2'
+  VERSION = '1.9.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: minting
 version: !ruby/object:Gem::Version
-  version: 1.8.2
+  version: 1.9.0
 platform: ruby
 authors:
 - Gilson Ferraz
@@ -75,7 +75,7 @@ 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/i18n.rb
 - lib/minting/mint/mint.rb
 - lib/minting/mint/parser/parser.rb
 - lib/minting/mint/parser/separators.rb