amounts 0.0.7 → 0.1.0

data/lib/amount/concerns/parsable.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+class Amount
+  # Concern: the class-level entry points that turn strings into amounts.
+  #
+  # Two inputs, two parsers:
+  #
+  # - {Amount.parse} reads the compact machine format (`USDC|1.50`) that
+  #   `to_s` writes. See {Parser}.
+  # - {Amount.parse_ui} reads what a person typed, in a locale's number
+  #   format. See {UiParser}.
+  module Parsable
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # Class-level methods extended onto any class that does `include Parsable`.
+    module ClassMethods
+      # Parses the compact client-facing string representation.
+      #
+      # Accepts either the default form `SYMBOL|amount` or the explicit
+      # versioned form `v1:SYMBOL|amount`.
+      #
+      # @param str [String]
+      # @return [Amount]
+      # @raise [InvalidInput]
+      # @example Parsing the default compact format
+      #   Amount.parse("USDC|1.50")
+      #
+      # @example Parsing the explicit versioned compact format
+      #   Amount.parse("v1:USDC|1.50")
+      def parse(str)
+        Parser.new(str).parse
+      end
+
+      # Parses text typed by a person, in a locale's number format.
+      #
+      # The effective locale is `locale:`, then `I18n.locale` when
+      # `Amount.localize` is true, else plain parsing (`.` decimal, no
+      # delimiters). Accepts surrounding whitespace, a leading `-` or `+`,
+      # delimiters in groups of three, and the type's label (any plural form)
+      # at either end. Never rounds.
+      #
+      # @param input [String]
+      # @param symbol [Symbol, String]
+      # @param locale [Symbol, String, nil]
+      # @return [Amount] an instance of the type's registered class
+      # @raise [InvalidInput] for too many decimals, misplaced delimiters, a
+      #   repeated separator, another type's label, or empty input
+      # @raise [Registry::UnknownType] for an unregistered symbol
+      # @example
+      #   Amount.parse_ui("1.500,50", :USD, locale: :de) # => USD|1500.50
+      def parse_ui(input, symbol, locale: nil)
+        UiParser.new(input, symbol, locale).parse
+      end
+    end
+  end
+end

data/lib/amount/concerns/registrable.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+class Amount
+  # Concern: the shared type registry and the class-level shortcuts for
+  # registering types and default rates.
+  #
+  # The registry lives on `Amount` itself, never on a subclass, so
+  # `GoldAmount.registry` and `Amount.registry` are the same object. Swapping
+  # it removes the outgoing registry's generated constructors (`of_usdc`) and
+  # installs the incoming one's.
+  module Registrable
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # Class-level methods extended onto any class that does
+    # `include Registrable`.
+    module ClassMethods
+      # @return [Amount::Registry]
+      # @example Accessing the shared registry
+      #   Amount.registry.locked?
+      #   # => false
+      def registry
+        Amount.instance_variable_get(:@registry) ||
+          replace_registry(Registry.new)
+      end
+
+      # @param symbol [Symbol, String]
+      # @param opts [Hash]
+      # @return [void]
+      # @example Registering a type
+      #   Amount.register :USDC,
+      #     decimals: 6,
+      #     display_symbol: "$",
+      #     display_position: :prefix,
+      #     ui_decimals: 2
+      def register(symbol, **opts)
+        registry.register(symbol, **opts)
+      end
+
+      # @param from [Symbol, String]
+      # @param to [Symbol, String]
+      # @param rate [String, Numeric, BigDecimal]
+      # @return [void]
+      # @example Registering a directional default rate
+      #   Amount.register_default_rate :USD, :USDC, "1"
+      def register_default_rate(from, to, rate)
+        registry.register_default_rate(from, to, rate)
+      end
+
+      # Temporarily swaps the global registry. Intended for tests.
+      #
+      # @param registry [Amount::Registry]
+      # @yield
+      # @return [Object]
+      # @example Using a temporary registry
+      #   test_registry = Amount::Registry.new
+      #   Amount.with_registry(test_registry) do
+      #     Amount.register :TEST, decimals: 2
+      #   end
+      def with_registry(registry)
+        original = Amount.instance_variable_get(:@registry)
+        replace_registry(registry)
+        yield
+      ensure
+        replace_registry(original)
+      end
+
+      private
+
+      def replace_registry(registry)
+        current = Amount.instance_variable_get(:@registry)
+        current&.remove_generated_methods!
+        Amount.instance_variable_set(:@registry, registry)
+        registry&.activate_generated_methods!
+        registry
+      end
+    end
+  end
+end

data/lib/amount/{serialization.rb → concerns/serializable.rb}

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
 class Amount
-  # Versioned hash serialization. `include Serialization` does both halves:
+  # Versioned hash serialization. `include Serializable` does both halves:
   # the instance side (`#to_h`) is mixed in directly, and the class-level
   # entry point (`Amount.load`) is auto-extended onto the including class
   # via the `included` hook below. The compact-string format is the
   # responsibility of {Amount::Parser}.
-  module Serialization
+  module Serializable
     VERSION = 1
 
     def self.included(base)
@@ -14,7 +14,7 @@ class Amount
     end
 
     # Class-level methods automatically extended onto any class that does
-    # `include Serialization`.
+    # `include Serializable`.
     module ClassMethods
       # @param payload [Hash]
       # @return [Amount]
@@ -41,7 +41,7 @@ class Amount
 
     # @return [Hash]
     # @example
-    #   Amount.usdc("1.50").to_h
+    #   Amount.of_usdc("1.50").to_h
     #   # => { v: 1, atomic: "1500000", symbol: "USDC" }
     def to_h
       {

data/lib/amount/display.rb

@@ -5,6 +5,19 @@ require "bigdecimal"
 class Amount
   # Formats amounts for UI output without changing their type.
   class Display
+    # Rounds to `decimals` places (negative rounds to tens, hundreds, ...),
+    # down with `:floor` and up with `:ceil`, like `ui`'s `direction:`.
+    # @param value [BigDecimal]
+    # @param decimals [Integer]
+    # @param direction [Symbol]
+    # @return [BigDecimal]
+    def self.round(value, decimals, direction)
+      factor = BigDecimal(10)**decimals
+      scaled = value * factor
+      truncated = direction == :ceil ? scaled.ceil : scaled.floor
+      truncated / factor
+    end
+
     # @param amount [Amount]
     def initialize(amount)
       @amount = amount
@@ -25,19 +38,61 @@ class Amount
     #   number. When `nil` (the default), falls back to the display unit's
     #   setting, then the registry entry's setting. An explicit `true` or
     #   `false` overrides both.
+    # @param locale [Symbol, String, nil] format the number with this locale's
+    #   `number.format` delimiter and separator (requires I18n). When `nil`,
+    #   uses `I18n.locale` if `Amount.localize` is true, else plain output.
+    # @param compact [Boolean, Hash] show numbers of one thousand or more in
+    #   compact notation (`1.5M`, or `1,5 Mio.` with a locale's
+    #   `number.human.decimal_units` keys). `true` keeps 3 significant digits;
+    #   `{ precision: 2 }` changes that. Rounds in `direction` and trims
+    #   trailing zeros. The label and template wrap the compacted number; plural
+    #   labels agree with the full value. See {Compact}.
     # @return [String]
     # @example
-    #   Amount.usdc("1.50").ui                       # => "$1.50"
-    #   Amount.usdc("1.50").ui(decorated: false)     # => "1.50"
-    #   Amount.gold("1").ui(unit: :gram)             # => "31.10 g"
-    #   Amount.gold("1").ui(unit: :gram, decorated: false)  # => "31.10"
-    #   Amount.sol("2.5").ui(trim_zeros: true)       # => "2.5 SOL"
-    def ui(unit: nil, direction: :floor, decorated: true, trim_zeros: nil)
-      if unit
-        render_display_unit(unit, direction, decorated:, trim_zeros:)
-      else
-        render_default(direction, decorated:, trim_zeros:)
-      end
+    #   Amount.of_usdc("1.50").ui                       # => "$1.50"
+    #   Amount.of_usdc("1.50").ui(decorated: false)     # => "1.50"
+    #   Amount.of_gold("1").ui(unit: :gram)             # => "31.10 g"
+    #   Amount.of_gold("1").ui(unit: :gram, decorated: false)  # => "31.10"
+    #   Amount.of_sol("2.5").ui(trim_zeros: true)       # => "2.5 SOL"
+    #   # EUR registered with display_format: "%u%n"; de.yml has
+    #   # amounts.formats.eur: "%n\u00A0%u"
+    #   Amount.of_eur("12.5").ui(locale: :en)           # => "€12.50"
+    #   Amount.of_eur("12.5").ui(locale: :de)           # => "12,50\u00A0€"
+    #   Amount.of_usd("1500000").ui(compact: true)      # => "$1.5M"
+    #   Amount.of_tokens(50_000_000).ui(compact: true, decorated: false)  # => "50M"
+    def ui(unit: nil, direction: :floor, decorated: true, trim_zeros: nil, locale: nil, compact: false)
+      locale = Locale.effective(locale)
+      precision = Compact.precision(compact)
+      spec = @entry.display_unit(unit) if unit
+      value = spec ? @amount.decimal * Amount.coerce_decimal(spec[:scale]) : @amount.decimal
+      decimals = spec&.dig(:ui_decimals) || @entry.ui_decimals
+      rounded = round(value, decimals, direction)
+      formatted =
+        if precision && Compact.applies?(value)
+          Compact.format(value, precision:, direction:, locale:)
+        else
+          format_number(rounded, decimals, resolve_trim(trim_zeros, spec), locale)
+        end
+      return formatted unless decorated
+
+      decorate(formatted, rounded, unit, spec, locale)
+    end
+
+    # The unit label alone, for column headers and chips that render it
+    # separately. Follows the same rules as `ui`: translated through I18n only
+    # when a locale is given or `Amount.localize` is true, else `display_symbol`
+    # (or the display unit's `:symbol`).
+    # @param unit [Symbol, nil] display unit
+    # @param locale [Symbol, String, nil]
+    # @param count [Numeric, String, nil] the number the label agrees with, for
+    #   plural labels. Without it the `:other` form is used.
+    # @return [String]
+    # @example
+    #   Amount.of_searches(3).unit_label(locale: :de)  # => "Suchen"
+    #   Amount.of_searches(1).unit_label(count: 1)     # => "search" (hash display_symbol)
+    def unit_label(unit: nil, locale: nil, count: nil)
+      count = Amount.coerce_decimal(count) unless count.nil?
+      label(unit, Locale.effective(locale), nil, count)
     end
 
     # @return [String]
@@ -49,56 +104,42 @@ class Amount
     # @param unit [Symbol]
     # @return [BigDecimal]
     def in_unit(unit)
-      unit_spec = fetch_display_unit(unit)
+      unit_spec = @entry.display_unit(unit)
       @amount.decimal * Amount.coerce_decimal(unit_spec[:scale])
     end
 
     private
 
-    def render_default(direction, decorated:, trim_zeros:)
-      rounded = round(@amount.decimal, @entry.ui_decimals, direction)
-      formatted = format_number(rounded, @entry.ui_decimals, resolve_trim(trim_zeros))
-      return formatted unless decorated
-
-      apply_symbol(formatted, @entry.display_symbol, @entry.display_position)
-    end
-
-    def render_display_unit(unit, direction, decorated:, trim_zeros:)
-      spec = fetch_display_unit(unit)
-      scaled = @amount.decimal * Amount.coerce_decimal(spec[:scale])
-      decimals = spec[:ui_decimals] || @entry.ui_decimals
-      rounded = round(scaled, decimals, direction)
-      formatted = format_number(rounded, decimals, resolve_trim(trim_zeros, spec))
-      return formatted unless decorated
+    # Places the number and its label with the template from
+    # {Formattable#display_format}. The label agrees with `count`, the number
+    # as displayed. Without a label there is nothing to place, so the number is
+    # returned alone.
+    def decorate(number, count, unit, spec, locale)
+      label = label(unit, locale, spec, count)
+      return number if label.nil? || label.empty?
 
-      apply_symbol(
-        formatted,
-        spec[:symbol] || @entry.display_symbol,
-        spec[:position] || @entry.display_position
-      )
+      Formattable.fill(@amount.display_format(unit:, locale:), number:, label:)
     end
 
-    def fetch_display_unit(unit)
-      units = @entry.display_units
-      unless units
-        raise Registry::InvalidDisplayUnit, "#{@entry.symbol} has no display_units configured"
-      end
+    def label(unit, locale, spec = nil, count = nil)
+      spec ||= @entry.display_unit(unit) if unit
+      if spec
+        return Locale.plain(spec[:symbol] || @entry.display_symbol, count) unless locale
 
-      units.fetch(unit.to_sym) do
-        raise Registry::InvalidDisplayUnit, "unknown display unit #{unit} for #{@entry.symbol}"
+        Locale.unit_label(@entry, unit.to_sym, spec, locale, count)
+      else
+        locale ? Locale.type_label(@entry, locale, count) : Locale.plain(@entry.display_symbol, count)
       end
     end
 
     def round(value, decimals, direction)
-      factor = BigDecimal(10)**decimals
-      scaled = value * factor
-      truncated = direction == :ceil ? scaled.ceil : scaled.floor
-      truncated / factor
+      self.class.round(value, decimals, direction)
     end
 
-    def format_number(value, decimals, trim)
+    def format_number(value, decimals, trim, locale = nil)
       str = format("%.#{decimals}f", value)
-      trim ? str.sub(/(\.\d*?)0+\z/, '\1').chomp('.') : str
+      str = str.sub(/(\.\d*?)0+\z/, '\1').chomp('.') if trim
+      locale ? Locale.apply(str, locale) : str
     end
 
     def resolve_trim(call_site, spec = nil)
@@ -107,11 +148,5 @@ class Amount
 
       @entry.trim_zeros
     end
-
-    def apply_symbol(str, symbol, position)
-      return str if symbol.nil? || symbol.empty?
-
-      position == :prefix ? "#{symbol}#{str}" : "#{str} #{symbol}"
-    end
   end
 end

data/lib/amount/locale.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+class Amount
+  # Internal: decides the effective locale and reads number formatting from
+  # I18n. I18n is used only when it is already loaded; it is never required.
+  module Locale
+    DEFAULT_DELIMITER = ","
+    DEFAULT_SEPARATOR = "."
+    MISSING_I18N = "the i18n gem is required for locale-aware output; add it to your Gemfile and require it"
+
+    module_function
+
+    # @return [Boolean]
+    def i18n_loaded?
+      defined?(::I18n) ? true : false
+    end
+
+    # @raise [ArgumentError] when I18n isn't loaded
+    def require_i18n!
+      raise ArgumentError, MISSING_I18N unless i18n_loaded?
+    end
+
+    # 1. an explicit locale, 2. I18n.locale when Amount.localize, 3. nil.
+    # @param explicit [Symbol, String, nil]
+    # @return [Symbol, String, nil]
+    def effective(explicit = nil)
+      unless explicit.nil?
+        require_i18n!
+        return explicit
+      end
+      return nil unless Amount.localize?
+
+      require_i18n!
+      ::I18n.locale
+    end
+
+    # @return [Hash{Symbol=>String}] `:delimiter` and `:separator`
+    def number_format(locale)
+      format = ::I18n.t("number.format", locale:, default: {})
+      format = {} unless format.is_a?(Hash)
+      {
+        delimiter: format[:delimiter] || DEFAULT_DELIMITER,
+        separator: format[:separator] || DEFAULT_SEPARATOR
+      }
+    end
+
+    # Picks a form from a plural hash without I18n: `:one` when the number
+    # equals 1, else `:other`. Strings pass through.
+    # @param label [String, Hash, nil]
+    # @param count [BigDecimal, nil]
+    def plain(label, count)
+      return label unless label.is_a?(Hash)
+
+      count == 1 && label.key?(:one) ? label[:one] : label[:other]
+    end
+
+    # Label of a registered type: its `label_key`, then
+    # `amounts.units.<symbol downcased>`, then `display_symbol`.
+    # @return [String, nil]
+    def type_label(entry, locale, count = nil)
+      key = entry.label_key || "amounts.units.#{entry.symbol.to_s.downcase}"
+      translate(key, locale, entry.display_symbol, count)
+    end
+
+    # Label of a display unit: the spec's `label_key`, then
+    # `amounts.display_units.<symbol downcased>.<unit>`, then the spec's
+    # `:symbol`, then the type's label.
+    # @return [String, nil]
+    def unit_label(entry, unit, spec, locale, count = nil)
+      key = spec[:label_key] || "amounts.display_units.#{entry.symbol.to_s.downcase}.#{unit}"
+      translate(key, locale, spec[:symbol] || type_label(entry, locale, count), count)
+    end
+
+    # Looks a key up, falling back to `default` so a miss never yields
+    # "translation missing". With a count, I18n pluralizes a hash translation
+    # or default using the locale's rules; without one, or when the form is
+    # missing, the `:other` form is used.
+    def translate(key, locale, default, count = nil)
+      opts = count.nil? ? {} : { count: whole(count) }
+      found = ::I18n.t(key.to_s, locale:, default:, **opts)
+      found.is_a?(Hash) ? found[:other] : found
+    rescue ::I18n::InvalidPluralizationData => e
+      e.entry[:other]
+    end
+
+    # 1.0 -> 1, so custom pluralization rules can match integers.
+    def whole(count)
+      count.frac.zero? ? count.to_i : count
+    end
+
+    # Rewrites a plain "-1234.50" style number with the locale's characters.
+    # @param str [String] output of `format("%.Nf", value)`
+    # @return [String]
+    def apply(str, locale)
+      fmt = number_format(locale)
+      sign = str.start_with?("-") ? "-" : ""
+      int, frac = str.delete_prefix("-").split(".", 2)
+      int = int.reverse.scan(/\d{1,3}/).join(fmt[:delimiter].reverse).reverse
+      "#{sign}#{int}#{frac ? "#{fmt[:separator]}#{frac}" : ''}"
+    end
+  end
+end

data/lib/amount/registry/generated_constructors.rb

@@ -2,9 +2,14 @@
 
 class Amount
   class Registry
-    # Manages registry-driven constructor methods such as `Amount.usdc(...)`.
+    # Manages registry-driven constructor methods such as `Amount.of_usdc(...)`.
+    #
+    # Generated names are prefixed with `of_` so that short ISO codes like
+    # `:TRY` (which collides with `Object#try` once ActiveSupport is loaded)
+    # do not clash with existing methods on `Amount`.
     class GeneratedConstructors
-      METHOD_NAME_PATTERN = /\A[a-z_][a-z0-9_]*\z/
+      SYMBOL_PATTERN = /\A[a-z_][a-z0-9_]*\z/
+      METHOD_NAME_PREFIX = "of_"
 
       def initialize(target: Amount)
         @target = target
@@ -40,10 +45,10 @@ class Amount
       private
 
       def method_name_for(symbol)
-        method_name = symbol.to_s.downcase
-        return unless method_name.match?(METHOD_NAME_PATTERN)
+        downcased = symbol.to_s.downcase
+        return unless downcased.match?(SYMBOL_PATTERN)
 
-        method_name
+        "#{METHOD_NAME_PREFIX}#{downcased}"
       end
 
       def raise_collision!(method_name)

data/lib/amount/registry.rb

@@ -2,7 +2,6 @@
 
 require "bigdecimal"
 require "thread"
-require_relative "registry/generated_constructors"
 
 class Amount
   # Stores registered amount types and default directional conversion rates.
@@ -25,19 +24,33 @@ class Amount
     class RegistryLocked < StandardError; end
     class AlreadyRegistered < StandardError; end
     class InvalidDisplayUnit < StandardError; end
+    class InvalidDisplaySymbol < StandardError; end
 
     Entry = Struct.new(
       :symbol,
       :decimals,
       :display_symbol,
+      :label_key,
       :display_position,
+      :display_format,
       :ui_decimals,
       :display_units,
       :default_display,
       :amount_class,
       :trim_zeros,
       keyword_init: true
-    )
+    ) do
+      # @param unit [Symbol, String]
+      # @return [Hash] the display unit's spec
+      # @raise [InvalidDisplayUnit] when the type has no such display unit
+      def display_unit(unit)
+        raise InvalidDisplayUnit, "#{symbol} has no display_units configured" unless display_units
+
+        display_units.fetch(unit.to_sym) do
+          raise InvalidDisplayUnit, "unknown display unit #{unit} for #{symbol}"
+        end
+      end
+    end
 
     def initialize
       @entries       = {}
@@ -51,13 +64,25 @@ class Amount
     # Registers a new fungible type.
     #
     # When the symbol is a valid Ruby method name after downcasing, an
-    # ergonomic constructor is also generated on `Amount`, such as
-    # `Amount.usdc("1.50")`.
+    # ergonomic constructor is also generated on `Amount` with an `of_`
+    # prefix, such as `Amount.of_usdc("1.50")`. The prefix avoids collisions
+    # with existing methods like `Object#try` (added by ActiveSupport).
     #
     # @param symbol [Symbol, String] registered type identifier
     # @param decimals [Integer] number of storage decimals
-    # @param display_symbol [String] symbol used by UI helpers
-    # @param display_position [Symbol] either `:prefix` or `:suffix`
+    # @param display_symbol [String, Hash] symbol used by UI helpers. A hash
+    #   (`{ one: "search", other: "searches" }`) gives plural forms and must
+    #   have `:other`
+    # @param label_key [String, Symbol, nil] I18n key for the unit label, used
+    #   when localizing. Defaults to `amounts.units.<symbol downcased>`;
+    #   a missing translation falls back to `display_symbol`
+    # @param display_position [Symbol, nil] `:prefix` (`"$1.50"`) or `:suffix`
+    #   (`"1.50 SOL"`, the default). Shorthand for the templates `"%u%n"` and
+    #   `"%n %u"`; can't be combined with `display_format`
+    # @param display_format [String, nil] template for decorated `ui` output,
+    #   where `%n` is the formatted number (sign included) and `%u` the label,
+    #   e.g. `"%n\u00A0%u"`. Used exactly as given. When localizing,
+    #   `amounts.formats.<symbol downcased>` overrides it
     # @param ui_decimals [Integer] decimals displayed by default UI formatting
     # @param display_units [Hash, nil] optional display-only scaling definitions
     # @param default_display [Symbol, nil] optional default display unit key
@@ -67,14 +92,16 @@ class Amount
     # @raise [AlreadyRegistered] if the symbol is already registered or the
     #   generated constructor would collide with an existing method
     # @raise [RegistryLocked] if the registry has been locked
+    # @raise [ArgumentError] if both `display_format` and `display_position`
+    #   are given, or `display_format` is not a String containing `%n`
     # @example
     #   Amount.register :USDC,
     #     decimals: 6,
     #     display_symbol: "$",
     #     display_position: :prefix,
     #     ui_decimals: 2
-    def register(symbol, decimals:, display_symbol: symbol.to_s, display_position: :suffix,
-                 ui_decimals: decimals, display_units: nil, default_display: nil,
+    def register(symbol, decimals:, display_symbol: symbol.to_s, label_key: nil, display_position: nil,
+                 display_format: nil, ui_decimals: decimals, display_units: nil, default_display: nil,
                  trim_zeros: false, class: nil)
       raise ArgumentError, "symbol must not be blank" if symbol.nil? || symbol.to_s.empty?
 
@@ -84,13 +111,17 @@ class Amount
         ensure_unlocked!
         raise AlreadyRegistered, "#{symbol} already registered" if @entries.key?(symbol)
 
+        validate_display_symbol!(:display_symbol, display_symbol, InvalidDisplaySymbol)
+        validate_display_format!(display_format, display_position) if display_format
         validate_display_units!(display_units, default_display) if display_units
 
         entry = Entry.new(
           symbol:,
           decimals:,
           display_symbol:,
-          display_position:,
+          label_key: label_key&.to_s,
+          display_position: display_format ? nil : (display_position || :suffix),
+          display_format: display_format || Formattable.template_for(display_position),
           ui_decimals:,
           display_units:,
           default_display:,
@@ -229,6 +260,13 @@ class Amount
       raise RegistryLocked, "registry is locked" if @locked
     end
 
+    def validate_display_format!(format, position)
+      raise ArgumentError, "pass display_format or display_position, not both" if position
+      return if Formattable.valid_template?(format)
+
+      raise ArgumentError, "display_format must be a String containing %n"
+    end
+
     def validate_display_units!(units, default)
       unless units.is_a?(Hash) && !units.empty?
         raise InvalidDisplayUnit, "display_units must be a non-empty hash"
@@ -242,7 +280,32 @@ class Amount
         unless spec.is_a?(Hash) && spec.key?(:scale)
           raise InvalidDisplayUnit, "display_unit #{key} must have :scale"
         end
+
+        validate_unit_format!(key, spec) if spec.key?(:format)
+        validate_display_symbol!("display_unit #{key} :symbol", spec[:symbol], InvalidDisplayUnit) if spec[:symbol]
+      end
+    end
+
+    def validate_unit_format!(key, spec)
+      if spec.key?(:position)
+        raise InvalidDisplayUnit, "display_unit #{key} takes :format or :position, not both"
       end
+      return if Formattable.valid_template?(spec[:format])
+
+      raise InvalidDisplayUnit, "display_unit #{key} :format must be a String containing %n"
+    end
+
+    def validate_display_symbol!(name, value, error)
+      return unless value.is_a?(Hash)
+
+      unless value.key?(:other)
+        raise error, "#{name} hash must have an :other key (got #{value.keys.inspect})"
+      end
+
+      bad = value.reject { |k, v| k.is_a?(Symbol) && v.is_a?(String) }
+      return if bad.empty?
+
+      raise error, "#{name} hash must map Symbol plural keys to String labels (got #{bad.inspect})"
     end
   end
 end

data/lib/amount/rspec.rb

@@ -12,10 +12,10 @@ require_relative "rspec/matchers"
 # @example
 #   require "amount/rspec"
 #
-#   expect(Amount.usdc("1.50")).to eq_amount("USDC|1.50")
-#   expect(Amount.usdc("1.50")).to be_amount_of(:USDC)
-#   expect(Amount.usdc("1.50")).to be_positive_amount
-#   expect(Amount.usdc("1.55")).to be_approximately_amount(:USDC, "1.50", within: "0.10")
+#   expect(Amount.of_usdc("1.50")).to eq_amount("USDC|1.50")
+#   expect(Amount.of_usdc("1.50")).to be_amount_of(:USDC)
+#   expect(Amount.of_usdc("1.50")).to be_positive_amount
+#   expect(Amount.of_usdc("1.55")).to be_approximately_amount(:USDC, "1.50", within: "0.10")
 Amount::RSpec::Matchers.define_amount_equality_matcher(:eq_amount) do |*expected_arguments|
   Amount::RSpec::Support.coerce_amount_arguments(expected_arguments)
 end