exchange 0.2.6

data/lib/exchange/external_api.rb

@@ -0,0 +1,4 @@
+require 'exchange/external_api/base'
+require 'exchange/external_api/call'
+require 'exchange/external_api/currency_bot'
+require 'exchange/external_api/xavier_media'

data/lib/exchange/external_api/base.rb

@@ -0,0 +1,114 @@
+module Exchange
+  # The external API module. Every class Handling an API has to be placed here and inherit from base. It has to call an api and define
+  # a rates hash, an exchange base and a unix timestamp. The call will get cached automatically with the right structure
+  # Allows for easy extension with an own api, as shown below
+  # @author Beat Richartz
+  # @version 0.1
+  # @since 0.1
+  # @example Easily connect to your custom API by writing an ExternalAPI Class
+  #   module Exchange
+  #     module ExternalAPI
+  #       class MyCustom < Base
+  #         # Define here which currencies your API can handle
+  #         CURRENCIES = %W(usd chf)
+  #         
+  #         # Every instance of ExternalAPI Class has to have an update function which gets the rates from the API
+  #         def update(opts={})
+  #           # assure that you will get a Time object for the historical dates
+  #           time = assure_time(opts[:at]) 
+  #
+  #           # call your API (shown here with a helper function that builds your API URL). Like this, your calls will get cached.
+  #           Call.new(api_url(time), :at => time) do |result|
+  #
+  #             # assign the currency conversion base, attention, this is readonly, so don't do self.base = 
+  #             @base                 = result['base']
+  #
+  #             # assign the rates, this has to be a hash with the following format: {'USD' => 1.23242, 'CHF' => 1.34323}. Attention, this is readonly.
+  #             @rates                = result['rates']
+  #
+  #             # timestamp the api call result. This may come in handy to assure you have the right result. Attention, this is readonly.
+  #             @timestamp            = result['timestamp'].to_i
+  #           end
+  #         end
+  #         
+  #         private
+  #
+  #           def api_url(time)
+  #             # code a helper function that builds your api url for the specified time
+  #           end
+  #
+  #       end
+  #     end
+  #   end
+  #   # Now, you can configure your API in the configuration. The Symbol will get camelcased and constantized
+  #   Exchange::Configuration.api = :my_custom
+  #   # Have fun, and don't forget to write tests.
+  
+  module ExternalAPI
+    
+    # The Base class of all External APIs, handling basic exchange rates and conversion
+    # @author Beat Richartz
+    # @version 0.1
+    # @since 0.1
+    
+    class Base
+      # @attr_reader
+      # @return [String] The currency which was the base for the rates
+      attr_reader :base
+      
+      # @attr_reader
+      # @return [Integer] A unix timestamp for the rates, delivered by the API
+      attr_reader :timestamp
+      
+      # @attr_reader
+      # @return [Hash] A Hash which delivers the exchange rate of every available currency to the base currency
+      attr_reader :rates
+      
+      
+      # Delivers an exchange rate from one currency to another with the option of getting a historical exchange rate. This rate
+      # has to be multiplied with the amount of the currency which you define in from
+      # @param [String, Symbol] from The currency which should be converted
+      # @param [String, Symbol] to The currency which the should be converted to
+      # @param [Hash] opts The options to throw at the rate
+      # @option opts [Time] :at Define a Time here to get a historical rate
+      # @return [Float] The exchange rate for those two currencies
+      # @example Get the exchange rate for a conversion from USD to EUR at March 23 2009
+      #   Exchange::ExternalAPI::Base.new.rate(:usd, :eur, :at => Time.gm(3,23,2009))
+      #     #=> 1.232231231
+      def rate(from, to, opts={})
+        update(opts)
+        self.rates[to.to_s.upcase] / self.rates[from.to_s.upcase]
+      end
+      
+      # Converts an amount of one currency into another
+      # @param [Fixed, Float] amount The amount of the currency to be converted
+      # @param [String, Symbol] from The currency to be converted from
+      # @param [String, Symbol] to The currency which should be converted to
+      # @param [Hash] opts Options to throw at the conversion
+      # @option opts [Time] :at Define a Time here to convert at a historical rate
+      # @return [Float] The amount in the currency converted to, rounded to two decimals
+      # @example Convert 23 EUR to CHF at the rate of December 1 2011
+      #   Exchange::ExternalAPI::Base.new.convert(23, :eur, :chf, :at => Time.gm(12,1,2011))
+      #     #=> 30.12
+      def convert(amount, from, to, opts={})
+        (amount.to_f * rate(from, to, opts) * 100).round.to_f / 100
+      end
+      
+      protected
+      
+        # A helper function to assure a value is an instance of time
+        # @param [Time, String, NilClass] The value to be asserted
+        # @param [Hash] opts Options for assertion
+        # @option opts [Symbol] :default If the argument is nil, you can define :default as :now to be delivered with Time.now instead of nil
+        
+        def assure_time(arg=nil, opts={})
+          if arg
+            arg.kind_of?(Time) ? arg : Time.gm(*arg.split('-'))
+          elsif opts[:default] == :now
+            Time.now
+          end
+        end
+        
+    end
+  end
+end

data/lib/exchange/external_api/call.rb

@@ -0,0 +1,76 @@
+module Exchange
+  module ExternalAPI
+    
+    # A class to handle API calls in a standardized way for all APIs
+    # @author Beat Richartz
+    # @version 0.1
+    # @since 0.1
+    
+    class Call
+      
+      # Initialization of the Call class is the call itself. This means that every instance of the class will only exist during the call
+      # @param [String] url The url of the API to call
+      # @param [Hash] options The options of the API call
+      # @option options [Time] :at The time of the historical exchange rate file to get
+      # @option options [Integer] :retries The number of retries if the API Call should fail with a HTTP Error
+      # @option options [Array] :retry_with an Array of urls to retry the call with (if the API does not have a file for the specified date). These values will be shifted until a call succeeds or the number of maximum retries is reached.
+      # @option options [Symbol] :format The format to return / yield the API call result in, defaults to :json
+      # @yield [Nokogiri::XML, Hash] The result of the API call, either nokogiri parsed XML or a hash loaded from JSON
+      # @return [Nokogiri::XML, Hash] Returns the result of the API call if no block is given, either nokogiri parsed XML or a hash loaded from JSON
+      # @example Call an API an yield the result
+      #   Exchange::ExternalAPI::Call.new('http://yourapiurl.com', :format => :xml) do |result|
+      #     # Do something with the result here, for example
+      #     rates = {}
+      #     result.css('rates').each do |rate|
+      #       rates.merge! rate.css('currency').children.to_s => rate.css('rate').children.to_s.to_f
+      #     end
+      #   end
+      # @example Call the API and do something with the result
+      #   result = Exchange::ExternalAPI::Call.new('http://yourapiurl.com', :format => :xml)
+      #   # Do something with that result
+      
+      def initialize url, options={}, &block
+        if Exchange::Configuration.cache
+          result = Exchange::Configuration.cache_class.cached(Exchange::Configuration.api_class, :at => options[:at]) do
+            load_url(url, options[:retries] || 5, options[:retry_with])
+          end
+        else
+          result = load_url(url, options[:retries] || 5, options[:retry_with])
+        end
+        
+        parsed = options[:format] == :xml ? Nokogiri.parse(result) : JSON.load(result)
+        
+        return parsed unless block_given?
+
+        yield parsed
+      end
+      
+      private
+      
+        # A helper function to load the API URL with
+        # @param [String] url The url to be loaded
+        # @param [Integer] retries The number of retries to do if the API Call should fail with a HTTP Error
+        # @param [Array] retry_with An array of urls to retry the API call with if the call to the original URL should fail. These values will be shifted until a call succeeds or the number of maximum retries is reached
+      
+        def load_url(url, retries, retry_with)
+          begin
+            result = URI.parse(url).open.read
+          rescue SocketError
+            raise APIError.new("Calling API #{url} produced a socket error")
+          rescue OpenURI::HTTPError
+            if retries > 0
+              retries -= 1
+              url = retry_with.shift if retry_with && !retry_with.empty?
+              retry
+            else
+              raise APIError.new("API #{url} was not reachable")
+            end
+          end
+        end
+      
+    end
+    
+    # The Api Error to throw when an API Call fails
+    APIError = Class.new(StandardError)
+  end
+end

data/lib/exchange/external_api/currency_bot.rb

@@ -0,0 +1,47 @@
+module Exchange
+  module ExternalAPI
+    # The Currency Bot API class, handling communication with the Open Source Currency bot API
+    # You can find further information on the currency bot API here: http://currencybot.github.com/
+    # @author Beat Richartz
+    # @version 0.1
+    # @since 0.1
+    
+    class CurrencyBot < Base
+      # The base of the Currency Bot exchange API
+      API_URL              = 'https://raw.github.com/currencybot/open-exchange-rates/master'
+      # The currencies the Currency Bot API can convert
+      CURRENCIES           = %W(xcd usd sar rub nio lak nok omr amd cdf kpw cny kes zwd khr pln mvr gtq clp inr bzd myr hkd sek cop dkk byr lyd ron dzd bif ars gip bob xof std ngn pgk aed mwk cup gmd zwl tzs cve btn xaf ugx syp mad mnt lsl top shp rsd htg mga mzn lvl fkp bwp hnl eur egp chf ils pyg lbp ang kzt wst gyd thb npr kmf irr uyu srd jpy brl szl mop bmd xpf etb jod idr mdl mro yer bam awg nzd pen vef try sll aoa tnd tjs sgd scr lkr mxn ltl huf djf bsd gnf isk vuv sdg gel fjd dop xdr mur php mmk krw lrd bbd zmk zar vnd uah tmt iqd bgn gbp kgs ttd hrk rwf clf bhd uzs twd crc aud mkd pkr afn nad bdt azn czk sos iep pab qar svc sbd all jmd bnd cad kwd ghs)
+      
+      # Updates the rates by getting the information from Currency Bot for today or a defined historical date
+      # The call gets cached for a maximum of 24 hours.
+      # @param [Hash] opts Options to define for the API Call
+      # @option opts [Time, String] :at a historical date to get the exchange rates for
+      # @example Update the currency bot API to use the file of March 2, 2010
+      #   Exchange::ExternalAPI::CurrencyBot.new.update(:at => Time.gm(3,2,2010))
+      
+      def update(opts={})
+        time = assure_time(opts[:at])
+        
+        Call.new(api_url(time), :at => time) do |result|
+          @base                 = result['base']
+          @rates                = result['rates']
+          @timestamp            = result['timestamp'].to_i
+        end
+      end
+            
+      private
+      
+        # A helper function to build an api url for either a specific time or the latest available rates
+        # @param [Time] time The time to build the api url for
+        # @return [String] an api url for the time specified
+        # @since 0.1
+        # @version 0.2.6
+      
+        def api_url(time=nil)
+          today = Time.now
+          [API_URL, time && (time.year != today.year || time.yday != today.yday) ? "historical/#{time.strftime("%Y-%m-%d")}.json" : 'latest.json'].join('/')
+        end
+        
+    end
+  end
+end

data/lib/exchange/external_api/xavier_media.rb

@@ -0,0 +1,47 @@
+module Exchange
+  module ExternalAPI
+    
+    # The XavierMedia API class, handling communication with the Xavier Media Currency API
+    # You can find further information on the Xaviermedia API here: http://www.xavierforum.com/viewtopic.php?f=5&t=10979&sid=671a685edbfa5dbec219fbc6793d5057
+    # @author Beat Richartz
+    # @version 0.1
+    # @since 0.1
+    
+    class XavierMedia < Base
+      # The base of the Xaviermedia API URL
+      API_URL              = "http://api.finance.xaviermedia.com/api"
+      # The currencies the Xaviermedia API URL can handle
+      CURRENCIES           = %W(eur usd jpy gbp cyp czk dkk eek huf ltl mtl pln sek sit skk chf isk nok bgn hrk rol ron rub trl aud cad cny hkd idr krw myr nzd php sgd thb zar)
+      
+      # Updates the rates by getting the information from Xaviermedia API for today or a defined historical date
+      # The call gets cached for a maximum of 24 hours.
+      # @param [Hash] opts Options to define for the API Call
+      # @option opts [Time, String] :at a historical date to get the exchange rates for
+      # @example Update the currency bot API to use the file of March 2, 2010
+      #   Exchange::ExternalAPI::XavierMedia.new.update(:at => Time.gm(3,2,2010))
+      
+      def update(opts={})
+        time       = assure_time(opts[:at], :default => :now)
+        api_url    = api_url(time)
+        retry_urls = [api_url(time - 86400), api_url(time - 172800), api_url(time - 259200)]
+        
+        Call.new(api_url, :format => :xml, :at => time, :retry_with => retry_urls) do |result|
+          @base                 = result.css('basecurrency').children[0].to_s
+          @rates                = Hash[*result.css('fx currency_code').children.map(&:to_s).zip(result.css('fx rate').children.map{|c| c.to_s.to_f }).flatten]
+          @timestamp            = Time.gm(*result.css('fx_date').children[0].to_s.split('-')).to_i
+        end
+      end
+      
+      private
+      
+        # A helper function which build a valid api url for the specified time
+        # @param [Time] time The exchange rate date for which the URL should be built
+        # @return [String] An Xaviermedia API URL for the specified time
+      
+        def api_url(time)
+          [API_URL, "#{time.strftime("%Y/%m/%d")}.xml"].join('/')
+        end
+        
+    end
+  end
+end

data/spec/core_extensions/conversability_spec.rb

@@ -0,0 +1,64 @@
+require 'spec_helper'
+
+describe "Exchange::Conversability" do
+  before(:all) do
+    Exchange::Configuration.cache = false
+  end
+  after(:all) do
+    Exchange::Configuration.cache = :memcached
+  end
+  context "with a fixnum" do
+    it "should allow to convert to a currency" do
+      3.eur.should be_kind_of Exchange::Currency
+      3.eur.value.should == 3
+    end
+    it "should allow to convert to a curreny with a negative number" do
+      -3.eur.should be_kind_of Exchange::Currency
+      -3.eur.value.should == -3
+    end
+    it "should allow to do full conversions" do
+      mock_api("https://raw.github.com/currencybot/open-exchange-rates/master/latest.json", fixture('api_responses/example_json_api.json'), 3)
+      3.eur.to_chf.should be_kind_of Exchange::Currency
+      3.eur.to_chf.value.should == 3.62
+      3.eur.to_chf.currency.should == 'chf'
+    end
+    it "should allow to do full conversions with negative numbers" do
+      mock_api("https://raw.github.com/currencybot/open-exchange-rates/master/latest.json", fixture('api_responses/example_json_api.json'), 3)
+      -3.eur.to_chf.should be_kind_of Exchange::Currency
+      -3.eur.to_chf.value.should == -3.62
+      -3.eur.to_chf.currency.should == 'chf'
+    end
+    it "should allow to define a historic time in which the currency should be interpreted" do
+      3.chf(:at => Time.gm(2010,1,1)).time.yday.should == 1
+      3.chf(:at => Time.gm(2010,1,1)).time.year.should == 2010
+      3.chf(:at => '2010-01-01').time.year.should == 2010
+    end
+  end
+  context "with a float" do
+    it "should allow to convert to a currency" do
+      3.25.eur.should be_kind_of Exchange::Currency
+      3.25.eur.value.should == 3.25
+    end
+    it "should allow to convert to a curreny with a negative number" do
+      -3.25.eur.should be_kind_of Exchange::Currency
+      -3.25.eur.value.should == -3.25
+    end
+    it "should allow to do full conversions" do
+      mock_api("https://raw.github.com/currencybot/open-exchange-rates/master/latest.json", fixture('api_responses/example_json_api.json'), 3)
+      3.25.eur.to_chf.should be_kind_of Exchange::Currency
+      3.25.eur.to_chf.value.should == 3.92
+      3.25.eur.to_chf.currency.should == 'chf'
+    end
+    it "should allow to do full conversions with negative numbers" do
+      mock_api("https://raw.github.com/currencybot/open-exchange-rates/master/latest.json", fixture('api_responses/example_json_api.json'), 3)
+      -3.25.eur.to_chf.should be_kind_of Exchange::Currency
+      -3.25.eur.to_chf.value.should == -3.92
+      -3.25.eur.to_chf.currency.should == 'chf'
+    end
+    it "should allow to define a historic time in which the currency should be interpreted" do
+      3.25.chf(:at => Time.gm(2010,1,1)).time.yday.should == 1
+      3.25.chf(:at => Time.gm(2010,1,1)).time.year.should == 2010
+      3.25.chf(:at => '2010-01-01').time.year.should == 2010
+    end
+  end
+end

data/spec/exchange/cache/base_spec.rb

@@ -0,0 +1,29 @@
+require 'spec_helper'
+
+describe "Exchange::Cache::Base" do
+  subject { Exchange::Cache::Base }
+  describe "key generation" do
+    before(:each) do
+      time = Time.gm 2012, 03, 01, 23, 23, 23
+      Time.stub! :now => time
+    end
+    context "with a daily cache" do
+      it "should build a timestamped key with the class given, the yearday and the year" do
+        Exchange::Cache::Base.send(:key, Exchange::ExternalAPI::XavierMedia).should == 'Exchange_ExternalAPI_XavierMedia_2012_61'
+        Exchange::Cache::Base.send(:key, Exchange::ExternalAPI::CurrencyBot).should == 'Exchange_ExternalAPI_CurrencyBot_2012_61'
+      end
+    end
+    context "with an hourly cache" do
+      before(:each) do
+        Exchange::Configuration.update = :hourly
+      end
+      after(:each) do
+        Exchange::Configuration.update = :daily
+      end
+      it "should build a timestamped key with the class given, the yearday, the year and the hour" do
+        Exchange::Cache::Base.send(:key, Exchange::ExternalAPI::XavierMedia).should == 'Exchange_ExternalAPI_XavierMedia_2012_61_23'
+        Exchange::Cache::Base.send(:key, Exchange::ExternalAPI::CurrencyBot).should == 'Exchange_ExternalAPI_CurrencyBot_2012_61_23'
+      end
+    end
+  end
+end

data/spec/exchange/cache/memcached_spec.rb

@@ -0,0 +1,72 @@
+require 'spec_helper'
+
+describe "Exchange::Cache::Memcached" do
+  subject { Exchange::Cache::Memcached }
+  before(:each) do
+    Exchange::Configuration.define do |c|
+      c.cache_host = 'HOST'
+      c.cache_port = 'PORT'
+    end
+  end
+  after(:each) do
+    Exchange::Configuration.define do |c|
+      c.cache_host = 'localhost'
+      c.cache_port = 11211
+    end
+  end
+  describe "client" do
+    let(:client) { mock('memcached') }
+    after(:each) do
+      subject.send(:remove_class_variable, "@@client")
+    end
+    it "should set up a client on the specified host and port for the cache" do
+      ::Memcached.should_receive(:new).with("HOST:PORT").and_return(client)
+      subject.client.should == client
+    end
+  end
+  describe "cached" do
+    context "when a cached result exists" do
+      let(:client) { mock('memcached') }
+      before(:each) do
+        subject.should_receive(:key).with('API_CLASS', nil).and_return('KEY')
+        ::Memcached.should_receive(:new).with("HOST:PORT").and_return(client)
+        client.should_receive(:get).with('KEY').and_return "{\"RESULT\":\"YAY\"}"
+      end
+      after(:each) do
+        subject.send(:remove_class_variable, "@@client")
+      end
+      it "should return the JSON loaded result" do
+        subject.cached('API_CLASS') { 'something' }.should == {'RESULT' => 'YAY'}
+      end
+    end
+    context "when no cached result exists" do
+      let(:client) { mock('memcached') }
+      before(:each) do
+        subject.should_receive(:key).with('API_CLASS', nil).twice.and_return('KEY')
+        ::Memcached.should_receive(:new).with("HOST:PORT").and_return(client)
+        client.should_receive(:get).with('KEY').and_raise(::Memcached::NotFound)
+      end
+      after(:each) do
+        subject.send(:remove_class_variable, "@@client")
+      end
+      context "with daily cache" do
+        it "should call the block and set and return the result" do
+          client.should_receive(:set).with('KEY', "{\"RESULT\":\"YAY\"}", 86400).once
+          subject.cached('API_CLASS') { {'RESULT' => 'YAY'} }.should == {'RESULT' => 'YAY'}
+        end
+      end
+      context "with hourly cache" do
+        before(:each) do
+          Exchange::Configuration.update = :hourly
+        end
+        after(:each) do
+          Exchange::Configuration.update = :daily
+        end
+        it "should call the block and set and return the result" do
+          client.should_receive(:set).with('KEY', "{\"RESULT\":\"YAY\"}", 3600).once
+          subject.cached('API_CLASS') { {'RESULT' => 'YAY'} }.should == {'RESULT' => 'YAY'}
+        end
+      end
+    end
+  end
+end