amounts 0.0.4 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b7620b025be07f1166e655108c2b9cea0232acb60d814cf91b71ecb47ddf1fb
-  data.tar.gz: 8f8ab43608f4ced54ab5020c7cbcf69b0741c9203e549558b27356766187efb5
+  metadata.gz: 01ce6cdf1c52884bc594317df4afa1debc6cfd90c1a6cbef0177e0ed8e2efe63
+  data.tar.gz: f796211c1f43214d5f8dc6f72d63715b4c901d96c9a4bed30e05220743740fee
 SHA512:
-  metadata.gz: 466350a8fbfff01e84bd044f23ced9d63288eb4147f13d70df2a3db9b37745cafee46e03cb3d1d9b0b805fff8ece3ca13df029c19786204f21e2fe1336b1e564
-  data.tar.gz: 807ba283121158491de02a78084dae5ce12c6360ac106a7d72a1bde6a7f536ac3009fdf329b9e75972fe3631ade8bdae3dd0f2d1f2d2e74f9a023f28d46f5cb1
+  metadata.gz: ebbf7e4ff014146a29243ae8dbd857a1833e09e6c5f3e4f124da382663ef0941346a4467a30815aa99ea0b1aa2fa9ace12c799dbf8456b63dbdf4b2f6ab6e5c1
+  data.tar.gz: 7e177014e0ad23a42cee97c6ae29f1d5c858426b211c1f63ebb3f23871c2e5aceb06edab03feee2efe26b4cf075c3d214e967d18882d3c93aff41226157ee6b9

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.0.6 - 2026-04-28
+
+### Added
+
+- `trim_zeros` option for `Amount.register` strips trailing zeros from `ui`
+  output. Defaults to `false` so fiat currencies keep fixed decimals (`$1.50`).
+  Set `true` for tokens with high precision to get clean output (`1.5 SOL`
+  instead of `1.5000 SOL`). Display units can override via
+  `display_units: { gram: { ..., trim_zeros: false } }`.
+- `Amount#ui(trim_zeros:)` call-site override. Pass `true` or `false` to
+  override the registry and display-unit settings for a single render.
+  Precedence: call-site > display unit spec > registry default.
+- Railtie `initializer` block that auto-requires `amount/active_record` in
+  Rails apps. `has_amount` and `t.amount` are now available without manual
+  `require` statements — Bundler's auto-require of the `amounts` gem handles
+  everything.
+
+## 0.0.5 - 2026-04-26
+
+### Added
+
+- `Amount#ui(decorated: false)` returns the rounded UI value as a plain
+  numeric string without the `display_symbol` prefix or suffix. Useful when
+  the caller renders the currency label separately (e.g. in a column header
+  or chip). Composes with `unit:` and `direction:` — for example,
+  `Amount.gold("1").ui(unit: :gram, decorated: false)` returns `"31.10"`.
+  Default remains `decorated: true`, so existing callers see no change.
+
 ## 0.0.4 - 2026-04-26
 
 ### Changed (breaking)

data/README.md

@@ -1,9 +1,14 @@
+> **You are reading the gem package readme.** The repository also contains
+> [`site/`](../site) (the docs site) and [`demo/`](../demo) (a Rails
+> case-study app that exercises every feature). See the
+> [root README](../README.md) for the layout overview.
+
 # amounts
 
 [![Gem Version](https://img.shields.io/gem/v/amounts)](https://rubygems.org/gems/amounts)
 [![CI](https://github.com/zarpay/amounts/actions/workflows/ci.yml/badge.svg)](https://github.com/zarpay/amounts/actions/workflows/ci.yml)
 [![Release](https://img.shields.io/github/v/release/zarpay/amounts)](https://github.com/zarpay/amounts/releases)
-[![License](https://img.shields.io/github/license/zarpay/amounts)](https://github.com/zarpay/amounts/blob/main/LICENSE.txt)
+[![License](https://img.shields.io/github/license/zarpay/amounts)](https://github.com/zarpay/amounts/blob/main/gem/LICENSE.txt)
 [![Ruby](https://img.shields.io/badge/Ruby-%3E%3D%203.1-red)](https://rubygems.org/gems/amounts)
 
 `amounts` is a Ruby gem for precise quantities of fungible things: money, crypto tokens, commodities, inventory units, points, and similar value-like amounts. It stores every value as an arbitrary-precision atomic `Integer`, keeps type identity in a registry, rejects accidental cross-type math unless an explicit directional rate exists, and offers an optional ActiveRecord adapter without making Rails part of the core runtime.
@@ -32,6 +37,10 @@ Load the Rails adapter only when needed:
 require "amount/active_record"
 ```
 
+If the gem is bundled into a Rails app, the Rails-only generator hooks are
+loaded through the adapter railtie. You do not need a separate top-level
+generator require.
+
 ## Quickstart
 
 ```ruby
@@ -235,6 +244,22 @@ Load the adapter explicitly:
 require "amount/active_record"
 ```
 
+### Preset registry generator
+
+In a Rails app, you can generate a starter initializer with curated baskets of
+registered symbols:
+
+```bash
+bin/rails generate amounts:registry fiat
+bin/rails generate amounts:registry metals
+bin/rails generate amounts:registry crypto
+bin/rails generate amounts:registry all
+```
+
+The generator writes `config/initializers/amounts.rb` with registration
+metadata only. It intentionally does not register default conversion rates,
+because those are directional and application-specific.
+
 ### Migration DSL
 
 ```ruby

data/lib/amount/active_record/railtie.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class Amount
+  module ActiveRecord
+    class Railtie < ::Rails::Railtie
+      initializer "amount.active_record" do
+        require "amount/active_record"
+      end
+
+      generators do
+        require_relative "../../../generators/amount/active_record/registry_generator"
+      end
+    end
+  end
+end

data/lib/amount/display.rb

@@ -18,9 +18,26 @@ class Amount
 
     # @param unit [Symbol, nil]
     # @param direction [Symbol]
+    # @param decorated [Boolean] when `false`, omit the display symbol and
+    #   return just the rounded number. Useful when the caller renders the
+    #   currency label separately (e.g. in a column header or a chip).
+    # @param trim_zeros [Boolean, nil] strip trailing zeros from the formatted
+    #   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.
     # @return [String]
-    def ui(unit: nil, direction: :floor)
-      unit ? render_display_unit(unit, direction) : render_default(direction)
+    # @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
     end
 
     # @return [String]
@@ -37,19 +54,24 @@ class Amount
 
     private
 
-    def render_default(direction)
+    def render_default(direction, decorated:, trim_zeros:)
       rounded = round(@amount.decimal, @entry.ui_decimals, direction)
-      apply_symbol(format("%.#{@entry.ui_decimals}f", rounded), @entry.display_symbol, @entry.display_position)
+      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)
+    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
 
       apply_symbol(
-        format("%.#{decimals}f", rounded),
+        formatted,
         spec[:symbol] || @entry.display_symbol,
         spec[:position] || @entry.display_position
       )
@@ -73,6 +95,18 @@ class Amount
       truncated / factor
     end
 
+    def format_number(value, decimals, trim)
+      str = format("%.#{decimals}f", value)
+      trim ? str.sub(/(\.\d*?)0+\z/, '\1').chomp('.') : str
+    end
+
+    def resolve_trim(call_site, spec = nil)
+      return call_site unless call_site.nil?
+      return spec[:trim_zeros] if spec&.key?(:trim_zeros)
+
+      @entry.trim_zeros
+    end
+
     def apply_symbol(str, symbol, position)
       return str if symbol.nil? || symbol.empty?
 

data/lib/amount/registry.rb

@@ -35,6 +35,7 @@ class Amount
       :display_units,
       :default_display,
       :amount_class,
+      :trim_zeros,
       keyword_init: true
     )
 
@@ -60,6 +61,7 @@ class Amount
     # @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
+    # @param trim_zeros [Boolean] strip trailing zeros from UI output
     # @param class [Class, nil] optional custom `Amount` subclass
     # @return [void]
     # @raise [AlreadyRegistered] if the symbol is already registered or the
@@ -73,7 +75,7 @@ class Amount
     #     ui_decimals: 2
     def register(symbol, decimals:, display_symbol: symbol.to_s, display_position: :suffix,
                  ui_decimals: decimals, display_units: nil, default_display: nil,
-                 class: nil)
+                 trim_zeros: false, class: nil)
       raise ArgumentError, "symbol must not be blank" if symbol.nil? || symbol.to_s.empty?
 
       symbol = symbol.to_sym
@@ -92,7 +94,8 @@ class Amount
           ui_decimals:,
           display_units:,
           default_display:,
-          amount_class: binding.local_variable_get(:class) || Amount
+          amount_class: binding.local_variable_get(:class) || Amount,
+          trim_zeros:
         )
 
         @entries[symbol] = entry

data/lib/amount/version.rb

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

data/lib/amounts.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Thin gem-name entrypoint for Bundler auto-require.
+# Core users should still require "amount" directly.
+require_relative "amount"
+
+begin
+  require "rails/railtie"
+  require_relative "amount/active_record/railtie"
+rescue LoadError
+  nil
+end

data/lib/generators/amount/active_record/registry_generator.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+class Amount
+  module ActiveRecord
+    class RegistryGenerator < ::Rails::Generators::Base
+      namespace "amounts:registry"
+
+      source_root File.expand_path("templates", __dir__)
+      VALID_PRESETS = %i[fiat metals crypto all].freeze
+
+      argument :preset, type: :string, banner: "fiat|metals|crypto|all"
+
+      def create_initializer
+        template "registry.rb.tt", "config/initializers/amounts.rb"
+      end
+
+      private
+
+      def preset_key
+        @preset_key ||= begin
+          key = preset.to_s.downcase.to_sym
+          if VALID_PRESETS.include?(key)
+            key
+          else
+            raise ::Thor::Error,
+                  "unknown preset #{preset.inspect}; choose one of: fiat, metals, crypto, all"
+          end
+        end
+      end
+
+      def preset_categories
+        preset_key == :all ? %i[fiat metals crypto] : [preset_key]
+      end
+
+      def preset_name
+        preset_key.to_s
+      end
+
+      def registered_symbols
+        @registered_symbols ||= preset_body.scan(/Amount\.register :([A-Z0-9_]+),/).flatten
+      end
+
+      def registry_guard_symbol
+        registered_symbols.first
+      end
+
+      def preset_body
+        @preset_body ||= File.read(
+          File.join(self.class.source_root, "presets", "#{preset_name}.fragment")
+        ).chomp
+      end
+
+      def preset_source_label
+        preset_name
+      end
+    end
+  end
+end