Module: WhittakerTech::Midas::Coin::Presenter

Included in:: WhittakerTech::Midas::Coin

Defined in:: app/models/whittaker_tech/midas/coin/presenter.rb

Overview

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

Constant Summary collapse

TOKEN_MAP = Registry of recognised tokens and their handler method names. Returns: (Hash{String => Symbol}) Since: 0.1.0

{
  '%' => :token_percent,
  't' => :token_total,
  'm' => :token_minor,
  'M' => :token_major,
  'c' => :token_currency_code,
  's' => :token_currency_symbol,
  'n' => :token_number_only,
  'u' => :token_units,
  'p' => :token_per_exact,
  '~' => :token_approx
}.freeze

Class Method Summary collapse

.build_context(coin, **opts) ⇒ Context
Builds a Context struct from a Coin and caller-supplied options.
.dispatch(token, ctx) ⇒ String
Dispatches a single token character to its handler.
.format(coin, pattern) ⇒ String
Formats a Coin using a pattern string.
.scan(pattern, ctx) ⇒ String
Scans a pattern string, expanding %x tokens into rendered values.
.token_approx(approx:) ⇒ Object private
.token_currency_code(coin:) ⇒ Object private
.token_currency_symbol(coin:, currency_dir:) ⇒ Object private
.token_major(coin:) ⇒ Object private
.token_minor(coin:) ⇒ Object private
.token_number_only(coin:) ⇒ Object private
.token_per_exact(per_exact:) ⇒ Object private
.token_percent ⇒ Object private
.token_total(coin:, currency_dir:) ⇒ Object private
.token_units(units:) ⇒ Object private

Instance Method Summary collapse

#present(pattern) ⇒ String
Renders this Coin using a format pattern.

Class Method Details

.build_context(coin, **opts) ⇒ `Context`

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

Parameters:

coin (Coin)
opts (Hash)

Options Hash (**opts):

:currency_dir (Symbol) — default: :ltr or :rtl —
override direction
:approx (Boolean) —
whether to render ~ as ≈
:units (String, nil) —
value for %u token
:per_exact (String, nil) —
value for %p token

Returns:

(Context)

Since:

0.1.0

# File 'app/models/whittaker_tech/midas/coin/presenter.rb', line 119

def build_context(coin, **opts)
  Context.new(coin:,
              currency_dir: opts[:currency_dir] || coin.bidi_currency_dir(coin.currency_code),
              approx: opts[:approx] || false,
              units: opts[:units] || nil,
              per_exact: opts[:per_exact] || nil)
end

.dispatch(token, ctx) ⇒ `String`

Dispatches a single token character to its handler.

Parameters:

token (String) —
single character following %
ctx (Context)

Returns:

(String)

Raises:

(ArgumentError) —
if the token is not in TOKEN_MAP

Since:

0.1.0

# File 'app/models/whittaker_tech/midas/coin/presenter.rb', line 159

def dispatch(token, ctx)
  handler = TOKEN_MAP[token]
  raise ArgumentError, "Unknown presenter token: %#{token}" unless handler

  send(handler, **ctx.to_h)
end

.format(coin, pattern) ⇒ `String`

Formats a Coin using a pattern string.

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

Parameters:

coin (Coin) —
the value to format
pattern (String) —
the format pattern
opts (Hash) —
optional context overrides

Returns:

(String)

Raises:

(ArgumentError) —
if pattern is nil, contains an unknown token, or has an unterminated % escape

Since:

0.1.0

# File 'app/models/whittaker_tech/midas/coin/presenter.rb', line 103

def format(coin, pattern, **)
  raise ArgumentError, 'pattern required' if pattern.nil?

  ctx = build_context(coin, **)
  scan(pattern, ctx)
end

.scan(pattern, ctx) ⇒ `String`

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

Parameters:

pattern (String)
ctx (Context)

Returns:

(String)

Raises:

(ArgumentError) —
on unknown or unterminated tokens

Since:

0.1.0

# File 'app/models/whittaker_tech/midas/coin/presenter.rb', line 133

def scan(pattern, ctx)
  is_token = false
  out = +'' # output buffer

  pattern.to_s.each_char do |char|
    if is_token
      out << dispatch(char, ctx)
      is_token = false
    elsif char == '%'
      is_token = true
    else
      out << char
    end
  end

  raise ArgumentError, "Unterminated token in pattern: #{pattern}" if is_token

  out
end