Module: Mint

Extended by:
Mint
Included in:
Mint
Defined in:
lib/minting/mint/dsl.rb,
lib/minting/mint/mint.rb,
lib/minting/mint/parser.rb,
lib/minting/money/money.rb,
lib/minting/money/coercion.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/currency.rb,
lib/minting/mint/currency/world_currencies.rb,
lib/minting/mint/currency/currency_registry.rb

Overview

Mint currency store (internal)

Defined Under Namespace

Modules: CurrencyRegistry 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 CurrencyRegistry.currencies[currency]
  else raise ArgumentError, "currency must be [Currency] ot [String] (#{currency})"
  end
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



40
41
42
 
# File 'lib/minting/mint/mint.rb', line 40

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

.use_top_level_constants! ⇒ Object 



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

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.

Loads ISO world currencies from YAML file into the registry.

Returns:

  • (Hash{String => Currency}) —

    ISO-4217 world currencies mapped by code



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

def self.world_currencies
  @world_currencies ||= begin
    path = File.join(File.expand_path('../../data', __dir__), 'world-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