minting 1.0.1 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e2e9f992fc49846276b49db3b06639ed38a2037dceb3762ffac27d1bc03b4d37
-  data.tar.gz: 12fdb933a6cd61b2fa2dc61455ac3932f71fdd7822dd04261d5b0b8ec0fa4ba8
+  metadata.gz: ef2574a0bffcbccb882faba1a839ef37369e047b23becf1ce405d2c1b883322a
+  data.tar.gz: 19ec197c01ceb083a2f6dcf2c6898b38f80ba7679749154b74b3d9fb2f2ffeda
 SHA512:
-  metadata.gz: 3013fca2971566d9503f2375aa1330f191e3467cdd2c442d92a83cd5b493e2778a7ef97dfc6248166af9be4002990a31eb2cbd3df38dcd1508407e12829d2515
-  data.tar.gz: ff7261f4c1fd93586833feb391fd8c95c90a1c1de7f6d5410a4ba406d40f4fcb536684e01ecbd725c87a1c9ef53caa29371a17bf05a6fc7d65320f5c255bb39b
+  metadata.gz: e8680da52ba5417cbe89f2c36615247fa1cc7302088c7d087aa782b6d1958bcd124a38f2b1027cd164810f9f04b02974cf8ac68cb61047d204c9189bf1943a6d
+  data.tar.gz: e85e786f6cb1f98b10e75742097651013e9fe57ddad4896a70fd85b836709e2eecfe26d0f0854b05423f931b1b5fc17b46dfa63c0e25f1a86ffa024de3748d05

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

@@ -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`.
+
+**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` 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/Rakefile

@@ -1,8 +1,9 @@
 require 'bundler/gem_tasks'
 require 'rubocop/rake_task'
 require 'rake/testtask'
+require 'yard'
 
-CLOBBER.include %w[tmp]
+CLOBBER.include %w[doc tmp .yardoc]
 
 Rake::TestTask.new(:test) do |t|
   t.libs << 'test'
@@ -39,4 +40,10 @@ task 'bench:all' => ['bench', 'bench:performance']
 
 RuboCop::RakeTask.new(:cop)
 
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb'] # optional
+  t.options = [] # optional
+  t.stats_options = ['--list-undoc'] # optional
+end
+
 task default: :test