minting 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4dfd2f98840b009208b9cccab86e9ca5d093300351e9e2031e70e03b93315638
-  data.tar.gz: 47a92df548558e20fd7bea3caa10a8966db91341d998e9712405af3d97fe12ae
+  metadata.gz: be78b384415345ebacec84c0fc7194c9cb5e8ae2c3f601db5871822987f7e95c
+  data.tar.gz: 0c852f37bca70dc4af732b824daca634a5b253d4497a10273cc9d041ccf327aa
 SHA512:
-  metadata.gz: 175607c53124f16cac60c699a6ed6f042b3c3e960055bca1ccb7ba822a05b6cf8401fb66902e148a9ed50b43524ce6e708feaa72cac15f6ddd8b9cf3e9189cc6
-  data.tar.gz: 4fc09433abd38014d0d99c16aed5f88eb36ad039e422b0ffa305d3335da1753a23bae2bfcf775ce6142edf844463ed3942710d87f034375f99e04ff1b7e92812
+  metadata.gz: 6e13eed34f93beb1a1e26cf89a89fb89a57a06529225610d8cc153c6eae28823368b47a993446e2e4deb3df30cecf31800253a7c55dd070bd6dcb074f615fb91
+  data.tar.gz: 8e2f204fbd592e93f143ed8756548d2013e909bca37d32a2fa70f41c070a3ede1946f668097faf49822a1e5e9df27cc9cf7865208faa94df47c310e06d96cd24

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gilson Ferraz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -33,7 +33,7 @@ total.currency_code                    #=> "USD"
 
 - Arithmetic: `+ - * /`, unary minus, `abs`
 - Comparisons: `==`, `<=>`, `zero?`, `nonzero?`, `positive?`, `negative?`
-- Formatting: `to_s` with custom formats, delimiters, separators
+- 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])`
 - Numeric Refinements for ergonomics: `10.dollars`, `3.euros`, `4.to_money('USD')`
@@ -59,6 +59,16 @@ ten == 10.dollars                #=> true
 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
+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)
 price = Mint.money(9.99, 'USD')
 
@@ -93,6 +103,22 @@ ten.allocate([1, 2, 3])                #=> [[USD 1.67], [USD 3.33], [USD 5.00]]
 
 ```
 
+## API notes
+
+**Module names** — Require the `minting` gem; the public API lives under `Mint` (the gem module is `Minting::VERSION`).
+
+**Exact amounts** — Amounts are stored as `Rational` and rounded to the currency subunit. Prefer rationals or decimal strings for exact literals (`Mint.money(1999/100r, 'USD')`, `'19.99'.to_r`) instead of binary floats when precision matters.
+
+**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** — `Mint.money(0, 'USD') == Mint.money(0, 'EUR')` is intentionally `true`. Non-zero amounts must match currency and value.
+
+**Custom currencies** — `Mint.register_currency` returns the existing entry if the code is already registered; use `register_currency!` to detect duplicates.
+
+**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
@@ -126,11 +152,25 @@ Option 3: Install it yourself with:
 gem install minting
 ```
 
+## Parsing strings
+
+```ruby
+Mint::Money.parse('$19.99')           #=> [USD 19.99]
+Mint::Money.parse('19,99 €')          #=> [EUR 19.99]
+Mint::Money.parse('1.234,56', 'EUR')  #=> [EUR 1234.56]
+Mint::Money.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.
+
 ## Roadmap
 
 - Improve formatting features
 - Localization (I18n-aware formatting)
-- `Mint.parse` for parsing human strings into money
 - Basic exchange-rate conversions
 
 ## Contributing

data/lib/minting/data/currencies.yaml

@@ -0,0 +1,469 @@
+---
+USD:
+  subunit: 2
+  symbol: "$"
+  priority: 1000
+EUR:
+  subunit: 2
+  symbol: "€"
+  priority: 950
+JPY:
+  subunit: 0
+  symbol: "¥"
+  priority: 900
+GBP:
+  subunit: 2
+  symbol: "£"
+  priority: 850
+CNY:
+  subunit: 2
+  symbol: "¥"
+  priority: 800
+INR:
+  subunit: 2
+  symbol: "₹"
+  priority: 760
+CAD:
+  subunit: 2
+  symbol: "$"
+  priority: 740
+AUD:
+  subunit: 2
+  symbol: "$"
+  priority: 730
+CHF:
+  subunit: 2
+  symbol: Fr
+  priority: 720
+HKD:
+  subunit: 2
+  symbol: HK$
+  priority: 710
+SGD:
+  subunit: 2
+  symbol: S$
+  priority: 700
+KRW:
+  subunit: 0
+  symbol: "₩"
+  priority: 690
+SEK:
+  subunit: 2
+  symbol: kr
+  priority: 680
+NOK:
+  subunit: 2
+  symbol: kr
+  priority: 670
+DKK:
+  subunit: 2
+  symbol: kr
+  priority: 660
+NZD:
+  subunit: 2
+  symbol: "$"
+  priority: 650
+MXN:
+  subunit: 2
+  symbol: "$"
+  priority: 640
+BRL:
+  subunit: 2
+  symbol: R$
+  priority: 630
+ZAR:
+  subunit: 2
+  symbol: R
+  priority: 620
+SAR:
+  subunit: 2
+  symbol: "﷼"
+  priority: 610
+AED:
+  subunit: 2
+  symbol: د.إ
+  priority: 600
+IDR:
+  subunit: 2
+  symbol: Rp
+  priority: 113
+PKR:
+  subunit: 2
+  symbol: "₨"
+  priority: 112
+NGN:
+  subunit: 2
+  symbol: "₦"
+  priority: 111
+BDT:
+  subunit: 2
+  symbol: "৳"
+  priority: 109
+XOF:
+  subunit: 0
+  symbol: CFA
+  priority: 108
+RUB:
+  subunit: 2
+  symbol: "₽"
+  priority: 107
+ETB:
+  subunit: 2
+  symbol: Br
+  priority: 105
+PHP:
+  subunit: 2
+  symbol: "₱"
+  priority: 103
+EGP:
+  subunit: 2
+  symbol: "£"
+  priority: 102
+VND:
+  subunit: 0
+  symbol: "₫"
+  priority: 101
+IRR:
+  subunit: 2
+  symbol: "﷼"
+  priority: 100
+TRY:
+  subunit: 2
+  symbol: "₺"
+  priority: 99
+THB:
+  subunit: 2
+  symbol: "฿"
+  priority: 98
+TZS:
+  subunit: 2
+  symbol: TSh
+  priority: 96
+XAF:
+  subunit: 0
+  symbol: FCFA
+  priority: 95
+KES:
+  subunit: 2
+  symbol: KSh
+  priority: 93
+MMK:
+  subunit: 2
+  symbol: K
+  priority: 92
+COP:
+  subunit: 2
+  symbol: "$"
+  priority: 91
+UGX:
+  subunit: 0
+  symbol: USh
+  priority: 89
+ARS:
+  subunit: 2
+  symbol: "$"
+  priority: 88
+DZD:
+  subunit: 2
+  symbol: د.ج
+  priority: 87
+IQD:
+  subunit: 3
+  symbol: د.ع
+  priority: 86
+AFN:
+  subunit: 2
+  symbol: "؋"
+  priority: 85
+MAD:
+  subunit: 2
+  symbol: د.م.
+  priority: 83
+PLN:
+  subunit: 2
+  symbol: zł
+  priority: 82
+UAH:
+  subunit: 2
+  symbol: "₴"
+  priority: 80
+AOA:
+  subunit: 2
+  symbol: Kz
+  priority: 79
+UZS:
+  subunit: 2
+  symbol: лв
+  priority: 78
+GHS:
+  subunit: 2
+  symbol: "¢"
+  priority: 77
+MYR:
+  subunit: 2
+  symbol: RM
+  priority: 76
+MZN:
+  subunit: 2
+  symbol: MT
+  priority: 75
+PEN:
+  subunit: 2
+  symbol: S/.
+  priority: 74
+NPR:
+  subunit: 2
+  symbol: "₨"
+  priority: 73
+VES:
+  subunit: 2
+  symbol: Bs.
+  priority: 72
+TWD:
+  subunit: 2
+  symbol: NT$
+  priority: 70
+LKR:
+  subunit: 2
+  symbol: "₨"
+  priority: 69
+MWK:
+  subunit: 2
+  symbol: MK
+  priority: 68
+CLP:
+  subunit: 0
+  symbol: "$"
+  priority: 67
+KZT:
+  subunit: 2
+  symbol: "₸"
+  priority: 66
+ZMW:
+  subunit: 2
+  symbol: ZK
+  priority: 65
+RON:
+  subunit: 2
+  symbol: lei
+  priority: 64
+GTQ:
+  subunit: 2
+  symbol: Q
+  priority: 63
+KHR:
+  subunit: 2
+  symbol: "៛"
+  priority: 62
+RWF:
+  subunit: 0
+  symbol: R₣
+  priority: 61
+BIF:
+  subunit: 0
+  symbol: FBu
+  priority: 60
+BOB:
+  subunit: 2
+  symbol: "$b"
+  priority: 59
+HTG:
+  subunit: 2
+  symbol: G
+  priority: 58
+TND:
+  subunit: 3
+  symbol: د.ت
+  priority: 57
+CZK:
+  subunit: 2
+  symbol: Kč
+  priority: 56
+DOP:
+  subunit: 2
+  symbol: RD$
+  priority: 55
+HNL:
+  subunit: 2
+  symbol: L
+  priority: 54
+JOD:
+  subunit: 3
+  symbol: د.ا
+  priority: 53
+AZN:
+  subunit: 2
+  symbol: "₼"
+  priority: 50
+HUF:
+  subunit: 2
+  symbol: Ft
+  priority: 49
+ILS:
+  subunit: 2
+  symbol: "₪"
+  priority: 48
+PGK:
+  subunit: 2
+  symbol: K
+  priority: 47
+TJS:
+  subunit: 2
+  symbol: SM
+  priority: 46
+BYN:
+  subunit: 2
+  symbol: Br
+  priority: 45
+LAK:
+  subunit: 2
+  symbol: "₭"
+  priority: 42
+KGS:
+  subunit: 2
+  symbol: лв
+  priority: 41
+LYD:
+  subunit: 3
+  symbol: ل.د
+  priority: 40
+NIO:
+  subunit: 2
+  symbol: C$
+  priority: 39
+PYG:
+  subunit: 0
+  symbol: Gs
+  priority: 38
+RSD:
+  subunit: 2
+  symbol: Дин.
+  priority: 37
+BGN:
+  subunit: 2
+  symbol: лв
+  priority: 36
+CRC:
+  subunit: 2
+  symbol: "₡"
+  priority: 32
+KWD:
+  subunit: 3
+  symbol: د.ك
+  priority: 30
+OMR:
+  subunit: 3
+  symbol: "﷼"
+  priority: 29
+PAB:
+  subunit: 2
+  symbol: B/.
+  priority: 28
+HRK:
+  subunit: 2
+  symbol: kn
+  priority: 27
+GEL:
+  subunit: 2
+  symbol: "₾"
+  priority: 26
+UYU:
+  subunit: 2
+  symbol: "$U"
+  priority: 25
+AMD:
+  subunit: 2
+  symbol: "֏"
+  priority: 24
+JMD:
+  subunit: 2
+  symbol: J$
+  priority: 23
+QAR:
+  subunit: 2
+  symbol: "﷼"
+  priority: 22
+BWP:
+  subunit: 2
+  symbol: P
+  priority: 21
+MDL:
+  subunit: 2
+  symbol: L
+  priority: 20
+NAD:
+  subunit: 2
+  symbol: N$
+  priority: 19
+LSL:
+  subunit: 2
+  symbol: L
+  priority: 18
+BHD:
+  subunit: 3
+  symbol: ".د.ب"
+  priority: 17
+TTD:
+  subunit: 2
+  symbol: TT$
+  priority: 16
+SZL:
+  subunit: 2
+  symbol: L
+  priority: 15
+FJD:
+  subunit: 2
+  symbol: FJ$
+  priority: 14
+GYD:
+  subunit: 2
+  symbol: G$
+  priority: 13
+SBD:
+  subunit: 2
+  symbol: SI$
+  priority: 12
+SRD:
+  subunit: 2
+  symbol: Sr$
+  priority: 11
+XCD:
+  subunit: 2
+  symbol: EC$
+  priority: 10
+BND:
+  subunit: 2
+  symbol: B$
+  priority: 9
+BSD:
+  subunit: 2
+  symbol: B$
+  priority: 8
+BZD:
+  subunit: 2
+  symbol: BZ$
+  priority: 7
+ISK:
+  subunit: 0
+  symbol: kr
+  priority: 6
+BBD:
+  subunit: 2
+  symbol: Bds$
+  priority: 5
+VUV:
+  subunit: 0
+  symbol: VT
+  priority: 4
+XPF:
+  subunit: 0
+  symbol: "₣"
+  priority: 3
+WST:
+  subunit: 2
+  symbol: WS$
+  priority: 2
+TOP:
+  subunit: 2
+  symbol: T$
+  priority: 1

data/lib/minting/mint/currency.rb

@@ -3,22 +3,21 @@ module Mint
   #
   # @see https://www.iso.org/iso-4217-currency-codes.html
   class Currency
-    attr_reader :code, :subunit, :symbol
+    attr_reader :code, :subunit, :symbol, :priority, :minimum_amount
 
     def inspect
       "<Currency:(#{code} #{symbol} #{subunit})>"
     end
 
-    def minimum_amount
-      @minimum_amount ||= 10r**-subunit
-    end
-
     private
 
-    def initialize(code, subunit:, symbol:)
-      @code = code
-      @subunit = subunit
-      @symbol = symbol
+    def initialize(code, subunit:, symbol:, priority: 0)
+      @code = code.to_s
+      @subunit = subunit.to_i
+      @symbol = symbol.to_s
+      @priority = priority.to_i
+      @minimum_amount = 10r**-subunit
+      freeze
     end
   end
 end

data/lib/minting/mint/registry.rb

@@ -1,11 +1,12 @@
+require 'yaml'
+
 # :nodoc
 module Mint
   def self.money(amount, currency_code)
     currency = currency(currency_code)
     return Money.new(amount, currency) if currency
 
-    available = currencies.keys.join(', ')
-    raise ArgumentError, "Currency [#{currency_code}] not registered. Available: #{available}"
+    raise ArgumentError, "Currency [#{currency_code}] not registered. Check Mint.currencies"
   end
 
   def self.currency(currency)
@@ -19,12 +20,13 @@ module Mint
     end
   end
 
-  def self.register_currency(code, subunit: 2, symbol: '$')
+  def self.register_currency(code, subunit: 2, symbol: '$', priority: 0)
     code = code.to_s
-    currencies[code] || register_currency!(code, subunit: subunit, symbol: symbol)
+    currencies[code] || register_currency!(code, subunit: subunit, symbol: symbol,
+                                                 priority: priority)
   end
 
-  def self.register_currency!(code, subunit:, symbol: '')
+  def self.register_currency!(code, subunit:, symbol: '', priority: 0)
     code = code.to_s
     unless code.match?(/^[A-Z_]+$/)
       raise ArgumentError,
@@ -36,141 +38,36 @@ module Mint
     end
 
     currencies[code] =
-      Currency.new(code, subunit: subunit.to_i, symbol: symbol.to_s).freeze
+      Currency.new(code, subunit: subunit, symbol: symbol, priority: priority)
+    @currency_symbols = nil
+    currencies[code]
   end
 
   def self.currencies
-    @currencies ||= {
-      # Major Global Currencies
-      'USD' => Currency.new('USD', subunit: 2, symbol: '$'),
-      'EUR' => Currency.new('EUR', subunit: 2, symbol: '€'),
-      'GBP' => Currency.new('GBP', subunit: 2, symbol: '£'),
-      'JPY' => Currency.new('JPY', subunit: 0, symbol: '¥'),
-      'CHF' => Currency.new('CHF', subunit: 2, symbol: 'Fr'),
-      'CAD' => Currency.new('CAD', subunit: 2, symbol: '$'),
-      'AUD' => Currency.new('AUD', subunit: 2, symbol: '$'),
-      'CNY' => Currency.new('CNY', subunit: 2, symbol: '¥'),
-      'SEK' => Currency.new('SEK', subunit: 2, symbol: 'kr'),
-      'NZD' => Currency.new('NZD', subunit: 2, symbol: '$'),
-
-      # Asia-Pacific
-      'HKD' => Currency.new('HKD', subunit: 2, symbol: 'HK$'),
-      'SGD' => Currency.new('SGD', subunit: 2, symbol: 'S$'),
-      'KRW' => Currency.new('KRW', subunit: 0, symbol: '₩'),
-      'INR' => Currency.new('INR', subunit: 2, symbol: '₹'),
-      'THB' => Currency.new('THB', subunit: 2, symbol: '฿'),
-      'MYR' => Currency.new('MYR', subunit: 2, symbol: 'RM'),
-      'IDR' => Currency.new('IDR', subunit: 2, symbol: 'Rp'),
-      'PHP' => Currency.new('PHP', subunit: 2, symbol: '₱'),
-      'VND' => Currency.new('VND', subunit: 0, symbol: '₫'),
-      'TWD' => Currency.new('TWD', subunit: 2, symbol: 'NT$'),
-      'PKR' => Currency.new('PKR', subunit: 2, symbol: '₨'),
-      'BDT' => Currency.new('BDT', subunit: 2, symbol: '৳'),
-      'LKR' => Currency.new('LKR', subunit: 2, symbol: '₨'),
-      'NPR' => Currency.new('NPR', subunit: 2, symbol: '₨'),
-      'MMK' => Currency.new('MMK', subunit: 2, symbol: 'K'),
-      'KHR' => Currency.new('KHR', subunit: 2, symbol: '៛'),
-      'LAK' => Currency.new('LAK', subunit: 2, symbol: '₭'),
-      'BND' => Currency.new('BND', subunit: 2, symbol: 'B$'),
-
-      # Middle East & Central Asia
-      'AED' => Currency.new('AED', subunit: 2, symbol: 'د.إ'),
-      'SAR' => Currency.new('SAR', subunit: 2, symbol: '﷼'),
-      'QAR' => Currency.new('QAR', subunit: 2, symbol: '﷼'),
-      'KWD' => Currency.new('KWD', subunit: 3, symbol: 'د.ك'),
-      'BHD' => Currency.new('BHD', subunit: 3, symbol: '.د.ب'),
-      'OMR' => Currency.new('OMR', subunit: 3, symbol: '﷼'),
-      'JOD' => Currency.new('JOD', subunit: 3, symbol: 'د.ا'),
-      'ILS' => Currency.new('ILS', subunit: 2, symbol: '₪'),
-      'TRY' => Currency.new('TRY', subunit: 2, symbol: '₺'),
-      'IRR' => Currency.new('IRR', subunit: 2, symbol: '﷼'),
-      'IQD' => Currency.new('IQD', subunit: 3, symbol: 'د.ع'),
-      'AFN' => Currency.new('AFN', subunit: 2, symbol: '؋'),
-      'KZT' => Currency.new('KZT', subunit: 2, symbol: '₸'),
-      'UZS' => Currency.new('UZS', subunit: 2, symbol: 'лв'),
-      'KGS' => Currency.new('KGS', subunit: 2, symbol: 'лв'),
-      'TJS' => Currency.new('TJS', subunit: 2, symbol: 'SM'),
-
-      # Europe
-      'NOK' => Currency.new('NOK', subunit: 2, symbol: 'kr'),
-      'DKK' => Currency.new('DKK', subunit: 2, symbol: 'kr'),
-      'ISK' => Currency.new('ISK', subunit: 0, symbol: 'kr'),
-      'PLN' => Currency.new('PLN', subunit: 2, symbol: 'zł'),
-      'CZK' => Currency.new('CZK', subunit: 2, symbol: 'Kč'),
-      'HUF' => Currency.new('HUF', subunit: 2, symbol: 'Ft'),
-      'RON' => Currency.new('RON', subunit: 2, symbol: 'lei'),
-      'BGN' => Currency.new('BGN', subunit: 2, symbol: 'лв'),
-      'HRK' => Currency.new('HRK', subunit: 2, symbol: 'kn'),
-      'RSD' => Currency.new('RSD', subunit: 2, symbol: 'Дин.'),
-      'RUB' => Currency.new('RUB', subunit: 2, symbol: '₽'),
-      'UAH' => Currency.new('UAH', subunit: 2, symbol: '₴'),
-      'BYN' => Currency.new('BYN', subunit: 2, symbol: 'Br'),
-      'MDL' => Currency.new('MDL', subunit: 2, symbol: 'L'),
-      'GEL' => Currency.new('GEL', subunit: 2, symbol: '₾'),
-      'AMD' => Currency.new('AMD', subunit: 2, symbol: '֏'),
-      'AZN' => Currency.new('AZN', subunit: 2, symbol: '₼'),
-
-      # Africa
-      'ZAR' => Currency.new('ZAR', subunit: 2, symbol: 'R'),
-      'EGP' => Currency.new('EGP', subunit: 2, symbol: '£'),
-      'NGN' => Currency.new('NGN', subunit: 2, symbol: '₦'),
-      'KES' => Currency.new('KES', subunit: 2, symbol: 'KSh'),
-      'GHS' => Currency.new('GHS', subunit: 2, symbol: '¢'),
-      'UGX' => Currency.new('UGX', subunit: 0, symbol: 'USh'),
-      'TZS' => Currency.new('TZS', subunit: 2, symbol: 'TSh'),
-      'ETB' => Currency.new('ETB', subunit: 2, symbol: 'Br'),
-      'MAD' => Currency.new('MAD', subunit: 2, symbol: 'د.م.'),
-      'TND' => Currency.new('TND', subunit: 3, symbol: 'د.ت'),
-      'DZD' => Currency.new('DZD', subunit: 2, symbol: 'د.ج'),
-      'LYD' => Currency.new('LYD', subunit: 3, symbol: 'ل.د'),
-      'AOA' => Currency.new('AOA', subunit: 2, symbol: 'Kz'),
-      'BWP' => Currency.new('BWP', subunit: 2, symbol: 'P'),
-      'NAD' => Currency.new('NAD', subunit: 2, symbol: 'N$'),
-      'SZL' => Currency.new('SZL', subunit: 2, symbol: 'L'),
-      'LSL' => Currency.new('LSL', subunit: 2, symbol: 'L'),
-      'MZN' => Currency.new('MZN', subunit: 2, symbol: 'MT'),
-      'ZMW' => Currency.new('ZMW', subunit: 2, symbol: 'ZK'),
-      'MWK' => Currency.new('MWK', subunit: 2, symbol: 'MK'),
-      'RWF' => Currency.new('RWF', subunit: 0, symbol: 'R₣'),
-      'BIF' => Currency.new('BIF', subunit: 0, symbol: 'FBu'),
+    @currencies ||= load_currencies
+  end
 
-      # Americas
-      'MXN' => Currency.new('MXN', subunit: 2, symbol: '$'),
-      'BRL' => Currency.new('BRL', subunit: 2, symbol: 'R$'),
-      'ARS' => Currency.new('ARS', subunit: 2, symbol: '$'),
-      'CLP' => Currency.new('CLP', subunit: 0, symbol: '$'),
-      'PEN' => Currency.new('PEN', subunit: 2, symbol: 'S/.'),
-      'COP' => Currency.new('COP', subunit: 2, symbol: '$'),
-      'VES' => Currency.new('VES', subunit: 2, symbol: 'Bs.'),
-      'UYU' => Currency.new('UYU', subunit: 2, symbol: '$U'),
-      'PYG' => Currency.new('PYG', subunit: 0, symbol: 'Gs'),
-      'BOB' => Currency.new('BOB', subunit: 2, symbol: '$b'),
-      'CRC' => Currency.new('CRC', subunit: 2, symbol: '₡'),
-      'GTQ' => Currency.new('GTQ', subunit: 2, symbol: 'Q'),
-      'HNL' => Currency.new('HNL', subunit: 2, symbol: 'L'),
-      'NIO' => Currency.new('NIO', subunit: 2, symbol: 'C$'),
-      'PAB' => Currency.new('PAB', subunit: 2, symbol: 'B/.'),
-      'DOP' => Currency.new('DOP', subunit: 2, symbol: 'RD$'),
-      'HTG' => Currency.new('HTG', subunit: 2, symbol: 'G'),
-      'JMD' => Currency.new('JMD', subunit: 2, symbol: 'J$'),
-      'TTD' => Currency.new('TTD', subunit: 2, symbol: 'TT$'),
-      'BBD' => Currency.new('BBD', subunit: 2, symbol: 'Bds$'),
-      'BSD' => Currency.new('BSD', subunit: 2, symbol: 'B$'),
-      'BZD' => Currency.new('BZD', subunit: 2, symbol: 'BZ$'),
-      'GYD' => Currency.new('GYD', subunit: 2, symbol: 'G$'),
-      'SRD' => Currency.new('SRD', subunit: 2, symbol: 'Sr$'),
+  # Registered symbols sorted for detection: longest match wins, then parser priority.
+  def self.currency_symbols
+    @currency_symbols ||= begin
+      currencies.values
+                .map { |currency| [currency.symbol, currency] }
+                .reject { |symbol, _| symbol.empty? }
+                .sort_by { |symbol, currency| [-symbol.length, -currency.priority] }
+    end.freeze
+  end
 
-      # Pacific & Others
-      'FJD' => Currency.new('FJD', subunit: 2, symbol: 'FJ$'),
-      'PGK' => Currency.new('PGK', subunit: 2, symbol: 'K'),
-      'SBD' => Currency.new('SBD', subunit: 2, symbol: 'SI$'),
-      'VUV' => Currency.new('VUV', subunit: 0, symbol: 'VT'),
-      'TOP' => Currency.new('TOP', subunit: 2, symbol: 'T$'),
-      'WST' => Currency.new('WST', subunit: 2, symbol: 'WS$'),
-      'XCD' => Currency.new('XCD', subunit: 2, symbol: 'EC$'),
-      'XOF' => Currency.new('XOF', subunit: 0, symbol: 'CFA'),
-      'XAF' => Currency.new('XAF', subunit: 0, symbol: 'FCFA'),
-      'XPF' => Currency.new('XPF', subunit: 0, symbol: '₣')
-    }
+  def self.load_currencies
+    path = File.expand_path('../data/currencies.yaml', __dir__)
+    YAML.load_file(path).each_with_object({}) do |(code, attrs), registry|
+      registry[code] = Currency.new(
+        code,
+        subunit: attrs['subunit'],
+        symbol: attrs['symbol'],
+        priority: attrs['priority']
+      )
+    end
   end
+
+  private_class_method :load_currencies
 end

data/lib/minting/money/allocation.rb

@@ -3,10 +3,11 @@ module Mint
   # split and allocation methods
   class Money
     def allocate(proportions)
+      whole = proportions.sum.to_r
       raise ArgumentError, 'Need at least 1 proportion element' if proportions.empty?
+      raise ArgumentError, 'Proportions total must not be zero' if whole.zero?
 
-      whole = proportions.sum.to_r
-      amounts = proportions.map! { |rate| (amount * rate.to_r / whole).round(currency.subunit) }
+      amounts = proportions.map { |rate| (amount * rate.to_r / whole).round(currency.subunit) }
       allocate_left_over!(amounts: amounts, left_over: amount - amounts.sum)
     end
 
@@ -29,7 +30,7 @@ module Mint
         last_slot = (left_over / minimum).to_i - 1
         (0..last_slot).each { |slot| amounts[slot] += minimum }
       end
-      amounts.map { mint(it) }
+      amounts.map { mint it }
     end
   end
 end

data/lib/minting/money/comparable.rb

@@ -13,12 +13,12 @@ module Mint
     end
 
     # @example
-    #   two_usd == Mint.money(2r, 'USD']) #=> [$ 2.00]
-    #   two_usd > 0                       #=> true
-    #   two_usd > Mint.money(2, 'USD'])  #=> true
+    #   two_usd == Mint.money(2r, 'USD') #=> [$ 2.00]
+    #   two_usd > 0                      #=> true
+    #   two_usd > Mint.money(2, 'USD')   #=> false
     #   two_usd > 1
     #   => TypeError: [$ 2.00] can't be compared to 1
-    #   two_usd > Mint.money(2, 'BRL'])
+    #   two_usd > Mint.money(2, 'BRL')
     #   => TypeError: [$ 2.00] can't be compared to [R$ 2.00]
     #
     def <=>(other)

data/lib/minting/money/conversion.rb

@@ -1,7 +1,11 @@
+require 'erb'
+
 module Mint
   # Conversion logic
   class Money
     def to_d
+      raise NoMethodError, 'decimal gem required' unless defined?(BigDecimal)
+
       amount.to_d 0
     end
 
@@ -11,7 +15,8 @@ module Mint
 
     def to_html(format = DEFAULT_FORMAT)
       title = Kernel.format("#{currency_code} %0.#{currency.subunit}f", amount)
-      %(<data class='money' title='#{title}'>#{to_s(format: format)}</data>)
+      body = to_s(format: format)
+      %(<data class='money' title='#{ERB::Util.html_escape(title)}'>#{ERB::Util.html_escape(body)}</data>)
     end
 
     def to_i
@@ -29,18 +34,5 @@ module Mint
     def to_r
       amount
     end
-
-    def to_s(format: '%<symbol>s%<amount>f', delimiter: false, separator: '.')
-      format = format.gsub(/%<amount>(\+?\d*)f/,
-                           "%<amount>\\1.#{currency.subunit}f")
-      formatted = Kernel.format(format, amount: amount, currency: currency_code,
-                                        symbol: currency.symbol)
-      if delimiter
-        # Thanks Money gem for the regular expression
-        formatted.gsub!(/(\d)(?=(?:\d{3})+(?:[^\d]{1}|$))/, "\\1#{delimiter}")
-      end
-      formatted.tr!('.', separator) if separator != '.'
-      formatted
-    end
   end
 end

data/lib/minting/money/formatting.rb

@@ -0,0 +1,68 @@
+module Mint
+  # Formatting functionality for Money objects
+  class Money
+    # Formats money as a string with customizable format, thousand delimiter, and decimal
+    #
+    # @param format [String] Format string with placeholders: %<symbol>s, %<amount>f, %<currency>s
+    # @param thousand [String, false] Thousands delimiter (e.g., ',' for 1,000)
+    # @param decimal [String] Decimal separator (e.g., '.' or ',')
+    # @return [String] Formatted money string
+    #
+    # @example Basic formatting
+    #   money = Mint.money(1234.56, 'USD')
+    #   money.to_s                               #=> "$1,234.56"
+    #   money.to_s(thousand: '.', decimal: ',')  #=> "$.1234,56"
+    #   money.to_s(decimal: ',', thousand: '')   #=> "$1234,56"
+    #
+    # @example Custom formats
+    #   money.to_s(format: '%<amount>f')                    #=> "1234.56"
+    #   money.to_s(format: '%<currency>s %<amount>f')       #=> "USD 1234.56"
+    #   money.to_s(format: '%<amount>f %<symbol>s')         #=> "1234.56 $"
+    #   money.to_s(format: '%<symbol>s%<amount>+f')         #=> "$+1234.56"
+    #
+    # @example Padding and alignment
+    #   money.to_s(format: '%<amount>10.2f')                #=> "   1234.56"
+    #   money.to_s(format: '%<symbol>s%<amount>010.2f')     #=> "$0001234.56"
+    #
+    def to_s(format: '%<symbol>s%<amount>f', decimal: '.', thousand: ',', width: nil)
+      raise ArgumentError, 'Invalid format' unless format.is_a?(String) || format.is_a?(Hash)
+
+      formatted = format_amount(format)
+
+      formatted.tr!('.', decimal) if decimal != '.'
+
+      unless thousand.empty?
+        # Regular expression courtesy of Money gem
+        # Matches digits followed by groups of 3 digits until non-digit or end
+        formatted.gsub!(/(\d)(?=(?:\d{3})+(?:[^\d]{1}|$))/, "\\1#{thousand}")
+      end
+
+      formatted = formatted.rjust(width) if width
+      formatted
+    end
+
+    def format_amount(format)
+      format = { positive: format } if format.is_a?(String)
+      value = amount
+
+      if amount.negative? && format[:negative]
+        format = format[:negative]
+        value = -amount
+      elsif amount.zero? && format[:zero]
+        format = format[:zero]
+      else
+        format = format[:positive]
+      end
+      format ||= '%<symbol>s%<amount>f'
+
+      # Automatically adjust decimal places based on currency subunit
+      adjusted_format = format.gsub(/%<amount>(\+?\d*)f/,
+                                    "%<amount>\\1.#{currency.subunit}f")
+
+      Kernel.format(adjusted_format,
+                    amount: value,
+                    currency: currency_code,
+                    symbol: currency.symbol)
+    end
+  end
+end

data/lib/minting/money/money.rb

@@ -18,6 +18,7 @@ module Mint
 
       @amount = amount.to_r.round(currency.subunit)
       @currency = currency
+      freeze
     end
 
     def currency_code
@@ -25,7 +26,7 @@ module Mint
     end
 
     def hash
-      @hash ||= zero? ? 0.hash : [amount, currency.code].hash
+      zero? ? 0.hash : [amount, currency.code].hash
     end
 
     # Returns a new Money object with the specified amount, or self if unchanged

data/lib/minting/money/parse.rb

@@ -0,0 +1,82 @@
+module Mint
+  # nodoc
+  class Money
+    # Parses a human-readable money string into a {Money} object.
+    #
+    # @param input [String] Amount input, optionally including a currency symbol or code
+    # @param currency [String, Symbol, Currency, nil] ISO code when not present in +input+
+    # @return [Money]
+    # @raise [ArgumentError] when +input+ is invalid or currency cannot be determined
+    #
+    # @example With explicit currency
+    #   Money.parse('19.99', 'USD')    #=> [USD 19.99]
+    #   Money.parse('1.234,56', 'EUR') #=> [EUR 1234.56]
+    #
+    # @example With symbol or code in the string
+    #   Money.parse('$19.99')            #=> [USD 19.99]
+    #   Money.parse('19,99 €')         #=> [EUR 19.99]
+    #   Money.parse('USD 1,234.56')    #=> [USD 1234.56]
+    def self.parse(input, currency = nil)
+      raise ArgumentError, 'input must be a String' unless input.is_a?(String)
+
+      input = input.strip
+      raise ArgumentError, 'input cannot be empty' if input.empty?
+
+      currency = currency ? Mint.currency(currency) : parse_currency(input)
+      raise ArgumentError, "Currency [#{currency}] not registered" unless currency
+
+      amount = parse_amount(input)
+      new(amount, currency)
+    end
+
+    # Extracts a numeric value from input that should only contain an amount.
+    def self.parse_amount(input)
+      # Remove any charater that is not a digit, comma or period
+      numeric = input.scan(/[\d.\-,]/).join
+      numeric = normalize_separators(numeric)
+      Rational(numeric)
+    end
+
+    # Converts locale-specific decimal/thousand separators into a plain decimal string.
+    def self.normalize_separators(numeric)
+      case [numeric.count(','), numeric.count('.')]
+      in [0, 0] | [0, 1] # Nothing to normalize (e.g. "1500" or "34.21").
+        numeric
+      in [1, 0] # Only one comma: decimal (e.g. 19,99 or 1,234).
+        numeric.tr(',', '.')
+      in [c, p] if c > 1 && p > 1 # Both separators appear multiple times
+        raise ArgumentError, "could not distinguish decimal and thousand separators in '#{numeric}'"
+      in [c, p] if c > 0 && p > 0 # Commas and dots: the rightmost one is the decimal separator.
+        if numeric.rindex(',') > numeric.rindex('.')
+          numeric.delete('.').tr(',', '.')
+        else
+          numeric.delete(',')
+        end
+      else # Multiple of the same separator only (e.g. 1,234,567) — all are thousands.
+        numeric.delete(',.')
+      end
+    end
+
+    def self.parse_currency(input)
+      # Prefer an explicit ISO 4217 code (e.g. "USD 1,234.56") over symbol matching.
+      code = input[/\b([A-Z]{3})\b/, 1]
+      if code
+        currency = Mint.currency(code)
+        return currency if currency
+      end
+
+      # Fall back to registered symbols, longest first (HK$ before $).
+      Mint.currency_symbols.each do |symbol, currency|
+        next if symbol.empty?
+
+        return currency if input.include?(symbol)
+      end
+
+      raise ArgumentError,
+            'currency could not be detected; pass a currency code as the second argument'
+    end
+
+    private_class_method :parse_amount, :normalize_separators,
+                         :parse_currency
+  end
+end

data/lib/minting/money.rb

@@ -1,6 +1,8 @@
+require 'minting/money/parse'
 require 'minting/money/allocation'
 require 'minting/money/arithmetics'
 require 'minting/money/coercion'
 require 'minting/money/comparable'
 require 'minting/money/conversion'
+require 'minting/money/formatting'
 require 'minting/money/money'

data/lib/minting/version.rb

@@ -1,3 +1,3 @@
 module Minting
-  VERSION = '1.0.0'.freeze
+  VERSION = '1.1.0'.freeze
 end

data/minting.gemspec

@@ -29,7 +29,7 @@ Gem::Specification.new do |s|
   s.required_ruby_version = '>= 3.2.0'
 
   s.files = Dir.glob('{bin,doc,lib}/**/*')
-  s.files += %w[minting.gemspec Rakefile README.md]
+  s.files += %w[minting.gemspec Rakefile README.md LICENSE]
 
   s.bindir        = 'bin'
   s.require_paths = ['lib']

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: minting
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Gilson Ferraz
@@ -15,11 +15,13 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
 - README.md
 - Rakefile
 - bin/console
 - bin/setup
 - lib/minting.rb
+- lib/minting/data/currencies.yaml
 - lib/minting/mint.rb
 - lib/minting/mint/currency.rb
 - lib/minting/mint/refinements.rb
@@ -30,7 +32,9 @@ files:
 - lib/minting/money/coercion.rb
 - lib/minting/money/comparable.rb
 - lib/minting/money/conversion.rb
+- lib/minting/money/formatting.rb
 - lib/minting/money/money.rb
+- lib/minting/money/parse.rb
 - lib/minting/version.rb
 - minting.gemspec
 homepage: https://github.com/gferraz/minting
@@ -57,7 +61,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.1
+rubygems_version: 4.0.9
 specification_version: 4
 summary: Library to manipulate currency values
 test_files: []