Module: Mint

Extended by:
Mint
Included in:
Mint
Defined in:
lib/minting/mint/mint.rb,
lib/minting/money/clamp.rb,
lib/minting/money/money.rb,
lib/minting/mint/dsl/range.rb,
lib/minting/money/coercion.rb,
lib/minting/mint/dsl/string.rb,
lib/minting/mint/dsl/numeric.rb,
lib/minting/money/comparable.rb,
lib/minting/money/conversion.rb,
lib/minting/currency/currency.rb,
lib/minting/money/format/to_s.rb,
lib/minting/mint/dsl/top_level.rb,
lib/minting/mint/parser/parser.rb,
lib/minting/money/constructors.rb,
lib/minting/mint/locale_backend.rb,
lib/minting/mint/registry/zeros.rb,
lib/minting/mint/registry/symbols.rb,
lib/minting/mint/parser/separators.rb,
lib/minting/mint/registry/registry.rb,
lib/minting/money/allocation/split.rb,
lib/minting/money/format/formatting.rb,
lib/minting/money/arithmetics/methods.rb,
lib/minting/mint/registry/registration.rb,
lib/minting/money/allocation/allocation.rb,
lib/minting/money/arithmetics/operators.rb

Overview

Mint registry: manages all cached state

Defined Under Namespace

Modules: RangeStepPatch, Registry Classes: Currency, Money, UnknownCurrency

Class Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Class Attribute Details

.locale_backend ⇒ Proc, ...

Optional callable that returns a Hash with locale-aware formatting defaults.

The callable receives no arguments and returns a Hash with these keys:

[+:decimal+]   Decimal separator (e.g. +","+)
[+:thousand+]  Thousands delimiter (e.g. +"."+)
[+:format+]    Format template string (e.g. +"%<amount>f %<symbol>s"+)

When set, #to_s and #format use these values as fallbacks when the corresponding parameter is not explicitly provided.

Examples:

Rails I18n integration (in minting-rails railtie)

Mint.locale_backend = -> {
  fmt = I18n.t('number.currency.format')
  {
    decimal: fmt[:separator],
    thousand: fmt[:delimiter],
    format: fmt[:format] == '%n %u' ? '%<amount>f %<symbol>s' : '%<symbol>s%<amount>f'
  }
}

Returns:

  • (Proc, #call, nil) 


27
28
29
 
# File 'lib/minting/mint/locale_backend.rb', line 27

def locale_backend
  @locale_backend
end

Class Method Details

.currency_for_code(code) ⇒ Currency?

Looks up a registered currency by its alpha code.

Unlike currency, this performs a direct hash lookup and only accepts strings.

Parameters:

  • code (String) —

    the currency code

Returns:

  • (Currency, nil) —

    the registered Currency, or nil if not found



27
28
29
 
# File 'lib/minting/mint/mint.rb', line 27

def self.currency_for_code(code)
  Registry.currencies[code]
end

.currency_for_symbol(symbol) ⇒ Currency?

Looks up a currency by its display symbol.

Parameters:

  • symbol (String) —

    the display symbol (e.g. “$”, “R$”)

Returns:

  • (Currency, nil) —

    the highest-priority currency for the symbol



35
36
37
 
# File 'lib/minting/mint/mint.rb', line 35

def self.currency_for_symbol(symbol)
  Registry.currency_for_symbol(symbol)
end

.money(amount, currency_code) ⇒ Money

Creates a new Money instance with the given amount and currency code.

Parameters:

  • amount (Numeric) —

    the financial value

  • currency_code (Currency, String) —

    Currency code

Returns:

  • (Money) —

    the instantiated Money object

Raises:

  • (ArgumentError) —

    if the currency code is not registered



15
 
# File 'lib/minting/mint/mint.rb', line 15

def self.money(amount, currency_code) = Money.create(amount, currency_code)

.register_currency(code:, subunit: 0, symbol: '', priority: 0) ⇒ Currency

Registers a new currency, raising a KeyError if already registered.

Parameters:

  • code (String) —

    the unique currency code

  • subunit (Integer) (defaults to: 0) —

    the decimal subunit precision, defaults to 0

  • symbol (String) (defaults to: '') —

    the display symbol

  • priority (Integer) (defaults to: 0) —

    parser precedence priority

Returns:

  • (Currency) —

    the newly registered Currency instance

Raises:

  • (ArgumentError) —

    if the code contains invalid characters

  • (KeyError) —

    if the currency code is already registered



56
57
58
 
# File 'lib/minting/mint/mint.rb', line 56

def self.register_currency(code:, subunit: 0, symbol: '', priority: 0)
  Registry.register(code:, subunit:, symbol:, priority:)
end

.use_top_level_constants! ⇒ Object

Registers top-level ::Money and ::Currency constants as aliases for Mint’s classes.

Raises:

  • (NameError) —

    if ::Money or ::Currency are already defined and differ



8
9
10
11
12
13
14
15
16
 
# File 'lib/minting/mint/dsl/top_level.rb', line 8

def self.use_top_level_constants!
  if !defined?(::Money) && !defined?(::Currency)
    require 'minting/mint/aliases'
  elsif ::Money == Mint::Money && ::Currency == Mint::Currency
    warn 'Warning: Money and Currency already defined as Mint aliases, skipping'
  else
    raise NameError, 'Cannot define top-level Money or Currency constants: already defined'
  end
end

.world_currencies ⇒ Hash{String => Currency}

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns the frozen world-currencies hash.

Returns:

  • (Hash{String => Currency}) —

    the frozen world-currencies hash



19
 
# File 'lib/minting/mint/mint.rb', line 19

def self.world_currencies = Registry.world_currencies

.zero(currency) ⇒ Money

Returns a zero Money in the given currency, useful as a default value for discounts, totals, or placeholders.

Parameters:

  • currency (String, Currency) —

    a currency code or object

Returns:

  • (Money) —

    a frozen zero-Money

Raises:

  • (ArgumentError) —

    if the currency can’t be resolved



45
 
# File 'lib/minting/mint/mint.rb', line 45

def self.zero(currency) = Registry.zero_for(Currency.resolve!(currency))

Instance Method Details

#parse(input, currency = nil) ⇒ Money

Parses a human-readable money string into a Money object.

Examples:

With explicit currency

Money.parse('19.99', 'USD')    #=> [USD 19.99]
Money.parse('1.234,56', 'EUR') #=> [EUR 1234.56]

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]

Parameters:

  • input (String) —

    Amount input, optionally including a currency symbol or code

  • currency (String, Symbol, Currency, nil) (defaults to: nil) —

    ISO code when not present in input

Returns:

Raises:

  • (ArgumentError) —

    when input is invalid or currency cannot be determined



22
23
24
25
26
27
28
29
30
31
32
33
 
# File 'lib/minting/mint/parser/parser.rb', line 22

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 = Currency.resolve(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