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/parser/separators.rb,
lib/minting/money/allocation/split.rb,
lib/minting/money/format/formatting.rb,
lib/minting/currency/world_currencies.rb,
lib/minting/money/arithmetics/methods.rb,
lib/minting/currency/currency_registry.rb,
lib/minting/money/allocation/allocation.rb,
lib/minting/money/arithmetics/operators.rb

Overview

Mint currency store (internal)

Defined Under Namespace

Modules: CurrencyRegistry, RangeStepPatch 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 NilClass then nil
  when Currency then currency
  when String   then CurrencyRegistry.currencies[currency]
  else          raise ArgumentError, "currency must be [Currency], [String] or nil (#{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

Returns the newly registered Currency instance.

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



54
55
56
 
# File 'lib/minting/mint/mint.rb', line 54

def self.register_currency(code:, subunit: 0, symbol: '', priority: 0)
  CurrencyRegistry.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.

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/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

.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 is not registered



37
38
39
40
41
42
43
44
 
# File 'lib/minting/mint/mint.rb', line 37

def self.zero(currency)
  checked = Mint.currency(currency)
  raise ArgumentError, "Invalid Currency: [#{currency}]" unless checked

  @zeros ||= CurrencyRegistry.currencies.values.to_h { |currency| [currency, Mint::Money.send(:new, 0, currency)] }
  @zeros[currency] ||= Money.send(:new, 0, currency)
  @zeros[currency]
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/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