amounts 0.0.8 → 0.1.0

data/lib/amount/compact.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+class Amount
+  # Internal: compact notation for large numbers, used by `ui(compact: true)`.
+  #
+  # A number of at least one thousand is divided by the largest scale it
+  # reaches (thousand, million, ... up to decillion, 10**33), rounded to a number of
+  # significant digits in the given direction, trimmed of trailing zeros and
+  # joined with a scale word:
+  #
+  # - when localizing, the word is `number.human.decimal_units.units.<scale>`
+  #   (pluralized with the compacted number) joined by
+  #   `number.human.decimal_units.format` (default `"%n %u"`), the keys Rails'
+  #   `number_to_human` uses. A scale without a translation falls back to the
+  #   short form below.
+  # - otherwise the word is `K`, `M`, `B`, `T`, `Qa`, `Qi`, `Sx`, `Sp`, `Oc`,
+  #   `No` or `Dc`, joined as `"%n%u"`.
+  #
+  # Numbers past decillions stay in decillions (`1500Dc`).
+  #
+  # Numbers below one thousand are not compacted; {Display} formats them as
+  # usual.
+  #
+  # @example
+  #   Amount::Compact.format(BigDecimal("1999999"), precision: 3, direction: :floor, locale: nil)
+  #   # => "1.99M"
+  module Compact
+    DEFAULT_PRECISION = 3
+    SHORT_FORMAT = "%n%u"
+    LOCALE_FORMAT = "%n %u"
+    LOCALE_FORMAT_KEY = "number.human.decimal_units.format"
+    LOCALE_UNITS_KEY = "number.human.decimal_units.units"
+
+    # [exponent, I18n key, short form], smallest first.
+    SCALES = [
+      [3, :thousand, "K"],
+      [6, :million, "M"],
+      [9, :billion, "B"],
+      [12, :trillion, "T"],
+      [15, :quadrillion, "Qa"],
+      [18, :quintillion, "Qi"],
+      [21, :sextillion, "Sx"],
+      [24, :septillion, "Sp"],
+      [27, :octillion, "Oc"],
+      [30, :nonillion, "No"],
+      [33, :decillion, "Dc"]
+    ].freeze
+
+    module_function
+
+    # Reads the `compact:` option of `ui`.
+    # @param option [Boolean, Hash, nil] `true`, `false`/`nil`, or
+    #   `{ precision: Integer }`
+    # @return [Integer, nil] significant digits, or `nil` when compact
+    #   notation is off
+    # @raise [ArgumentError] for anything else
+    def precision(option)
+      case option
+      when nil, false then nil
+      when true then DEFAULT_PRECISION
+      when Hash then precision_from_hash(option)
+      else raise ArgumentError, "compact: must be true, false or { precision: Integer }, got #{option.inspect}"
+      end
+    end
+
+    # @param value [BigDecimal]
+    # @return [Boolean] whether the number is large enough to compact
+    def applies?(value)
+      value.abs >= BigDecimal(10)**SCALES.first[0]
+    end
+
+    # The compacted number with its scale word, e.g. `"1.5M"` or
+    # `"1,5 Mio."`. Call only when {applies?} is true.
+    # @param value [BigDecimal]
+    # @param precision [Integer] significant digits
+    # @param direction [Symbol] `:floor` or `:ceil`, as in `ui`
+    # @param locale [Symbol, String, nil]
+    # @return [String]
+    def format(value, precision:, direction:, locale:)
+      index = SCALES.rindex { |exponent, _, _| value.abs >= BigDecimal(10)**exponent }
+      loop do
+        mantissa, decimals = round(value, SCALES[index][0], precision, direction)
+        # Rounding up can reach the next scale: 999,999 ceils to 1000K, shown as 1M.
+        if mantissa.abs >= 1000 && index < SCALES.length - 1
+          index += 1
+          next
+        end
+
+        return join(number(mantissa, decimals, locale), mantissa, SCALES[index], locale)
+      end
+    end
+
+    # Divides by 10**exponent and rounds to `precision` significant digits.
+    # Returns the mantissa and how many decimals it may show.
+    def round(value, exponent, precision, direction)
+      mantissa = value / (BigDecimal(10)**exponent)
+      digits = [mantissa.abs.to_i.to_s.length, 1].max
+      decimals = precision - digits
+      [Display.round(mantissa, decimals, direction), [decimals, 0].max]
+    end
+
+    def number(mantissa, decimals, locale)
+      str = mantissa.to_s("F")
+      int, frac = str.split(".", 2)
+      frac = frac.to_s[0, decimals].sub(/0+\z/, "")
+      str = frac.empty? ? int : "#{int}.#{frac}"
+      locale ? Locale.apply(str, locale) : str
+    end
+
+    def join(number, mantissa, scale, locale)
+      _, key, short = scale
+      word = locale && Locale.translate("#{LOCALE_UNITS_KEY}.#{key}", locale, "", mantissa)
+      return Formattable.fill(SHORT_FORMAT, number:, label: short) if word.nil? || word.empty?
+
+      Formattable.fill(locale_format(locale), number:, label: word)
+    end
+
+    def locale_format(locale)
+      found = Locale.translate(LOCALE_FORMAT_KEY, locale, LOCALE_FORMAT)
+      Formattable.valid_template?(found) ? found : LOCALE_FORMAT
+    end
+
+    def precision_from_hash(option)
+      unknown = option.keys - [:precision]
+      raise ArgumentError, "unknown compact: option(s) #{unknown.map(&:inspect).join(', ')}" unless unknown.empty?
+
+      digits = option.fetch(:precision, DEFAULT_PRECISION)
+      return digits if digits.is_a?(Integer) && digits.positive?
+
+      raise ArgumentError, "compact: precision must be a positive Integer, got #{digits.inspect}"
+    end
+
+    private_class_method :round, :number, :join, :locale_format, :precision_from_hash
+  end
+end

data/lib/amount/{allocation.rb → concerns/allocatable.rb}

@@ -5,7 +5,7 @@ class Amount
   # `[parts, remainder]`, preserving the invariant that the parts plus
   # remainder always sum back to the receiver's atomic value (including
   # the sign).
-  module Allocation
+  module Allocatable
     # Splits into equal parts and returns the leftover explicitly.
     #
     # @param n [Integer]

data/lib/amount/{arithmetic.rb → concerns/calculable.rb}

@@ -6,7 +6,7 @@ class Amount
   #
   # All operators preserve the receiver's class via `build`, so subclass
   # identity (`GoldAmount`) survives through `+`, `-`, `*`, `/`, `abs`, `-@`.
-  module Arithmetic
+  module Calculable
     # @return [Amount]
     # @example
     #   Amount.of_usdc("-1").abs

data/lib/amount/concerns/coercible.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+class Amount
+  # Concern: bringing the other side of an operation into a usable form.
+  #
+  # - {ClassMethods#coerce_decimal} turns a scalar, rate or display-unit scale
+  #   into a `BigDecimal` without losing a `Rational`.
+  # - The private instance helpers bring another amount to the receiver's
+  #   type. They only cross types through a registered directional default
+  #   rate; without one they raise {TypeMismatch} (or return `nil` for
+  #   comparisons). There is no implicit conversion.
+  module Coercible
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # Class-level methods extended onto any class that does `include Coercible`.
+    module ClassMethods
+      # Coerces a numeric input to BigDecimal in a way that preserves Rational
+      # values. `BigDecimal(value.to_s)` raises `ArgumentError` for Rational
+      # because `Rational#to_s` produces strings like `"3/2"`. This helper is
+      # the single place every call site should use to convert a scalar / rate
+      # / display-unit scale into a BigDecimal.
+      #
+      # @param value [Numeric, BigDecimal, Rational, String]
+      # @return [BigDecimal]
+      def coerce_decimal(value)
+        case value
+        when BigDecimal then value
+        when Rational then BigDecimal(value, Float::DIG + 4)
+        else BigDecimal(value.to_s)
+        end
+      end
+    end
+
+    private
+
+    def ensure_same_type!(other)
+      return if same_type?(other)
+
+      raise TypeMismatch, type_mismatch_message(other)
+    end
+
+    # The other amount in the receiver's type: itself when the types match,
+    # converted through a registered default rate when one exists, else `nil`.
+    def coerce_other_to_self_type(other)
+      return other if same_type?(other)
+      return unless other.is_a?(Amount)
+
+      other.to(symbol)
+    rescue Registry::NoDefaultRate
+      nil
+    end
+
+    def coerce_other_to_self_type!(other)
+      coerce_other_to_self_type(other) || raise(TypeMismatch, type_mismatch_message(other))
+    end
+
+    def type_mismatch_message(other)
+      "type mismatch: #{symbol} vs #{other.is_a?(Amount) ? other.symbol : other.class}"
+    end
+  end
+end

data/lib/amount/concerns/constructible.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+class Amount
+  # Concern: how a constructor input becomes an atomic `Integer`, and which
+  # class an amount is built as.
+  #
+  # Input inference rules:
+  # - `Integer` => atomic units
+  # - `String` => UI decimal value
+  # - `Float`, `BigDecimal`, `Rational` => UI decimal value (a `Float` goes
+  #   through its string form, never through float math)
+  # - `from:` (`:atomic`, `:ui`, `:float`) overrides inference
+  #
+  # Class identity: a type registered with `class:` is always built as that
+  # class. `Amount.new` dispatches to it, and every operator that returns an
+  # amount goes through {#build} so the receiver's class carries through.
+  module Constructible
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # Class-level methods extended onto any class that does
+    # `include Constructible`.
+    module ClassMethods
+      # When called as `Amount.new` for a symbol whose registry entry binds a
+      # custom class, dispatch the construction to that class instead of
+      # raising. Direct calls to a subclass (`GoldAmount.new(...)`) still go
+      # through the default `Class.new` path. Calls that target the wrong
+      # subclass continue to raise from `#initialize`.
+      #
+      # @param value [Integer, String, Float, BigDecimal, Rational]
+      # @param symbol [Symbol, String]
+      # @param from [Symbol, nil]
+      # @return [Amount]
+      def new(value, symbol, from: nil)
+        if equal?(::Amount)
+          entry_class = registry.lookup(symbol.to_sym).amount_class
+          return entry_class.new(value, symbol, from:) if entry_class && entry_class != ::Amount
+        end
+        super
+      end
+    end
+
+    private
+
+    # Builds a same-symbol amount in the receiver's class. Used by every
+    # operator that returns an Amount so subclass identity propagates.
+    def build(atomic_value)
+      self.class.new(atomic_value, symbol, from: :atomic)
+    end
+
+    # A type registered with `class: GoldAmount` must be built as
+    # `GoldAmount` (or dispatched there by `Amount.new`), never as another
+    # subclass.
+    def ensure_registered_class!
+      expected = registry_entry.amount_class
+      return unless expected && expected != Amount && self.class != Amount && !instance_of?(expected)
+
+      raise InvalidInput, "use #{expected}.new for #{symbol}"
+    end
+
+    def infer_value(from, value)
+      case from || infer_type(value)
+      when :atomic then value.to_i
+      when :ui then ui_to_atomic(value)
+      when :float then ui_to_atomic(value.is_a?(Rational) ? value : value.to_s)
+      else
+        raise InvalidInput, "unknown amount format: #{value.inspect}"
+      end
+    end
+
+    def infer_type(value)
+      case value
+      when Integer then :atomic
+      when String then :ui
+      when Float, BigDecimal, Rational then :float
+      else
+        raise InvalidInput, "cannot infer type for #{value.class}"
+      end
+    end
+
+    def ui_to_atomic(value)
+      return (value * (10**decimals)).to_i if value.is_a?(Rational)
+
+      (BigDecimal(value.to_s) * (BigDecimal(10)**decimals)).to_i
+    rescue ArgumentError
+      raise InvalidInput, "cannot parse #{value.inspect} as #{symbol}"
+    end
+  end
+end

data/lib/amount/{conversion.rb → concerns/convertible.rb}

@@ -6,7 +6,7 @@ class Amount
   # default rate. The result class is taken from the target symbol's registry
   # entry, so a `class:`-registered subclass becomes the natural identity for
   # conversion outputs.
-  module Conversion
+  module Convertible
     # @param target_symbol [Symbol, String]
     # @param rate [String, Numeric, BigDecimal, nil]
     # @return [Amount]

data/lib/amount/concerns/formattable.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+class Amount
+  # Concern: where the number and its unit label go in decorated output.
+  #
+  # A format is a template in the style of Rails' `number.currency.format.format`:
+  # `%n` is the formatted number (sign included) and `%u` the unit label.
+  # Everything else is copied as given, so a non-breaking space in
+  # `"%n %u"` stays non-breaking.
+  #
+  # Included in {Amount}, it answers one question per amount, {#display_format}:
+  # which template does decorated `ui` output use, for this type or one of its
+  # display units, in this locale? The module functions are the template
+  # primitives the registry (validation) and {Display} (filling) share.
+  #
+  # A template is resolved, first match wins:
+  #
+  # - type: `amounts.formats.<symbol downcased>` (when localizing), then the
+  #   registered `display_format`, which the registry derives from
+  #   `display_position` when no template was given.
+  # - display unit: `amounts.display_unit_formats.<symbol downcased>.<unit>`
+  #   (when localizing), then the unit's `:format`, then its `:position`, then
+  #   the type's template as above.
+  #
+  # A locale template without `%n` is ignored, so a typo in a locale file can't
+  # drop the amount from the output.
+  #
+  # @example
+  #   Amount.register :EUR, decimals: 2, display_symbol: "€", display_format: "%u%n"
+  #   # de.yml: amounts.formats.eur: "%n %u"
+  #
+  #   Amount.of_eur("1").display_format               # => "%u%n"
+  #   Amount.of_eur("1").display_format(locale: :de)  # => "%n %u"
+  #   Amount::Formattable.fill("%n %u", number: "12,50", label: "€")
+  #   # => "12,50 €"
+  module Formattable
+    NUMBER = "%n"
+    LABEL = "%u"
+    PREFIX = "%u%n"
+    SUFFIX = "%n %u"
+
+    PLACEHOLDER = /%[nu]/
+    private_constant :PLACEHOLDER
+
+    # The template a `display_position` stands for: `:prefix` is `"%u%n"`,
+    # anything else `"%n %u"`, matching the output before templates existed.
+    # @param position [Symbol, nil]
+    # @return [String]
+    def self.template_for(position)
+      position == :prefix ? PREFIX : SUFFIX
+    end
+
+    # A usable template is a String that places the number.
+    # @param template [Object]
+    # @return [Boolean]
+    def self.valid_template?(template)
+      template.is_a?(String) && template.include?(NUMBER)
+    end
+
+    # Fills a template in one pass, so a `%` inside the number or label is
+    # never read as a placeholder.
+    # @param template [String]
+    # @param number [String] the formatted number
+    # @param label [String] the unit label
+    # @return [String]
+    def self.fill(template, number:, label:)
+      template.gsub(PLACEHOLDER, NUMBER => number, LABEL => label)
+    end
+
+    # The template decorated `ui` output uses for this amount.
+    #
+    # @param unit [Symbol, nil] a display unit, or `nil` for the type itself
+    # @param locale [Symbol, String, nil] look for a locale template too
+    #   (requires I18n). When `nil`, uses `I18n.locale` if `Amount.localize`
+    #   is true, else only the registered templates.
+    # @return [String]
+    # @raise [Registry::InvalidDisplayUnit] for an unknown display unit
+    # @example
+    #   Amount.of_usd("1").display_format                    # => "%u%n"
+    #   Amount.of_gold("1").display_format(unit: :gram)      # => "%n %u"
+    def display_format(unit: nil, locale: nil)
+      locale = Locale.effective(locale)
+      return type_display_format(locale) unless unit
+
+      spec = registry_entry.display_unit(unit)
+      (locale && locale_display_format(unit_format_key(unit), locale)) ||
+        spec[:format] ||
+        (spec[:position] && Formattable.template_for(spec[:position])) ||
+        type_display_format(locale)
+    end
+
+    private
+
+    def type_display_format(locale)
+      (locale && locale_display_format(type_format_key, locale)) ||
+        registry_entry.display_format
+    end
+
+    def locale_display_format(key, locale)
+      found = Locale.translate(key, locale, nil)
+      found if Formattable.valid_template?(found)
+    end
+
+    def type_format_key
+      "amounts.formats.#{symbol.to_s.downcase}"
+    end
+
+    def unit_format_key(unit)
+      "amounts.display_unit_formats.#{symbol.to_s.downcase}.#{unit}"
+    end
+  end
+end

data/lib/amount/concerns/localizable.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+class Amount
+  # Concern: the global switch that makes output and input follow
+  # `I18n.locale` when no `locale:` is given.
+  #
+  # Every locale-aware method (`ui`, `unit_label`, `display_format`,
+  # `Amount.parse_ui`) resolves its locale through {Locale.effective}, which
+  # reads this switch.
+  #
+  # @example
+  #   Amount.localize = true
+  #   I18n.locale = :de
+  #   Amount.of_usd("1500.5").ui # formatted with de's number.format
+  module Localizable
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # Class-level methods extended onto any class that does
+    # `include Localizable`.
+    module ClassMethods
+      # Whether `ui` formats numbers for `I18n.locale` when no `locale:` is
+      # given. Defaults to `false`.
+      # @return [Boolean]
+      def localize?
+        @localize ? true : false
+      end
+      alias localize localize?
+
+      # @param value [Boolean]
+      # @raise [ArgumentError] when enabling without I18n loaded
+      def localize=(value)
+        Locale.require_i18n! if value
+        @localize = value ? true : false
+      end
+    end
+  end
+end

data/lib/amount/{comparison.rb → concerns/orderable.rb}

@@ -3,10 +3,10 @@
 class Amount
   # Comparison, equality, hashing, and sign predicates for `Amount`.
   #
-  # Pulls in `Comparable` itself so consumers only need `include Comparison`
+  # Pulls in `Comparable` itself so consumers only need `include Orderable`
   # to get `<`, `<=`, `>`, `>=`, `between?`, `clamp`, and `Enumerable#min`/
   # `#max` alongside the explicit `<=>` / `==` / `eql?` / `hash` defined here.
-  module Comparison
+  module Orderable
     include Comparable
     # @param other [Object]
     # @return [Boolean]

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]