exchange 0.2.6 → 0.3.0

data/lib/exchange/external_api.rb

@@ -2,3 +2,4 @@ require 'exchange/external_api/base'
 require 'exchange/external_api/call'
 require 'exchange/external_api/currency_bot'
 require 'exchange/external_api/xavier_media'
+require 'exchange/external_api/ecb'

data/lib/exchange/external_api/base.rb

@@ -1,4 +1,5 @@
 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
@@ -15,7 +16,7 @@ module Exchange
   #         # 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]) 
+  #           time = Exchange::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.new(api_url(time), :at => time) do |result|
@@ -76,8 +77,14 @@ module Exchange
       #   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]
+        rate = Configuration.cache_class.cached(Exchange::Configuration.api, opts.merge(:key_for => [from, to])) 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
+          rate_from / rate_to
+        end
+        BigDecimal.new(rate.to_s)
       end
       
       # Converts an amount of one currency into another
@@ -91,23 +98,8 @@ module Exchange
       #   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
+        amount * rate(from, to, opts)
       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

data/lib/exchange/external_api/call.rb

@@ -12,6 +12,7 @@ module Exchange
       # @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 [Class] :api The class to generate the key for
       # @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
@@ -30,19 +31,14 @@ module Exchange
       #   # 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])
+        result = Configuration.cache_class(options).cached(options[:api] || Configuration.api, options) do
+          load_url(url, options[:retries] || Exchange::Configuration.retries, options[:retry_with])
         end
         
         parsed = options[:format] == :xml ? Nokogiri.parse(result) : JSON.load(result)
         
         return parsed unless block_given?
-
-        yield parsed
+        yield  parsed
       end
       
       private
@@ -52,20 +48,22 @@ module Exchange
         # @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
+        def load_url(url, retries, retry_with)          
+          begin            
             result = URI.parse(url).open.read
           rescue SocketError
+            puts 'SocketError'
             raise APIError.new("Calling API #{url} produced a socket error")
-          rescue OpenURI::HTTPError
+          rescue OpenURI::HTTPError => e
+            retries -= 1
             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
+          result          
         end
       
     end

data/lib/exchange/external_api/currency_bot.rb

@@ -20,11 +20,11 @@ module Exchange
       #   Exchange::ExternalAPI::CurrencyBot.new.update(:at => Time.gm(3,2,2010))
       
       def update(opts={})
-        time = assure_time(opts[:at])
+        time = Exchange::Helper.assure_time(opts[:at])
         
         Call.new(api_url(time), :at => time) do |result|
           @base                 = result['base']
-          @rates                = result['rates']
+          @rates                = Hash[*result['rates'].keys.zip(result['rates'].values.map{|v| BigDecimal.new(v.to_s) }).flatten]
           @timestamp            = result['timestamp'].to_i
         end
       end

data/lib/exchange/external_api/ecb.rb

@@ -0,0 +1,68 @@
+module Exchange
+  module ExternalAPI
+    
+    # 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
+    # @since 0.3
+    
+    class ECB < Base
+      # The base of the ECB API URL
+      API_URL              = "http://www.ecb.europa.eu/stats/eurofxref"
+      # The currencies the ECB API URL can handle
+      CURRENCIES           = %W(eur usd jpy bgn czk dkk gbp huf ltl lvl pln ron sek chf nok hrk rub try aud brl cad cny hkd idr ils inr krw mxn myr nzd php sgd thb zar)
+      
+      attr_accessor :callresult
+      
+      # Updates the rates by getting the information from ECB API for today or a defined historical date
+      # The call gets cached for a maximum of 24 hours. Getting history from ECB is a bit special, since they do not seem to have
+      # any smaller portion history than an epic 4MB XML history file and a 90 day recent history file. We get each of that once and cache it in smaller portions.
+      # @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)
+        api_url       = api_url(time)
+        times         = Exchange::Configuration.retries.times.map{ |i| time - 86400 * (i+1) }
+        
+        Kernel.warn "WARNING: Using the ECB API without caching can be very, very slow." unless Configuration.cache
+        
+        Configuration.cache_class.cached(self.class, :at => time) do
+          Call.new(api_url, :format => :xml, :at => time, :cache => :file, :cache_period => time >= Time.now - 90 * 86400 ? :daily : :monthly) do |result|
+            t = time
+            while (r = result.css("Cube[time=\"#{t.strftime("%Y-%m-%d")}\"]")).empty? && !times.empty?
+              t = times.shift
+            end
+            @callresult = r.to_s
+          end
+        end
+
+        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)]
+        @timestamp            = time.to_i
+      end
+      
+      private
+      
+        # A helper function which build a valid api url for the specified time
+        # If the date is today, get the small daily file. If it is less than 90 days ago, get the 90 days file. 
+        # If it is more than 90 days ago, get the big file
+        # @param [Time] time The exchange rate date for which the URL should be built
+        # @return [String] An ECB API URL to get the xml from
+      
+        def api_url(time)
+          border = Time.now - 90 * 86400
+          [
+            API_URL, 
+            border <= time ? 'eurofxref-hist-90d.xml' : 'eurofxref-hist.xml'
+          ].join('/')
+        end
+        
+    end
+  end
+end

data/lib/exchange/external_api/xavier_media.rb

@@ -15,19 +15,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
       # @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)
+        time       = Exchange::Helper.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)]
+        retry_urls = Exchange::Configuration.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| c.to_s.to_f }).flatten]
+          @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
         end
       end

data/lib/exchange/helper.rb

@@ -0,0 +1,27 @@
+module Exchange
+  # Helper Functions that get used throughout the gem can be placed here
+  # @author Beat Richartz
+  # @version 0.3
+  # @since 0.3
+  
+  class Helper
+    class << self
+    
+      # 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 a method that can be sent to Time if the argument is nil (:now for example)
+      
+      def assure_time(arg=nil, opts={})
+        if arg
+          arg.kind_of?(Time) ? arg : Time.gm(*arg.split('-'))
+        elsif opts[:default]
+          Time.send(opts[:default])
+        end
+      end
+    
+    end
+    
+  end
+  
+end

data/lib/exchange/iso_4217.rb

@@ -0,0 +1,95 @@
+module Exchange
+  
+  # This class handles everything that has to do with certified formatting of the different currencies. The standard is stored in 
+  # the iso4217 YAML file.
+  # @version 0.3
+  # @since 0.3
+  # @author Beat Richartz
+  
+  class ISO4217
+    class << self
+      
+      # The ISO 4217 that have to be loaded. Nothing much to say here. Just use this method to get to the definitions
+      # They are static, so they can be stored in a class variable without many worries
+      # @return [Hash] The iso427 Definitions with the currency code as keys
+      
+      def definitions
+        @@definitions ||= YAML.load_file('iso4217.yml')
+      end
+      
+      # Use this to instantiate a currency amount. For one, it is important that we use BigDecimal here so nothing gets lost because
+      # of floating point errors. For the other, This allows us to set the precision exactly according to the iso definition
+      # @param [BigDecimal, Fixed, Float, String] amount The amount of money you want to instantiate
+      # @param [String, Symbol] currency The currency you want to instantiate the money in
+      # @return [BigDecimal] The instantiated currency
+      # @example instantiate a currency from a string
+      #   Exchange::ISO4217.instantiate("4523", "usd") #=> #<Bigdecimal 4523.00>
+      
+      def instantiate(amount, currency)
+        BigDecimal.new(amount.to_s, definitions[currency.to_s.upcase]['minor_unit'])
+      end
+      
+      # Converts the currency to a string in ISO 4217 standardized format, either with or without the currency. This leaves you
+      # with no worries how to display the currency.
+      # @param [BigDecimal, Fixed, Float] amount The amount of currency you want to stringify
+      # @param [String, Symbol] currency The currency you want to stringify
+      # @param [Hash] opts The options for formatting
+      # @option opts [Boolean] :amount_only Whether you want to have the currency in the string or not
+      # @return [String] The formatted string
+      # @example Convert a currency to a string
+      #   Exchange::ISO4217.stringify(49.567, :usd) #=> "USD 49.57"
+      # @example Convert a currency without minor to a string
+      #   Exchange::ISO4217.stringif(45, :jpy) #=> "JPY 45"
+      # @example Convert a currency with a three decimal minor to a string
+      #   Exchange::ISO4217.stringif(34.34, :omr) #=> "OMR 34.340"
+      # @example Convert a currency to a string without the currency
+      #   Exchange::ISO4217.stringif(34.34, :omr, :amount_only => true) #=> "34.340"
+      
+      def stringify(amount, currency, opts={})
+        format      = "%.#{definitions[currency.to_s.upcase]['minor_unit']}f"
+        "#{currency.to_s.upcase + ' ' unless opts[:amount_only]}#{format % amount}"
+      end
+      
+      private
+        # @private
+        # @macro [attach] install_operations
+      
+        def install_operation op      
+          self.class_eval <<-EOV
+            def self.#{op}(amount, currency, precision=nil)
+              minor = definitions[currency.to_s.upcase]['minor_unit']
+              (amount.is_a?(BigDecimal) ? amount : BigDecimal.new(amount.to_s, minor)).#{op}(precision || minor)
+            end
+          EOV
+        end
+    end
+    
+    # Use this to round a currency amount. This allows us to round exactly to the number of minors the currency has in the 
+    # iso definition
+    # @param [BigDecimal, Fixed, Float, String] amount The amount of money you want to round
+    # @param [String, Symbol] currency The currency you want to round the money in
+    # @example Round a currency with 2 minors
+    #   Exchange::ISO4217.round("4523.456", "usd") #=> #<Bigdecimal 4523.46>
+    
+    install_operation :round
+    
+    # Use this to ceil a currency amount. This allows us to ceil exactly to the number of minors the currency has in the 
+    # iso definition
+    # @param [BigDecimal, Fixed, Float, String] amount The amount of money you want to ceil
+    # @param [String, Symbol] currency The currency you want to ceil the money in
+    # @example Ceil a currency with 2 minors
+    #   Exchange::ISO4217.ceil("4523.456", "usd") #=> #<Bigdecimal 4523.46>
+    
+    install_operation :ceil
+    
+    # Use this to floor a currency amount. This allows us to floor exactly to the number of minors the currency has in the 
+    # iso definition
+    # @param [BigDecimal, Fixed, Float, String] amount The amount of money you want to floor
+    # @param [String, Symbol] currency The currency you want to floor the money in
+    # @example Floor a currency with 2 minors
+    #   Exchange::ISO4217.floor("4523.456", "usd") #=> #<Bigdecimal 4523.46>
+    
+    install_operation :floor
+    
+  end
+end

data/spec/core_extensions/conversability_spec.rb

@@ -7,6 +7,13 @@ describe "Exchange::Conversability" do
   after(:all) do
     Exchange::Configuration.cache = :memcached
   end
+  it "should define all currencies on Fixnum, Float and BigDecimal" do
+    Exchange::ISO4217.definitions.keys.each do |c|
+      1.should be_respond_to(c.downcase.to_sym)
+      1.1.should be_respond_to(c.downcase.to_sym)
+      BigDecimal.new("1").should be_respond_to(c.downcase.to_sym)
+    end
+  end
   context "with a fixnum" do
     it "should allow to convert to a currency" do
       3.eur.should be_kind_of Exchange::Currency
@@ -19,13 +26,13 @@ describe "Exchange::Conversability" do
     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.value.round(2).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.value.round(2).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
@@ -37,22 +44,22 @@ describe "Exchange::Conversability" do
   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
+      3.25.eur.value.round(2).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
+      -3.25.eur.value.round(2).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.value.round(2).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.value.round(2).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
@@ -61,4 +68,31 @@ describe "Exchange::Conversability" do
       3.25.chf(:at => '2010-01-01').time.year.should == 2010
     end
   end
+  context "with a big decimal" do
+    it "should allow to convert to a currency" do
+      BigDecimal.new("3.25").eur.should be_kind_of Exchange::Currency
+      BigDecimal.new("3.25").eur.value.round(2).should == 3.25
+    end
+    it "should allow to convert to a curreny with a negative number" do
+      BigDecimal.new("-3.25").eur.should be_kind_of Exchange::Currency
+      BigDecimal.new("-3.25").eur.value.round(2).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)
+      BigDecimal.new("3.25").eur.to_chf.should be_kind_of Exchange::Currency
+      BigDecimal.new("3.25").eur.to_chf.value.round(2).should == 3.92
+      BigDecimal.new("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)
+      BigDecimal.new("-3.25").eur.to_chf.should be_kind_of Exchange::Currency
+      BigDecimal.new("-3.25").eur.to_chf.value.round(2).should == -3.92
+      BigDecimal.new("-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
+      BigDecimal.new("3.25").chf(:at => Time.gm(2010,1,1)).time.yday.should == 1
+      BigDecimal.new("3.25").chf(:at => Time.gm(2010,1,1)).time.year.should == 2010
+      BigDecimal.new("3.25").chf(:at => '2010-01-01').time.year.should == 2010
+    end
+  end
 end

data/spec/exchange/cache/base_spec.rb

@@ -9,8 +9,8 @@ describe "Exchange::Cache::Base" do
     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'
+        Exchange::Cache::Base.send(:key, :xavier_media).should == 'exchange_xavier_media_2012_61'
+        Exchange::Cache::Base.send(:key, :currency_bot).should == 'exchange_currency_bot_2012_61'
       end
     end
     context "with an hourly cache" do
@@ -21,8 +21,8 @@ describe "Exchange::Cache::Base" 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'
+        Exchange::Cache::Base.send(:key, :xavier_media).should == 'exchange_xavier_media_2012_61_23'
+        Exchange::Cache::Base.send(:key, :currency_bot).should == 'exchange_currency_bot_2012_61_23'
       end
     end
   end