exchange_rates 0.1.0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in exchange_rates.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Jakub Hampl
+
+MIT License
+
+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

@@ -0,0 +1,75 @@
+# ExchangeRates
+
+ExchangeRates is a Ruby Gem that allows currency conversion between a number of currencies and allows a historical overview of the currencies. It takes its information from the [European Central Banks historical feed](
+http://www.ecb.europa.eu/stats/eurofxref/eurofxref-hist-90d.xml).
+
+A demo application can be seen running at http://exchange.herokuapp.com and the source code is [available here](https://github.com/gampleman/exchange_rates_demo).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'exchange_rates'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install exchange_rates
+
+## Usage
+
+The first task that the programmer must use is to obtain the data source. The library assumes it will be in `./exchange-rates.xml`, however the path can be set via the environment variable `EXCHANGE_RATE_FILE`, which should point to the exchange rate file. This file can be downloaded from the [ECB website](http://www.ecb.europa.eu/stats/eurofxref/eurofxref-hist-90d.xml). 
+
+You can add this to your crontab to automatically download the updated files (where MY_PROJECT_PATH is an absolute path to your project). 
+
+    @daily curl -o MY_PROJECT_PATH/exchange-rates.xml http://www.ecb.europa.eu/stats/eurofxref/eurofxref-hist-90d.xml >/dev/null 2>&1
+
+Finally if you have a different datasource, you can simply parse it and call `ExchangeRates.set_rates(data, base_currency)`, where `data` will be your currency data organized by date and `base_currency` will be the currency code to which your rates are relative to. For example:
+
+    ExchangeRates.set_rates({
+       Date::civil(2013, 11, 21) => {
+        'EUR' => 0.9472,  # means 1 USD = 0.9472 EUR on the 21st Oct 2013
+        'JPY' => 135.83,
+        'BGN' => 1.9558,
+        'CZK' => 27.197
+      },
+      Date::civil(2013, 11, 20) => {
+        'EUR' => 0.9527,
+        'JPY' => 135.2,
+        'BGN' => 1.9558,
+        'CZK' => 27.329
+      }
+    }, 'USD')
+
+Then there are three methods you can call:
+
+#### at
+
+`ExchangeRates.at(date, from_currency, to_currency)` returns the exchange rate from `from_currency` to `to_currency` on the date `date`. Given the data above, the call `ExchangeRates.at(Date::civil(2013, 11, 20), 'JPY', 'CZK')` would return `0.202137574`.
+
+The method throws exceptions if asked about missing dates/currencies.
+
+#### convert
+
+`ExchangeRates.convert(amount, opts)` converts an amount of money between currencies. The options for this method are:
+
+`:from` - from currency, defaults to base_currency (see above, for the default data this is EUR)  
+`:to`   - to currency, defaults to base_currency  
+`:date` - date at which to perform conversion, defaults to current date
+
+#### over_time
+
+`ExchangeRates.over_time(from, to)` gives a hash of all known dates and the exchange rate between `from` and `to`.
+
+Again given the above data, calling `ExchangeRates.over_time('JPY', 'CZK')` gives `{Date::civil(2013, 11, 21) => 0.200228226, Date::civil(2013, 11, 20) => 0.202137574}`.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/exchange_rates.gemspec

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/exchange_rates/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Jakub Hampl"]
+  gem.email         = ["honitom@seznam.cz"]
+  gem.description   = %q{exchange_rates is a gem that allows currency conversion and rate history tracking.}
+  gem.summary       = %q{Gives historical exchange rates}
+  gem.homepage      = "https://github.com/gampleman/exchange_rates"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "exchange_rates"
+  gem.require_paths = ["lib"]
+  gem.version       = ExchangeRates::VERSION
+  
+  gem.add_dependency "nokogiri"
+  gem.add_development_dependency "rspec"
+  gem.add_development_dependency "rake"
+end

data/lib/exchange_rates.rb

@@ -0,0 +1,87 @@
+require "exchange_rates/version"
+require "nokogiri"
+
+# Exchange Rates is responsible for parsing a locally available XML file 
+# listing ratios between the base_currency and target currencies. All currencies should
+# be provided as strings with their 3 letter code.
+class ExchangeRates
+  # ExchangeRates.at gives an exchange rate between two currencies at a particular
+  # date. Raises exceptions if the dates are out of range of the file or if the 
+  # currencies are unknown.
+  def self.at(date, from, to)
+    parse_rates
+    if rates = @@rates[date]
+      unless from_rate = rates[from]
+        if from == 'EUR'
+          from_rate = 1.0
+        else
+          raise "Unknown 'from' currency"
+        end
+      end
+      unless to_rate = rates[to]
+        if to == 'EUR'
+          to_rate = 1.0
+        else
+          raise "Unknown 'to' currency"
+        end
+      end
+      to_rate / from_rate
+    else
+      raise "Date out of known dates."
+    end  
+  end
+  
+  # Converts an amount of money between currencies. The options for this method are:
+  #
+  #    from - from currency, defaults to base_currency (typically EUR)
+  #    to   - to currency, defaults to  base_currency (typically EUR)
+  #    date - date at which to perform conversion, defaults to current date
+  def self.convert(amount, opts = {})
+    options = {from: @@base_currency, to: @@base_currency, date: Date.today}.merge(opts)
+    amount.to_f * at(options[:date], options[:from], options[:to])
+  end
+  
+  # Calculates exchange rates between two currencies over all available dates.
+  def self.over_time(from, to)
+    parse_rates
+    results = {}
+    @@rates.each do |date, rates|
+      results[date] = self.at(date, from, to)
+    end
+    results
+  end
+  
+  # Reads and parses the XML data feed providing the underlying data source.
+  # The data source is currently assumed to be in the format of the European 
+  # Central Bank feed accesible at <http://www.ecb.europa.eu/stats/eurofxref/eurofxref­hist­90d.xml>
+  # which provides a 90 day history of exchange rates. It is assumed that this
+  # file is saved locally, best through a cron tab (see README).
+  # If a different source is to be used, call the `set_rates` method.
+  def self.parse_rates
+    @@rates ||= nil
+    return @@rates if @@rates
+    @@base_currency = 'EUR'
+    rate_file = ENV['EXCHANGE_RATE_FILE'] || './exchange-rates.xml'
+    doc = Nokogiri::XML(File.read(rate_file))
+    @@rates = {}
+    doc.css('Cube>Cube[time]').each do |day|
+      time = Date.parse day.attr('time')
+      @@rates[time] = {}
+      day.css('Cube').each{ |c| 
+        @@rates[time][c.attr('currency')] = c.attr('rate').to_f
+      }
+    end
+    @@rates
+  end
+  
+  # Set custom rates data. The data should be a hash of hashes, where the keys in the
+  # outer hash are Date objects and the keys in the inner hashes are three letter currency
+  # codes. The values are floats showing the exchange rate between a currency and the base
+  # currency. This second argument should be the base currency to which all values are relative
+  # to.
+  def self.set_rates(rates, base = 'EUR')
+    @@rates = rates
+    @@base_currency = base
+  end
+  
+end

data/lib/exchange_rates/version.rb

@@ -0,0 +1,3 @@
+class ExchangeRates
+  VERSION = "0.1.0"
+end

data/spec/exchange_rates_spec.rb

@@ -0,0 +1,59 @@
+require "exchange_rates"
+
+describe ExchangeRates do
+  
+  before(:all) do
+    File.open('/tmp/currencies.xml', 'w') {|file| file.write(SAMPLE_XML)}
+    ENV['EXCHANGE_RATE_FILE'] = '/tmp/currencies.xml'
+  end
+  
+  it "parses the XML data format correctly" do
+    ExchangeRates.parse_rates.should eq(SAMPLE_DATA)
+  end
+  
+  it "should get correct to EUR rates" do
+    ExchangeRates.at(DATE1, 'CZK', 'EUR').should eq(1.0/27.197)
+  end
+  
+  it "should get correct from EUR rates" do
+    ExchangeRates.at(DATE1, 'EUR', 'CZK').should eq(27.197)
+  end
+  
+  it "should get correct cross rates" do
+    ExchangeRates.at(DATE1, 'JPY', 'BGN').should eq(1.9558/135.83)
+  end
+  
+  it "should raise exceptions when out of range" do
+    expect{ ExchangeRates.at(Date::civil(2012, 11, 21), 'JPY', 'BGN') }.to raise_error
+  end
+  
+  it "should convert currencies accurately" do 
+    ExchangeRates.convert(123, date: DATE1, from: 'CZK').should eq(123.0/27.197)
+  end
+  
+  it "should spread data over time" do
+    ExchangeRates.over_time('EUR', 'CZK').should eq({Date::civil(2013, 11, 20) => 27.329, DATE1 => 27.197})
+  end  
+end
+
+
+DATE1 = Date::civil(2013, 11, 21)
+
+SAMPLE_XML = '<?xml version="1.0" encoding="UTF-8"?><gesmes:Envelope xmlns:gesmes="http://www.gesmes.org/xml/2002-08-01" xmlns="http://www.ecb.int/vocabulary/2002-08-01/eurofxref"><gesmes:subject>Reference rates</gesmes:subject><gesmes:Sender><gesmes:name>European Central Bank</gesmes:name></gesmes:Sender><Cube><Cube time="2013-11-21"><Cube currency="USD" rate="1.3472"/><Cube currency="JPY" rate="135.83"/><Cube currency="BGN" rate="1.9558"/><Cube currency="CZK" rate="27.197"/></Cube>
+<Cube time="2013-11-20"><Cube currency="USD" rate="1.3527"/><Cube currency="JPY" rate="135.2"/><Cube currency="BGN" rate="1.9558"/><Cube currency="CZK" rate="27.329"/></Cube>
+</Cube></gesmes:Envelope>'
+
+SAMPLE_DATA = {
+   DATE1 => {
+    'USD' => 1.3472,
+    'JPY' => 135.83,
+    'BGN' => 1.9558,
+    'CZK' => 27.197
+  },
+  Date::civil(2013, 11, 20) => {
+    'USD' => 1.3527,
+    'JPY' => 135.2,
+    'BGN' => 1.9558,
+    'CZK' => 27.329
+  }
+}

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification
+name: exchange_rates
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Jakub Hampl
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-11-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: exchange_rates is a gem that allows currency conversion and rate history
+  tracking.
+email:
+- honitom@seznam.cz
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- exchange_rates.gemspec
+- lib/exchange_rates.rb
+- lib/exchange_rates/version.rb
+- spec/exchange_rates_spec.rb
+homepage: https://github.com/gampleman/exchange_rates
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 2857346963252068634
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 2857346963252068634
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Gives historical exchange rates
+test_files:
+- spec/exchange_rates_spec.rb