Module: Mint

Extended by:
Mint
Included in:
Mint
Defined in:
lib/minting/mint/mint.rb,
lib/minting/mint/parser.rb,
lib/minting/money/money.rb,
lib/minting/mint/currency.rb,
lib/minting/mint/registry.rb,
lib/minting/money/coercion.rb,
lib/minting/mint/refinements.rb,
lib/minting/money/allocation.rb,
lib/minting/money/comparable.rb,
lib/minting/money/conversion.rb,
lib/minting/money/formatting.rb,
lib/minting/money/arithmetics.rb,
lib/minting/money/constructors.rb,
lib/minting/mint/currency_store.rb,
lib/minting/mint/world_currencies.rb

Overview

Mint currency store (internal)

Defined Under Namespace

Modules: Registry Classes: Currency, Money, UnknownCurrency

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.currency(currency) ⇒ Currency?

Finds a registered currency by its code, symbol, or retrieves it directly if already a Currency object.

Parameters:

  • currency (String, Currency) —

    the currency identifier or object

Returns:

  • (Currency, nil) —

    the registered Currency instance or nil if not found



22
23
24
25
26
27
28
29
 
# File 'lib/minting/mint/mint.rb', line 22

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

.currency_symbols ⇒ Array<Array<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.

Registered symbols sorted for detection: longest match wins, then parser priority. Internal API - used by Money parser.

Returns:

  • (Array<Array<String, Currency>>) —

    sorted symbol-to-currency mappings



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

def self.currency_symbols
  Registry.currency_symbols
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



14
15
16
17
18
19
20
21
22
23
24
25
26
27
 
# File 'lib/minting/mint/registry.rb', line 14

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 have only letters or '_' ('USD',, 'MY_COIN')"
  end

  currencies = Registry.currencies
  raise KeyError, "Currency: #{code} already registered" if currencies[code]

  currency = currencies[code] = Currency.new(code:, subunit:, symbol:, priority:)
  Registry.invalidate_symbols_cache
  currency
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.

Loads ISO world currencies from YAML file into the registry.

Returns:

  • (Hash{String => Currency}) —

    ISO-4217 world currencies mapped by code



10
11
12
13
14
15
16
 
# File 'lib/minting/mint/world_currencies.rb', line 10

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

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.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 = 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