amounts 0.0.8 → 0.1.0

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,6 +38,15 @@ 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.of_usdc("1.50").ui                       # => "$1.50"
@@ -32,12 +54,45 @@ class Amount
     #   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"
-    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
+    #   # 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.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       = {}
@@ -57,8 +70,19 @@ class Amount
     #
     # @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
@@ -68,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?
 
@@ -85,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:,
@@ -230,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"
@@ -243,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/ui_parser.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+class Amount
+  # Internal: parses the text a person types into a form field, optionally in
+  # a locale's number format. Exact: never rounds, never goes through Float.
+  class UiParser
+    # @param input [#to_s]
+    # @param symbol [Symbol, String]
+    # @param locale [Symbol, String, nil]
+    def initialize(input, symbol, locale)
+      @input = input
+      @entry = Amount.registry.lookup(symbol)
+      @locale = Locale.effective(locale)
+      format = @locale ? Locale.number_format(@locale) : { delimiter: "", separator: "." }
+      @delimiter = format[:delimiter].to_s
+      @separator = format[:separator].to_s
+    end
+
+    # @return [Amount]
+    def parse
+      text = strip(@input.to_s)
+      fail_with("is empty") if text.empty?
+      original = text
+
+      sign, text = take_sign(text)
+      @signed = text != original
+      unlabeled = strip_label(text)
+      # "$-1.50": a sign may follow a prefix label, but not as a second sign
+      sign, unlabeled = take_sign(unlabeled) if sign.empty? && unlabeled != text && !@signed
+      text = unlabeled
+      value = atomic(text)
+      Amount.new(sign.empty? ? value : -value, @entry.symbol)
+    end
+
+    private
+
+    def fail_with(reason)
+      raise InvalidInput, "cannot parse #{@input.inspect} as #{@entry.symbol}: #{reason}"
+    end
+
+    def strip(str)
+      str.gsub(/\A[[:space:]]+|[[:space:]]+\z/, "")
+    end
+
+    # @return [Array(String, String)] "-" or "" (a "+" is dropped), and the rest
+    def take_sign(text)
+      match = text.match(/\A([+-])[[:space:]]*(.*)\z/m)
+      return ["", text] unless match
+
+      [match[1] == "-" ? "-" : "", match[2]]
+    end
+
+    # Removes one label (the longest match) from either end.
+    def strip_label(text)
+      labels.each do |label|
+        if text.start_with?(label)
+          return strip(text.delete_prefix(label))
+        elsif text.end_with?(label)
+          return strip(text.delete_suffix(label))
+        end
+      end
+      text
+    end
+
+    # Every form of the type's label: `display_symbol` (and its plural
+    # forms), plus the locale's translation when localizing.
+    def labels
+      found = forms(@entry.display_symbol)
+      found += forms(translation) if @locale
+      found.map(&:to_s).reject(&:empty?).uniq.sort_by { |label| -label.length }
+    end
+
+    def translation
+      key = @entry.label_key || "amounts.units.#{@entry.symbol.to_s.downcase}"
+      ::I18n.t(key.to_s, locale: @locale, default: nil)
+    end
+
+    def forms(label)
+      case label
+      when Hash then label.values.grep(String)
+      when String then [label]
+      else []
+      end
+    end
+
+    # @return [Integer] atomic units, unsigned
+    def atomic(text)
+      whole, fraction, extra = text.split(@separator, -1)
+      fail_with("a decimal separator is used twice") if extra
+      fail_with("is not a number") unless whole&.match?(whole_pattern)
+      fraction ||= ""
+      fail_with("is not a number") if text.include?(@separator) && fraction.empty?
+      fail_with("is not a number") unless fraction.match?(/\A\d*\z/)
+      if fraction.length > @entry.decimals
+        fail_with("has more than #{@entry.decimals} decimal places")
+      end
+
+      digits = whole.gsub(/\D/, "") + fraction.ljust(@entry.decimals, "0")
+      digits.to_i
+    end
+
+    def whole_pattern
+      return /\A\d+\z/ if @delimiter.empty?
+
+      glue = @delimiter.match?(/\A[[:space:]]+\z/) ? "[[:space:]]" : Regexp.escape(@delimiter)
+      /\A(?:\d+|\d{1,3}(?:#{glue}\d{3})+)\z/
+    end
+  end
+end

data/lib/amount/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Amount
-  VERSION = "0.0.8"
+  VERSION = "0.1.0"
 end