danconia 0.2.2 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 38d88815b5c3c9155db3c64433d6469614656a2464ab6a0c0eae51b3429b084d
-  data.tar.gz: d8962d50c98a68e8acfbc2a1424e81b77b1d506d069d4e87c0fa32803482d2b0
+  metadata.gz: 0ebf1db97ca89c6a822b12279f873193c97d7e9f412aa0054967cf02e1d3f74d
+  data.tar.gz: da1e807e1d5e0c4ec0619f8d93a7a023c4e8361c4b48a3f16b138c4013122fed
 SHA512:
-  metadata.gz: 69fa03e8ae6c01a37eaafaf9fe358b1e57eca34bd4e1113fb795002b80d4f5dc2a3934c06f1b3102a3c64e3403e16f3d6fd97c9f301b819f9de6b742c3ea088d
-  data.tar.gz: 4881c55540c4b0e51e6018a23aae7923effc31ea9694295aae07a08a62fa60b32d6943adea8bd3798d5349b6f15c97ab2948f6410593c6d03ceb35c136e12c9b
+  metadata.gz: 1836de03b18616b074b76028d6ff6cf392e8148e294d80783a918836c9d75eb78aa2f6df666302a5d68435362f90091f3690daa7ca1c08bf1fa746bd4b0171ab
+  data.tar.gz: bc00add76fb57dd0b30ddc8c0a2c4ba5790335bc4f4ad5dd4e29c73b2445fe5b3cec06edd8df2dd5eec4b9abcadc158196f2cb8a146807dcb43a6952b67f5c68

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    danconia (0.2.2)
+    danconia (0.2.3)
       activerecord (>= 3.0.0)
 
 GEM

data/README.md

@@ -1,26 +1,69 @@
 # Danconia
 
-TODO: Write a gem description
+A very simple money library for Ruby, backed by BigDecimal (no conversion to cents, i.e. "infinite precision") with support for external exchange rates services.
 
 [![Build Status](https://travis-ci.org/eeng/danconia.svg?branch=master)](https://travis-ci.org/eeng/danconia)
 
 ## Installation
 
-Add this line to your application's Gemfile:
+```ruby
+gem 'danconia'
+```
 
-    gem 'danconia'
+## Basic Usage
 
-And then execute:
+If you only need to work with a single currency:
 
-    $ bundle
+```ruby
+# USD by default, but can be configured
+m1 = Money(10.25) # => 10.25 USD
 
-Or install it yourself as:
+# Note that we keep all decimal places
+m2 = m1 / 2 # => 5.125 USD
 
-    $ gem install danconia
+# Simple formatting by default
+puts m2 # => $5.13
+```
 
-## Usage
+Please refer to `examples/single_currency.rb` for some configuration options.
 
-TODO: Write usage instructions here
+## Multi-Currency Support
+
+To handle multiple currencies you need to configure an `Exchange` in order to fetch the rates. For example, with [CurrencyLayer](https://currencylayer.com/):
+
+```ruby
+# This can be placed in a Rails initializer
+Danconia.configure do |config|
+  config.default_exchange = Danconia::Exchanges::CurrencyLayer.new(access_key: '...')
+end
+```
+
+Then, download the exchange rates:
+```ruby
+# You should do this periodically to keep rates up to date
+Danconia.config.default_exchange.update_rates!
+```
+
+And finally to convert between currencies:
+```ruby
+Money(9, 'JPY').exchange_to('ARS') # => 2.272401 ARS
+```
+
+By default, rates are stored in memory, but you can supply a store in the exchange constructor to save them elsewhere. Please refer to `examples/currency_layer.rb` for an ActiveRecord example.
+
+## Active Record Integration
+
+Given a `products` table with a decimal column `price` and a string column `price_currency` (optional), then you can use the `money` class method to automatically convert it to Money:
+
+```ruby
+class Product < ActiveRecord::Base
+  money :price
+end
+
+Product.new(price: 30, price_currency: 'ARS').price # => 30 ARS
+```
+
+Currently, there is no option to customize the names of the columns but should be fairly simple to implement if needed.
 
 ## Contributing
 

data/danconia.gemspec

@@ -6,11 +6,12 @@ require 'danconia/version'
 Gem::Specification.new do |gem|
   gem.name          = "danconia"
   gem.version       = Danconia::VERSION
-  gem.authors       = ["Emmanuel Nicolau"]
-  gem.email         = ["emmanicolau@gmail.com"]
+  gem.author        = "Emmanuel Nicolau"
+  gem.email         = "emmanicolau@gmail.com"
   gem.description   = %q{Multi-currency money library backed by BigDecimal}
   gem.summary       = %q{Multi-currency money library backed by BigDecimal}
-  gem.homepage      = ""
+  gem.homepage      = "https://github.com/eeng/danconia"
+  gem.license       = "MIT"
 
   gem.files         = `git ls-files`.split($/)
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }

data/examples/currency_layer.rb

@@ -1,8 +1,10 @@
+# Remember to supply your CurrencyLayer key in the ACCESS_KEY environment variable to run this example
 require 'danconia'
 
 ActiveRecord::Base.establish_connection adapter: 'sqlite3', database: ':memory:'
 
 ActiveRecord::Schema.define do
+  # You can use this in a Rails migration
   create_table :exchange_rates do |t|
     t.string :pair, limit: 6
     t.decimal :rate, precision: 12, scale: 6
@@ -11,10 +13,13 @@ ActiveRecord::Schema.define do
 end
 
 Danconia.configure do |config|
-  config.default_exchange = Danconia::Exchanges::CurrencyLayer.new(access_key: ENV['ACCESS_KEY'], store: Danconia::Stores::ActiveRecord.new)
+  config.default_exchange = Danconia::Exchanges::CurrencyLayer.new(
+    access_key: ENV['ACCESS_KEY'],
+    store: Danconia::Stores::ActiveRecord.new
+  )
 end
 
-# Periodically do this
+# Periodically call this method to keep rates up to date
 puts 'Updating dates with CurrencyLayer API...'
 Danconia.config.default_exchange.update_rates!
 

data/examples/single_currency.rb

@@ -0,0 +1,14 @@
+require 'danconia'
+
+# USD is the default currency if no configuration is provided
+puts (Money(10.25) / 2).inspect # => 5.125 USD
+puts (Money(10.25) / 2).to_s # => $5.13
+
+# Lets switch to other currency
+Danconia.configure do |config|
+  config.default_currency = 'EUR'
+  config.available_currencies = [{code: 'EUR', symbol: '€'}]
+end
+
+puts Money(10.25).inspect # => 10.25 EUR
+puts Money(10.25).to_s # => €10.25

data/lib/danconia/config.rb

@@ -14,11 +14,12 @@ module Danconia
   end
 
   class Config
-    attr_accessor :default_currency, :default_exchange
+    attr_accessor :default_currency, :default_exchange, :available_currencies
 
     def initialize
       @default_currency = 'USD'
       @default_exchange = Exchanges::FixedRates.new
+      @available_currencies = []
     end
   end
 end

data/lib/danconia/currency.rb

@@ -2,7 +2,7 @@ module Danconia
   class Currency < Struct.new(:code, :symbol, :description, keyword_init: true)
     def self.find code, exchange
       return code if code.is_a? Currency
-      new exchange.currencies.find { |c| c[:code] == code } || {code: code, symbol: '$'}
+      new Danconia.config.available_currencies.find { |c| c[:code] == code } || {code: code, symbol: '$'}
     end
   end
 end

data/lib/danconia/exchanges/exchange.rb

@@ -1,11 +1,10 @@
 module Danconia
   module Exchanges
     class Exchange
-      attr_reader :store, :currencies
+      attr_reader :store
 
-      def initialize store: Stores::InMemory.new, currencies: []
+      def initialize store: Stores::InMemory.new
         @store = store
-        @currencies = currencies
       end
 
       def rate from, to

data/lib/danconia/test_helpers.rb

@@ -9,7 +9,7 @@ module Danconia
 
       def with_rates rates
         with_config do |config|
-          config.default_exchange = Exchanges::FixedRates.new rates: rates, currencies: config.default_exchange.currencies
+          config.default_exchange = Exchanges::FixedRates.new rates: rates
           yield
         end
       end

data/lib/danconia/version.rb

@@ -1,3 +1,3 @@
 module Danconia
-  VERSION = '0.2.2'
+  VERSION = '0.2.3'
 end

data/spec/danconia/money_spec.rb

@@ -96,7 +96,7 @@ module Danconia
         expect(Money(3.25).to_s).to eq '$3.25'
 
         TestHelpers.with_config do |config|
-          config.default_exchange = Exchanges::FixedRates.new currencies: [{code: 'EUR', symbol: '€'}, {code: 'JPY', symbol: '¥'}]
+          config.available_currencies = [{code: 'EUR', symbol: '€'}, {code: 'JPY', symbol: '¥'}]
 
           expect(Money(1, 'EUR').to_s).to eq '€1.00'
           expect(Money(1, 'JPY').to_s).to eq '¥1.00'
@@ -168,7 +168,7 @@ module Danconia
     end
 
     def fake_exchange args = {}
-      double 'exchange', args.reverse_merge(rate: nil, currencies: [])
+      double 'exchange', args.reverse_merge(rate: nil)
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: danconia
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.3
 platform: ruby
 authors:
 - Emmanuel Nicolau
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-07-04 00:00:00.000000000 Z
+date: 2018-07-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -109,8 +109,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 description: Multi-currency money library backed by BigDecimal
-email:
-- emmanicolau@gmail.com
+email: emmanicolau@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -128,6 +127,7 @@ files:
 - danconia.gemspec
 - examples/currency_layer.rb
 - examples/fixed_rates.rb
+- examples/single_currency.rb
 - lib/danconia.rb
 - lib/danconia/config.rb
 - lib/danconia/currency.rb
@@ -150,8 +150,9 @@ files:
 - spec/danconia/stores/active_record_spec.rb
 - spec/spec_helper.rb
 - spec/support/database.rb
-homepage: ''
-licenses: []
+homepage: https://github.com/eeng/danconia
+licenses:
+- MIT
 metadata: {}
 post_install_message: 
 rdoc_options: []