minting 1.7.0 → 1.7.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 005a740f595e3f1b579b2108feb4cd742706588a75b1df41179775d311fb002e
-  data.tar.gz: b1c2d55e378cca46adde3e6edd7253bb0914707768c19fd00e568288921540ff
+  metadata.gz: 7ebe31c2ae1b9febafa3a6a4ccea1392cb089242746a933d530121b08f55cd4e
+  data.tar.gz: 80f1eb17f62b7a7924df8b2fedb79d864bcadd5ea5e8432e5149b14fb0d9af0c
 SHA512:
-  metadata.gz: 48f40d6cceeb16d9ffc357297dae0961ba0473f4d9ed1271ac6e144a0a468b42dd8a553b661485317eba56d88665b08b1302c4620af1a58bb6f07ab9aa996da3
-  data.tar.gz: bc77e69b3e39d3bde0ebb47e60bb1225d0a9062e2a1f201924c3e32924ad65711c28ef492ac4c5d63b06bb376510d07e7d2d69a3efbc17805e89d703c3c15812
+  metadata.gz: 44147d3523485fc36491bb62f24df5f4040fe3ddda673201d5b6fc9a5e005bda94cd3300b4e84682f4378cb9eedb851ad16c247a2dfeb9de264fd24a6b1714ca
+  data.tar.gz: 5f41672831c8c722e47de8b8e94549bb633c48b677fc8e63eca9f10233062f32a0acd276b31271a4f0ac4417779b03db7f034a9b9afcfbd39c0cbadb16886dbf

data/README.md

@@ -3,23 +3,10 @@
 Fast, precise, and developer-friendly money handling for Ruby.
 
 [![Gem Version](https://badge.fury.io/rb/minting.svg)](https://badge.fury.io/rb/minting)
-
-## Why Minting?
-
-**Tired of floating-point errors in financial calculations?** Minting uses Rational numbers for perfect precision.
-
-**Need performance?** Minting is 2× faster than alternatives for high-volume operations (often 10×+ for formatting). See the [Performance](https://github.com/gferraz/minting/blob/master/test/performance/README.md) section for full benchmarks.
-
-**Want a clean API?** Minting provides an intuitive interface with helpful error messages.
-
-**Looking for a proven alternative?** Check out the established [Money gem](https://github.com/RubyMoney/money) with thousands of stars on GitHub.
-
-**Rails**? Use the [minting-rails](https://github.com/gferraz/minting-rails) companion gem
-
-## Resources
-
-- [API Documentation](https://www.rubydoc.info/gems/minting/frames)
-- [Git Repository](https://github.com/gferraz/minting)
+[![CI](https://github.com/gferraz/minting/actions/workflows/ci.yml/badge.svg)](https://github.com/gferraz/minting/actions/workflows/ci.yml)
+[![Test Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/gferraz/minting)
+[![RubyCritic](https://img.shields.io/badge/RubyCritic-94gem /100-brightgreen)](https://github.com/gferraz/minting)
+[![Documentation](https://img.shields.io/badge/docs-rubydoc.info-blue)](https://www.rubydoc.info/gems/minting/frames)
 
 ## Quick start
 
@@ -34,16 +21,44 @@ total.to_s                             #=> "$21.59"
 total.currency_code                    #=> "USD"
 ```
 
-## Features
+## Why Minting?
+
+|                    | Minting                                   |
+|--------------------|-------------------------------------------|
+| **Precision**      | Rational-based, zero floating-point error |
+| **Performance**    | **2× faster** (10×+ formatting)           |
+| **Ruby support**   | 3.3+ (including Ruby 4.0)                 |
+| **Rails**          | Dedicated companion gem                   |
+| **Code quality**   | 100% coverage, 93/100 RubyCritic          |
+
+### 🎯 Exact precision
+Amounts are stored as `Rational` and rounded to the currency subunit. No floating-point surprises, ever.
+
+### ⚡ Blazing performance
+Minting is **2× faster** than the Money gem for everyday operations and **over 10× faster for formatting**. See full benchmarks in the [Performance Guide](test/performance/README.md).
+
+### 🧼 Clean, modern API
+Intuitive interface, descriptive error messages, and sensible defaults. Works the way you expect.
+
+### 🚆 Rails-ready
+Use with the [minting-rails](https://github.com/gferraz/minting-rails) companion gem for drop-in ActiveRecord type casting, validators, and form helpers.
 
-- Arithmetic: `+ - * /`, unary minus, `abs`
-- Comparisons: `==`, `<=>`, `zero?`, `nonzero?`, `positive?`, `negative?`
-- Formatting: `to_s` with custom formats, thousand delimiters and decimal separators
-- Serialization: `to_json`, `to_i`, `to_f`, `to_r`, `to_d`
-- Allocation utilities: `split(quantity)`, `allocate([ratios])`, 
-- Utilities: `clamp(min, max)`
-- Numeric Refinements for ergonomics: `10.dollars`, `3.euros`, `4.to_money('USD')`
-- Currency registry with 117+ currencies and custom registration
+### 🏆 Quality you can trust
+- **100% test coverage** — every line exercised
+- **93/100 RubyCritic score** — clean, maintainable code
+- **CI-tested on Ruby 3.3 and 4.0**
+
+## Installation
+
+```shell
+bundle add minting
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem 'minting'
+```
 
 ## Usage
 
@@ -66,16 +81,15 @@ ten == Mint.money(10, 'EUR')     #=> false
 ten > Mint.money(9.99, 'USD')    #=> true
 
 # Zero equality semantics
-# Any zero amount is treated as equal, regardless of currency 
-Mint.money(0, 'USD') == Mint.money(0, 'EUR')  #=> true
+# Any zero amount is treated as equal, regardless of currency
+Mint.money(0, 'USD') == Mint.money(0, 'EUR')   #=> true
 Mint.money(0, 'USD') == 0                      #=> true
 Mint.money(0, 'USD') == 0.0                    #=> true
-Mint.money(0, 'USD') == 0r                     #=> true
 
 # Non-zero numerics are not equal to Money objects
 Mint.money(10, 'USD') == 10                    #=> false
 
-# Format (uses Kernel.format internally)
+# Format (uses Kernel.format syntax)
 price = Mint.money(9.99, 'USD')
 
 price.to_s                                  #=> "$9.99",
@@ -141,128 +155,82 @@ price.clamp(min_price, 100) #=> [USD 75.00]
 
 ```
 
-## API notes
-
-**Module names** — Require the `minting` gem; the public API lives under `Mint`.
-
-**Exact amounts** — Amounts are stored as `Rational` and rounded to the currency subunit.
-
-**Refinements** — `10.dollars` and similar helpers require `using Mint` in the current scope (see Usage above).
-
-**Division** — `money / 5` returns new `Money`; `money / other_money` returns a numeric ratio, not money.
-
-**Zero equality** — Any zero amount is considered equal across currencies and to numeric zero `Mint.money(0, 'USD') == Mint.money(0, 'EUR')` is intentionally `true`. Non-zero amounts must match currency and value.
-
-**Custom currencies** — `Mint.register_currency`, Only registered currency codes and symbolos are recoginized by the parser.
-
-**Built-in currencies** — ISO-style codes ship in `lib/minting/data/currencies.yaml` and load when the registry is first accessed.
-
-## Installation
-
-Option 1: Via bundler command
-
-```shell
-bundle add minting
-bundle install
-```
-
-Option 2: add the line below to your application's Gemfile:
+## Parsing strings
 
 ```ruby
-gem 'minting'
+Mint.parse('$19.99')           #=> [USD 19.99]
+Mint.parse('19,99 €')          #=> [EUR 19.99]
+Mint.parse('1.234,56', 'EUR')  #=> [EUR 1234.56]
+Mint.parse('USD 1,234.56')     #=> [USD 1234.56]
 ```
 
-or, if you want latest development version from Github
+Notes:
+- Pass a currency code when the string has no symbol or code.
+- `1,234` means 1234, not 1.234 and `1,23` means 1.23, not 123
+- `1,234.00` is unambiguous (thousands + decimal).
+- Accounting negatives like `($1.23)` are unsupported for now.
+- Ambiguous symbols like `$` resolve by currency priority (currently USD).
+- The parser scans all uppercase words for registered codes, so spurious non-currency words before the real code are correctly ignored: `Mint.parse("MAX 10.00 USD")` yields `[USD 10.00]`.
+
+## Currency lookup
 
 ```ruby
-gem 'minting', git: 'https://github.com/gferraz/minting.git'
-```
+# By ISO code (direct hash lookup, string only)
+Mint.currency_for_code('USD')        #=> #<Currency code="USD" ...>
 
-and execute:
+# By display symbol (highest-priority currency for ambiguous symbols)
+Mint.currency_for_symbol('$')        #=> #<Currency code="USD" ...>
+Mint.currency_for_symbol('R$')       #=> #<Currency code="BRL" ...>
+Mint.currency_for_symbol('€')        #=> #<Currency code="EUR" ...>
 
-```shell
-bundle install
 ```
 
-Option 3: Install it yourself with:
+## API notes
 
-```shell
-gem install minting
-```
+**Exact amounts** — Amounts are stored as `Rational` and rounded to the currency subunit.
 
-## Configuration
+**Refinements** — `10.dollars` and similar helpers require `using Mint` in the current scope (see Usage above).
 
-### Optional top‑level `Money` and `Currency`
+**Division** — `money / 5` returns new `Money`; `money / other_money` returns a numeric ratio, not money.
 
-By default, Minting keeps everything namespaced under `Mint`:
+**Zero equality** — Any zero amount is considered equal across currencies and to numeric zero (`Mint.money(0, 'USD') == Mint.money(0, 'EUR')` is intentionally `true`). Non-zero amounts must match currency and value.
 
-```ruby
-price    = Mint::Money.create(10, "USD")
-currency = Mint::Currency.new(code: "USD", symbol: "$", subunit: 2, priority: 0)
-```
+**Zero helper** — `Mint.zero('USD')` returns a frozen zero-Money, useful as a default value for discounts, totals, or counters.
 
-To avoid polluting the global namespace (and to coexist nicely with other gems), **Minting dont automatically defines `Money` or `Currency` at the top level automatically**.
+**Registered currencies** — `Mint.register_currency(code:, subunit:, symbol:, priority:)` adds custom currencies. Only registered codes and symbols are recognized by the parser.
 
-If you prefer the shorter `Money` / `Currency` constants in your application code, you can opt in explicitly.
+**Built-in currencies** — 150+ ISO-4217 world currencies ship in `lib/minting/data/currencies.yaml` and load when the registry is first accessed.
 
-There are two ways to enable shorter constants:
+## Optional top-level `Money` and `Currency`
 
-1. Require dsl in your app
+By default, Minting keeps everything namespaced under `Mint` to coexist nicely with other gems. If you prefer shorter constants, opt in:
 
 ```ruby
 require "minting"
 require "minting/dsl"  # opt‑in top‑level Money / Currency
 ```
 
-2. Call a configuration method
+Or at runtime:
 
 ```ruby
 Minting.use_top_level_constants!
 ```
 
-After this, you can use:
+After opting in:
 
 ```ruby
 price = Money.create(10, "USD")     # equivalent to Mint::Money.create
-tax   = Money.money(2.50, "USD")   # via Mint.money, still available
+tax   = Money.money(2.50, "USD")
 cur   = Currency.new(code: "EUR", symbol: "€", subunit: 2, priority: 0)
 ```
 
-#### When to use this
-
-- **Good fit:** application code, especially in Rails apps, where `Money` reads nicely in models and views.
-- **Not recommended:** reusable gems/libraries. In that case, stick to the namespaced API (`Mint::Money`, `Mint::Currency`) to avoid conflicts with other libraries.
-
-## Parsing strings
-
-```ruby
-Mint.parse('$19.99')           #=> [USD 19.99]
-Mint.parse('19,99 €')          #=> [EUR 19.99]
-Mint.parse('1.234,56', 'EUR')  #=> [EUR 1234.56]
-Mint.parse('USD 1,234.56')     #=> [USD 1234.56]
-```
-
-- Pass a currency code when the string has no symbol or code. 
-- 1,234 means 1.234, not 1234, because one comma is treated as decimal.
-- 1,234.00 is unambiguous thousands-plus-decimal.
-- accounting negatives like ($1.23) are unsupported.
-- ambiguous symbols like $ resolve by priority, currently USD.
+**Good fit:** Application code, especially Rails apps.
+**Not recommended:** Reusable gems/libraries — stick to `Mint::Money` to avoid conflicts.
 
 ## Roadmap
 
-- Add support to configure thousand and decimal separators in parse (evaluating)
 - Localization (I18n-aware formatting)
-- Basic exchange-rate conversions - infrastructure only, not integrations yet
-
-## Contributing
-
-Bug reports and pull requests are welcome on GitHub at <https://github.com/gferraz/minting>.
-
-1. Fork and create a feature branch
-2. Run the test suite: `rake`
-3. Run performance suites as needed: `rake bench:performance`
-4. Open a PR with a clear description and benchmarks if relevant
-
+- Exchange-rate conversion infrastructure
 
 ## License
 

data/Rakefile

@@ -39,6 +39,19 @@ Rake::TestTask.new('bench:competitive') do |t|
   t.pattern = 'test/performance/competitive/**/*_benchmark.rb'
 end
 
+desc 'Run core benchmarks and update the baseline'
+task 'bench:baseline' do
+  platform = RUBY_PLATFORM
+  baseline = "test/performance/check/results/baseline-#{platform}.json"
+  sh "ruby test/performance/check/runner.rb #{baseline}"
+  puts "Baseline updated for #{platform}."
+end
+
+desc 'Run core benchmarks and check for regressions against the baseline'
+task 'bench:check' do
+  ruby 'bin/bench_check'
+end
+
 Bundler::Audit::Task.new
 
 RuboCop::RakeTask.new(:cop) do |task|
@@ -51,7 +64,6 @@ end
 
 YARD::Rake::YardocTask.new do |t|
   t.files   = ['lib/**/*.rb']
-  #t.options = ['-o doc'] # Place the documentos in doc/api
   t.stats_options = ['--list-undoc']
 end
 

data/bin/bench_check

@@ -0,0 +1,46 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'json'
+require 'tempfile'
+
+platform = RUBY_PLATFORM
+results_dir = File.expand_path('../test/performance/check/results', __dir__)
+baseline_path = File.join(results_dir, "baseline-#{platform}.json")
+threshold = (ARGV[0] || 0.80).to_f
+
+unless File.exist?(baseline_path)
+  puts "No baseline for #{platform} at #{baseline_path}. Skipping check."
+  exit 0
+end
+
+baseline = JSON.parse(File.read(baseline_path))
+current_json = Tempfile.new(%w[bench_current .json])
+
+unless system("bundle exec ruby test/performance/check/runner.rb #{current_json.path}")
+  puts 'Benchmark runner failed.'
+  exit 1
+end
+
+current = JSON.parse(File.read(current_json.path))
+
+failures = []
+baseline['results'].each do |key, b|
+  c = current.dig('results', key)
+  next unless c
+
+  ratio = c['ips'].to_f / b['ips']
+  if ratio < threshold
+    failures << format('%<key>-15s baseline: %<b>10d ips  current: %<c>10d ips  ratio: %<ratio>5.1f%%',
+                       key:, b: b['ips'], c: c['ips'], ratio: ratio * 100)
+  end
+end
+
+puts "\n--- Benchmark Regression Check ---"
+if failures.empty?
+  puts 'All benchmarks within 20% of baseline.'
+else
+  puts 'Regressions detected:'
+  failures.each { |f| puts "  FAIL  #{f}" }
+  exit 1
+end