Skip to content

Module WhittakerTech::Midas::Coin::Presenter

Presenter provides a strftime-like token grammar for rendering Coin values.

Design principles

  • Declarative — tokens map directly to named handler methods.
  • Pure — no mutation, rounding, or currency conversion.
  • Direction-safe — all text is wrapped with Unicode bidirectional isolation markers via Coin::Bidi to prevent display corruption in mixed LTR/RTL contexts.

Token reference

Patterns are strings containing %x tokens (similar to strftime).

Tokens:

  • %t: Formatted total (symbol + amount), e.g. $29.99
  • %m: Minor units (raw integer), e.g. 2999
  • %M: Major units (decimal string), e.g. 29.99
  • %c: Currency code, e.g. USD
  • %s: Currency symbol, e.g. $
  • %n: Number only (no symbol), e.g. 29.99
  • %u: Custom units label (see opts), e.g. per kg
  • %p: Custom per-exact label (see opts), e.g. 0.2997
  • %~: Approximate marker (≈ or empty)
  • %%: Literal percent sign

Usage

coin = Coin.value(2999, 'USD')
coin.present('%s%M %c')           # => "$29.99 USD"
coin.present('%~%t', approx: true) # => "≈$29.99"

Options

Pass keyword options to present / format to populate optional tokens:

  • approx: [Boolean] — if true, ~ expands to ≈; otherwise empty string.
  • units: [String] — value for %u token.
  • per_exact: [String] — value for %p token.

  • currency_dir: [Symbol] — override the currency display direction (:ltr or :rtl); defaults to the value from WhittakerTech::Midas.currency_direction_for.

  • @since 0.1.0

Constants

TOKEN_MAP

Registry of recognised tokens and their handler method names.

  • @return [Hash{String => Symbol}]
  • @since 0.1.0

Public Class Methods

build_context(coin, **opts)

Builds a Context struct from a Coin and caller-supplied options.

  • @option opts
  • @option opts
  • @option opts
  • @option opts
  • @param coin [Coin]
  • @param opts [Hash]
  • @return [Context]
  • @since 0.1.0

dispatch(token, ctx)

Dispatches a single token character to its handler.

  • @param token [String] single character following %
  • @param ctx [Context]
  • @raise [ArgumentError] if the token is not in TOKEN_MAP
  • @return [String]
  • @since 0.1.0

format(coin, pattern)

Formats a Coin using a pattern string.

This is the class-level entry point; instance-level access is via Coin#present.

  • @param coin [Coin] the value to format
  • @param pattern [String] the format pattern
  • @param opts [Hash] optional context overrides

  • @raise [ArgumentError] if pattern is nil, contains an unknown token, or has an unterminated % escape

  • @return [String]

  • @since 0.1.0

scan(pattern, ctx)

Scans a pattern string, expanding %x tokens into rendered values.

  • @param pattern [String]
  • @param ctx [Context]
  • @raise [ArgumentError] on unknown or unterminated tokens
  • @return [String]
  • @since 0.1.0

token_approx(approx:)

  • @api private
  • @since 0.1.0

token_currency_code(coin:)

  • @api private
  • @since 0.1.0

token_currency_symbol(coin:, currency_dir:)

  • @api private
  • @since 0.1.0

token_major(coin:)

  • @api private
  • @since 0.1.0

token_minor(coin:)

  • @api private
  • @since 0.1.0

token_number_only(coin:)

  • @api private
  • @since 0.1.0

token_per_exact(per_exact:)

  • @api private
  • @since 0.1.0

token_percent()

  • @api private
  • @since 0.1.0

token_total(coin:, currency_dir:)

  • @api private
  • @since 0.1.0

token_units(units:)

  • @api private
  • @since 0.1.0

Public Instance Methods

present(pattern)

Renders this Coin using a format pattern.

  • @param pattern [String] the format pattern containing %x tokens
  • @param opts [Hash] optional rendering context overrides (see module docs)
  • @raise [ArgumentError] if the pattern contains an unknown or unterminated token
  • @return [String]
  • @since 0.1.0

@example 

coin.present('%s%M')          # => "$29.99"
coin.present('%t (%c)')       # => "$29.99 (USD)"
coin.present('~%t', approx: true) # => "≈$29.99"