ECB Exchange¶ ↑
Currency conversion using the European Central Bank's foreign exchange rates. Rates for the last 90 days are fetched and cached on demand. All calculations are performed and returned as BigDecimal
(usually a good idea when dealing with money).
Requirements¶ ↑
-
Ruby >= 2.3
Installation¶ ↑
Add this line to your Gemfile and run bundle install
:
gem 'ecb_exchange'
Usage¶ ↑
Convert an amount from one currency to another:
ECB::Exchange.convert(100, from: 'EUR', to: 'GBP') => 0.88235e2
The converted amount (using today's current rate) will be returned as BigDecimal
. In doing this, the gem will fetch and cache ECB rates for the last 90 days.
Convert an amount on a specific date:
ECB::Exchange.convert(100, from: 'EUR', to: 'GBP', date: Date.parse('2017-01-11')) => 0.87235e2
To fetch the exchange rate multiplier between two currencies:
ECB::Exchange.rate(from: 'EUR', to: 'USD') # pass an optional `date` arg here too => 0.11969e1
You can ask for an array of all supported currencies with:
ECB::Exchange.currencies => ["USD", "JPY", "BGN", "CZK", "DKK", "GBP", "HUF" ... ]
Finally, you can adjust the rates endpoint by setting your own XMLFeed.endpoint
(e.g. in an initializer):
ECB::Exchange::XMLFeed.endpoint = "http://my-awesome-service.com/feed.xml"
The XML feed at this endpoint must conform to the ECB rates structure.
Handling Errors¶ ↑
Not all dates, rates or currencies may be available, or the remote endpoint could be unresponsive. For these cases consider handling these errors:
-
ECB::Exchange::DateNotFoundError
-
ECB::Exchange::CurrencyNotFoundError
-
ECB::Exchange::ResponseError
-
ECB::Exchange::ParseError
Or rescue ECB::Exchange::Error
to catch any of them.
Caching¶ ↑
By default rates will be cached to one of the following backend stores (in this order of preference).
-
Your own backend cache store (see below)
-
Rails.cache
-
An
ECB::Exchange::MemoryCache
instance (a simple in memory cache store)
To configure your own backend store (e.g. in an initializer):
ECB::Exchange::Cache.backend = MyAwesomeCache.new # this cache must implement public `read(key)` and `write(key, value)` methods
All keys in the cache are name-spaced with a ecb_exchange_rates_for_date-
prefix.
Development¶ ↑
Check out this repo and run bin/setup
, this will install gem dependencies and generate docs. Use bundle exec rake
to run tests and generate a coverage report.
You can also run bin/console
for an interactive prompt to experiment with the code.
Tests¶ ↑
MiniTest is used for testing. Run the test suite with:
$ rake test
Docs¶ ↑
Generate docs for this gem with:
$ rake rdoc
Troubles?¶ ↑
If you think something is broken or missing, please raise a new issue. Please remember to check it hasn't already been raised.
Contributing¶ ↑
Bug reports and pull requests are welcome on GitHub. When submitting pull requests, remember to add tests covering any new behaviour, and ensure all tests are passing on Travis. Read the contributing guidelines for more details.
This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct. See here for more details.
Todo¶ ↑
-
Better RDoc documentation.
-
A Rails app to demo this gem (e.g. with a one-click Heroku install).
License¶ ↑
The code is available as open source under the terms of LGPL-3.