exchange 0.6.0 → 0.8.0

data/lib/exchange/external_api/base.rb

@@ -13,23 +13,37 @@ module Exchange
   #         # 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
+  #         # 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 = Exchange::Helper.assure_time(opts[:at]) 
+  #           #
+  #           time = helper.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 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
+  # 
+  #           # Assign the currency conversion base.
+  #           # Attention, this is readonly, self.base= won't work
+  #           #
+  #           @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, self.rates= won't work
+  #           #
+  #           @rates                = result['rates']
+  # 
+  #           # Timestamp the api call result. This may come in handy to assure you have 
+  #           # the right result. 
+  #           #
+  #           # Attention, this is readonly, self.timestamp= won't work
+  #           #
+  #           @timestamp            = result['timestamp'].to_i
   #         end
   #         
   #         private
@@ -41,8 +55,11 @@ module Exchange
   #       end
   #     end
   #   end
+  #
   #   # Now, you can configure your API in the configuration. The Symbol will get camelcased and constantized
+  #   #
   #   Exchange::Configuration.api.subclass = :my_custom
+  #
   #   # Have fun, and don't forget to write tests.
   #
   module ExternalAPI
@@ -69,6 +86,28 @@ module Exchange
       #
       attr_reader :rates
       
+      # @attr_reader
+      # @return [Exchange::Cache] The cache subclass
+      attr_reader :cache
+      
+      # @attr_reader
+      # @return [Exchange::API] The api subclass
+      attr_reader :api
+      
+      # @attr_reader
+      # @return [Exchange::Helper] The Exchange Helper
+      attr_reader :helper
+      
+      # Initialize with a convenience accessor for the Cache and the api subclass
+      # @param [Any] args The args to initialize with
+      #
+      def initialize *args
+        @cache  = Exchange.configuration.cache.subclass
+        @api    = Exchange.configuration.api.subclass
+        @helper = Exchange::Helper.instance
+        
+        super *args
+      end
       
       # 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
@@ -82,13 +121,17 @@ module Exchange
       #     #=> 1.232231231
       #
       def rate(from, to, opts={})
-        rate = Exchange.configuration.cache.subclass.cached(Exchange.configuration.api.subclass, opts.merge(:key_for => [from, to], :plain => true)) do
+        rate = cache.cached(api, opts.merge(:key_for => [from, to], :plain => true)) do
           update(opts)
+          
           rate_from   = self.rates[to.to_s.upcase]
           rate_to     = self.rates[from.to_s.upcase]
-          raise NoRateError.new("No rates where found for #{from} to #{to} #{'at ' + opts[:at].to_s if opts[:at]}") unless rate_from && rate_to
+          
+          test_for_rates_and_raise_if_nil rate_from, rate_to, opts[:at]
+          
           rate_from / rate_to
         end
+        
         BigDecimal.new(rate.to_s)
       end
       
@@ -107,6 +150,23 @@ module Exchange
         amount * rate(from, to, opts)
       end
       
+      # Converts an array to a hash
+      # @param [Array] array The array to convert
+      # @return [Hash] The hash out of the array
+      #
+      def to_hash! array
+        Hash[*array]
+      end
+      
+      # Test for a error to be thrown when no rates are present
+      # @param [String] rate_from The rate from which should be converted
+      # @param [String] rate_to The rate to which should be converted
+      # @param [Time] time The time at which should be converted
+      # @raise [NoRateError] An error indicating that there is no rate present when there is no rate present
+      #
+      def test_for_rates_and_raise_if_nil rate_from, rate_to, time=nil
+        raise NoRateError.new("No rates where found for #{from} to #{to} #{'at ' + time.to_s if time}") unless rate_from && rate_to
+      end
     end
   end
 end

data/lib/exchange/external_api/call.rb

@@ -30,14 +30,16 @@ module Exchange
       #   result = Exchange::ExternalAPI::Call.new('http://yourapiurl.com', :format => :xml)
       #   # Do something with that result
       #
-      def initialize url, options={}, &block
+      def initialize url, options={}, &block        
         Exchange::GemLoader.new('nokogiri').try_load if options[:format] == :xml
         
-        result = Exchange.configuration.cache.subclass.cached(options[:api] || Exchange.configuration.api.subclass, options) do
-          load_url(url, options[:retries] || Exchange.configuration.api.retries, options[:retry_with])
+        api_config = Exchange.configuration.api
+        
+        result = Exchange.configuration.cache.subclass.cached(options[:api] || api_config.subclass, options) do
+          load_url(url, options[:retries] || api_config.retries, options[:retry_with])
         end
         
-        parsed = options[:format] == :xml ? Nokogiri.parse(result) : ::JSON.load(result)
+        parsed = options[:format] == :xml ? Nokogiri::XML.parse(result.sub("\n", '')) : ::JSON.load(result)
         
         return parsed unless block_given?
         yield  parsed
@@ -49,6 +51,7 @@ module Exchange
         # @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
+        # @todo install a timeout for slow requests, but respect when loading large files
         #
         def load_url(url, retries, retry_with)          
           begin            

data/lib/exchange/external_api/currency_bot.rb

@@ -24,17 +24,27 @@ module Exchange
       #   Exchange::ExternalAPI::CurrencyBot.new.update(:at => Time.gm(3,2,2010))
       #
       def update(opts={})
-        time = Exchange::Helper.assure_time(opts[:at])
+        time = helper.assure_time(opts[:at])
         
         Call.new(api_url(time), :at => time) do |result|
           @base                 = result['base']
-          @rates                = Hash[*result['rates'].keys.zip(result['rates'].values.map{|v| BigDecimal.new(v.to_s) }).flatten]
+          @rates                = extract_rates(result)
           @timestamp            = result['timestamp'].to_i
         end
       end
             
       private
       
+        # Helper method to extract rates from the api call result
+        # @param [JSON] parsed The parsed result
+        # @return [Hash] A hash with rates
+        # @since 0.7
+        # @version 0.7
+        #
+        def extract_rates parsed
+          to_hash! parsed['rates'].keys.zip(parsed['rates'].values.map{|v| BigDecimal.new(v.to_s) }).flatten
+        end
+      
         # 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

data/lib/exchange/external_api/ecb.rb

@@ -4,7 +4,7 @@ module Exchange
     # The ECB class, handling communication with the European Central Bank XML File API
     # You can find further information on the European Central Bank XML API API here: http://www.ecb.int/stats/exchange/eurofxref/html/index.en.html
     # @author Beat Richartz
-    # @version 0.3
+    # @version 0.7
     # @since 0.3
     #
     class Ecb < XML
@@ -28,22 +28,23 @@ module Exchange
       # @example Update the ecb API to use the file of March 2, 2010
       #   Exchange::ExternalAPI::Ecb.new.update(:at => Time.gm(3,2,2010))
       #
+      # @since 0.1
+      # @version 0.7
+      #
       def update(opts={})
-        time          = Exchange::Helper.assure_time(opts[:at], :default => :now)
-        times         = Exchange.configuration.api.retries.times.map{ |i| time - 86400 * (i+1) }
+        time          = helper.assure_time(opts[:at], :default => :now)
+        times         = map_retry_times time
         
         # Since the Ecb File retrieved can be very large (> 5MB for the history file) and parsing takes a fair amount of time,
         # caching is doubled on this API
         # 
-        Exchange.configuration.cache.subclass.cached(self.class, :at => time) do
+        cache.cached(self.class, :at => time) do
           Call.new(api_url(time), call_opts(time)) do |result|
             t = time
             
             # Weekends do not have rates present
             #
-            while (r = result.css("Cube[time=\"#{t.strftime("%Y-%m-%d")}\"]")).empty? && !times.empty?
-              t = times.shift
-            end
+            t = times.shift while (r = find_rate!(result, t)).empty? && !times.empty?
             
             @callresult = r.to_s
           end
@@ -52,7 +53,7 @@ module Exchange
         parsed = Nokogiri.parse(self.callresult)
         
         @base                 = 'EUR' # We just have to assume, since it's the ECB
-        @rates                = Hash[*(['EUR', BigDecimal.new("1")] + parsed.children.children.map {|c| c.attributes.values.map{|v| v.value.match(/\d/) ? BigDecimal.new(v.value) : v.value }.sort_by(&:to_s).reverse unless c.attributes.values.empty? }.compact.flatten)]
+        @rates                = extract_rates(parsed.children.children)
         @timestamp            = time.to_i
       end
       
@@ -72,9 +73,62 @@ module Exchange
           ].join('/')
         end
         
+        # A helper method to find rates from the callresult given a certain time
+        # ECB packs the rates in «Cubes», so we try to find the cube appropriate to the time
+        # @param [Nokogiri::XML] parsed The parsed callresult
+        # @param [Time] time The time to parse for
+        # @return [Nokogiri::XML, NilClass] the rate, hopefully
+        # @since 0.7
+        # @version 0.7
+        #
+        def find_rate! parsed, time
+          parsed.css("Cube[time=\"#{time.strftime("%Y-%m-%d")}\"]")
+        end
+        
+        # A helper method to extract rates from the callresult
+        # @param [Nokogiri::XML] parsed the parsed api data
+        # @return [Hash] a hash with rates
+        # @since 0.7
+        # @version 0.7
+        #
+        def extract_rates parsed
+          rate_array = parsed.map { |c| 
+            map_to_currency_or_rate c
+          }.compact.flatten
+          
+          to_hash!(['EUR', BigDecimal.new("1")] + rate_array)
+        end
+        
+        # a helper method to map a key value pair to either currency or rate
+        # @param [Nokogiri::XML] xml a parsed xml part of the document
+        # @return [Array] An array with the following structure [currency, value, currency, value]
+        # @since 0.7
+        # @version 0.7
+        #
+        def map_to_currency_or_rate xml
+          unless (values = xml.attributes.values).empty?
+            values.map { |v|
+              val = v.value
+              val.match(/\d+/) ? BigDecimal.new(val) : val 
+            }.sort_by(&:to_s).reverse 
+          end
+        end
+        
+        # Helper method to map retry times
+        # @param [Time] time The time to start with
+        # @return [Array] An array of times to retry api operation with
+        # @since 0.7
+        # @version 0.7
+        #
+        def map_retry_times time
+          Exchange.configuration.api.retries.times.map{ |i| time - 86400 * (i+1) }
+        end
+        
         # a wrapper for the call options, since the cache period is quite complex
         # @param [Time] time The date of the exchange rate
         # @return [Hash] a hash with the call options
+        # @since 0.6
+        # @version 0.6
         #
         def call_opts time
           {:format => :xml, :at => time, :cache => :file, :cache_period => time >= Time.now - 90 * 86400 ? :daily : :monthly}

data/lib/exchange/external_api/json.rb

@@ -1,22 +1,12 @@
 module Exchange
   module ExternalAPI
     
-    # The json base class takes care of JSON apis. It assumes you would want to use json as a parser and preloads the gem
-    # Also, this may serve as a base for some operations which might be common to the json apis
+    # The json base class takes care of JSON apis. 
+    # This may serve as a base for some operations which might be common to the json apis
     # @author Beat Richartz
     # @version 0.6
     # @since 0.6
     #
-    class JSON < Base
-      
-      # Initializer, essentially takes the arguments passed to initialization, loads the json gem on the way
-      # and passes the arguments to the api base
-      #
-      def initialize *args
-        Exchange::GemLoader.new('json').try_load unless defined?(::JSON)
-        super *args
-      end
-      
-    end
+    JSON = Class.new Base
   end
 end

data/lib/exchange/external_api/xavier_media.rb

@@ -4,7 +4,7 @@ module Exchange
     # 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
+    # @version 0.7
     # @since 0.1
     #
     class XavierMedia < XML
@@ -16,21 +16,20 @@ module Exchange
       
       # 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.
-      # @version 0.3
+      # @version 0.7
       # @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       = Exchange::Helper.assure_time(opts[:at], :default => :now)
+        time       = helper.assure_time(opts[:at], :default => :now)
         api_url    = api_url(time)
-        retry_urls = Exchange.configuration.api.retries.times.map{ |i| api_url(time - 86400 * (i+1)) }
         
-        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| BigDecimal.new(c.to_s) }).flatten]
-          @timestamp            = Time.gm(*result.css('fx_date').children[0].to_s.split('-')).to_i
+        Call.new(api_url, api_opts(opts.merge(:at => time))) do |result|
+          @base                 = extract_base_currency result
+          @rates                = extract_rates result
+          @timestamp            = extract_timestamp result
         end
       end
       
@@ -44,6 +43,50 @@ module Exchange
           [API_URL, "#{time.strftime("%Y/%m/%d")}.xml"].join('/')
         end
         
+        # Options for the API call to make
+        # @param [Hash] opts The options to generate the call options with
+        # @option opts [Time, String] :at a historical date to get the exchange rates for
+        # @return [Hash] The options hash for the API call
+        # @since 0.6
+        # @version 0.6
+        #
+        def api_opts(opts={})
+          retry_urls = Exchange.configuration.api.retries.times.map { |i| api_url(opts[:at] - 86400 * (i+1)) }
+          
+          { :format => :xml, :at => opts[:at], :retry_with => retry_urls }
+        end
+        
+        # Extract a timestamp of the callresult
+        # @param [Nokogiri::XML] result the callresult
+        # @return [Integer] A unix timestamp
+        # @since 0.7
+        # @version 0.7
+        #
+        def extract_timestamp(result)
+          Time.gm(*result.css('fx_date').children[0].to_s.split('-')).to_i
+        end
+        
+        # Extract rates from the callresult
+        # @param [Nokogiri::XML] result the callresult
+        # @return [Hash] A hash with currency / rate pairs
+        # @since 0.7
+        # @version 0.7
+        #
+        def extract_rates(result)
+          rates_array = result.css('fx currency_code').children.map(&:to_s).zip(result.css('fx rate').children.map{|c| BigDecimal.new(c.to_s) }).flatten
+          to_hash!(rates_array)
+        end
+        
+        # Extract the base currency from the callresult
+        # @param [Nokogiri::XML] result the callresult
+        # @return [String] The base currency for the rates
+        # @since 0.7
+        # @version 0.7
+        #
+        def extract_base_currency(result)
+          result.css('basecurrency').children[0].to_s
+        end
+        
     end
   end
 end

data/lib/exchange/helper.rb

@@ -13,7 +13,7 @@ module Exchange
     extend SingleForwardable
     
     # A helper function to assure a value is an instance of time
-    # @param [Time, String, NilClass] The value to be asserted
+    # @param [Time, String, NilClass] arg The value to be asserted
     # @param [Hash] opts Options for assertion
     # @option opts [Symbol] :default a method that can be sent to Time if the argument is nil (:now for example)
     #

data/lib/exchange/iso_4217.rb

@@ -1,5 +1,6 @@
 require 'singleton'
 require 'forwardable'
+require 'yaml'
 
 module Exchange
   

data/spec/exchange/cache/memcached_spec.rb

@@ -68,26 +68,52 @@ describe "Exchange::CacheDalli::Client" do
     end
     context "when no cached result exists" do
       let(:client) { mock('memcached') }
-      before(:each) do
-        subject.should_receive(:key).with('API_CLASS', {}).twice.and_return('KEY')
-        client.should_receive(:get).with('KEY').and_return(nil)
-      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'}
+      context "when returning nil" do
+        before(:each) do
+          subject.should_receive(:key).with('API_CLASS', {}).twice.and_return('KEY')
+          client.should_receive(:get).with('KEY').and_return(nil)
+        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.cache.expire = :hourly
+          end
+          after(:each) do
+            Exchange.configuration.cache.expire = :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
-      context "with hourly cache" do
+      context "when returning an empty string" do
         before(:each) do
-          Exchange.configuration.cache.expire = :hourly
+          subject.should_receive(:key).with('API_CLASS', {}).twice.and_return('KEY')
+          client.should_receive(:get).with('KEY').and_return('')
         end
-        after(:each) do
-          Exchange.configuration.cache.expire = :daily
+        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
-        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'}
+        context "with hourly cache" do
+          before(:each) do
+            Exchange.configuration.cache.expire = :hourly
+          end
+          after(:each) do
+            Exchange.configuration.cache.expire = :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