exchange 0.8.0 → 0.9.0

data/lib/{core_extensions → exchange/core_extensions/numeric}/conversability.rb

@@ -12,24 +12,24 @@ module Exchange
     # and others via method missing, this is not handled via method missing because it would seriously break down performance.
     # 
     # @example Instantiate from any type of number
-    #   40.usd => #<Exchange::Currency @value=40 @currency=:usd>
-    #   -33.nok => #<Exchange::Currency @value=-33 @currency=:nok>
-    #   33.333.sek => #<Exchange::Currency @value=33.333 @currency=:sek>
+    #   40.usd => #<Exchange::Money @value=40 @currency=:usd>
+    #   -33.nok => #<Exchange::Money @value=-33 @currency=:nok>
+    #   33.333.sek => #<Exchange::Money @value=33.333 @currency=:sek>
     # @example Instantiate and immediatly convert
-    #   1.usd.to_eur => #<Exchange::Currency @value=0.79 @currency=:eur>
-    #   1.nok.to_chf => #<Exchange::Currency @value=6.55 @currency=:chf>
-    #   -3.5.dkk.to_huf => #<Exchange::Currency @value=-346.55 @currency=:huf>
+    #   1.usd.to_eur => #<Exchange::Money @value=0.79 @currency=:eur>
+    #   1.nok.to_chf => #<Exchange::Money @value=6.55 @currency=:chf>
+    #   -3.5.dkk.to_huf => #<Exchange::Money @value=-346.55 @currency=:huf>
     # @example Instantiate and immediatly convert at a specific time in the past
-    #   1.usd.to_eur(:at => Time.now - 86400) => #<Exchange::Currency @value=0.80 @currency=:eur>
-    #   1.nok.to_chf(:at => Time.now - 3600) => #<Exchange::Currency @value=6.57 @currency=:chf>
-    #   -3.5.dkk.to_huf(:at => Time.now - 172800) => #<Exchange::Currency @value=-337.40 @currency=:huf>
+    #   1.usd.to_eur(:at => Time.now - 86400) => #<Exchange::Money @value=0.80 @currency=:eur>
+    #   1.nok.to_chf(:at => Time.now - 3600) => #<Exchange::Money @value=6.57 @currency=:chf>
+    #   -3.5.dkk.to_huf(:at => Time.now - 172800) => #<Exchange::Money @value=-337.40 @currency=:huf>
     #
     # @since 0.1
     # @version 0.2
     #
-    ISO4217.definitions.keys.each do |c|
-      define_method c.downcase.to_sym do |*args|
-        Currency.new(self, c, *args)
+    ISO4217.currencies.each do |c|
+      define_method c do |*args|
+        Money.new(self, c, *args)
       end
     end
     

data/lib/exchange/external_api.rb

@@ -1,7 +1,8 @@
+require 'exchange/external_api/configuration'
 require 'exchange/external_api/base'
 require 'exchange/external_api/xml'
 require 'exchange/external_api/json'
 require 'exchange/external_api/call'
-require 'exchange/external_api/currency_bot'
+require 'exchange/external_api/open_exchange_rates'
 require 'exchange/external_api/xavier_media'
 require 'exchange/external_api/ecb'

data/lib/exchange/external_api/base.rb

@@ -9,14 +9,21 @@ module Exchange
   # @example Easily connect to your custom API by writing an ExternalAPI Class
   #   module Exchange
   #     module ExternalAPI
-  #       class MyCustom < Base
+  #
+  #       # Inherit from Json to write for a json api, and the json gem is automatically loaded
+  #       # Inherit from XML to write for an xml api, and nokogiri is automatically loaded
+  #       # 
+  #       class MyCustom < Json
+  #         
   #         # Define here which currencies your API can handle
-  #         CURRENCIES = %W(usd chf)
+  #         #
+  #         CURRENCIES = %W(usd chf).map(&:to_sym)
   #         
   #         # 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 = helper.assure_time(opts[:at]) 
@@ -44,6 +51,7 @@ module Exchange
   #           # Attention, this is readonly, self.timestamp= won't work
   #           #
   #           @timestamp            = result['timestamp'].to_i
+  #
   #         end
   #         
   #         private
@@ -120,19 +128,19 @@ module Exchange
       #   Exchange::ExternalAPI::Base.new.rate(:usd, :eur, :at => Time.gm(3,23,2009))
       #     #=> 1.232231231
       #
-      def rate(from, to, opts={})
-        rate = cache.cached(api, opts.merge(:key_for => [from, to], :plain => true)) do
+      def rate(from, to, opts={})        
+        rate = cache.cached(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]
+          rate_from   = rates[from]
+          rate_to     = rates[to]
           
           test_for_rates_and_raise_if_nil rate_from, rate_to, opts[:at]
           
-          rate_from / rate_to
+          rate_to / rate_from
         end
         
-        BigDecimal.new(rate.to_s)
+        rate.is_a?(BigDecimal) ? rate : BigDecimal.new(rate.to_s)
       end
       
       # Converts an amount of one currency into another
@@ -165,8 +173,25 @@ module Exchange
       # @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
+        raise NoRateError.new("No rates where found for #{rate_from} to #{rate_to} #{'at ' + time.to_s if time}") unless rate_from && rate_to
       end
+      
+      protected
+      
+      # Convenience accessor to api configuration
+      # @return [Exchange::ExternalAPI::Configuration] the current configuration
+      #
+      def config
+        @config ||= Exchange.configuration.api
+      end
+      
+      # Convenience accessor to the cache configuration
+      # @return [Exchange::Cache::Configuration] the current configuration
+      #
+      def cache_config
+        @cache_config ||= Exchange.configuration.cache
+      end
+      
     end
   end
 end

data/lib/exchange/external_api/call.rb

@@ -6,7 +6,7 @@ module Exchange
     # @version 0.1
     # @since 0.1
     #
-    class Call
+    class Call < Base
       
       # 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
@@ -31,12 +31,10 @@ module Exchange
       #   # Do something with that result
       #
       def initialize url, options={}, &block        
-        Exchange::GemLoader.new('nokogiri').try_load if options[:format] == :xml
-        
-        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])
+        Exchange::GemLoader.new(options[:format] == :xml ? 'nokogiri' : 'json').try_load
+                
+        result = cache_config.subclass.cached(options[:api] || config.subclass, options) do
+          load_url(url, options[:retries] || config.retries, options[:retry_with])
         end
         
         parsed = options[:format] == :xml ? Nokogiri::XML.parse(result.sub("\n", '')) : ::JSON.load(result)
@@ -64,7 +62,7 @@ module Exchange
               url = retry_with.shift if retry_with && !retry_with.empty?
               retry
             else
-              raise APIError.new("API #{url} was not reachable")
+              raise APIError.new("API #{url} was not reachable and returned #{e.message}. May be you requested a historic rate not provided")
             end
           end
           result          

data/lib/exchange/external_api/configuration.rb

@@ -0,0 +1,25 @@
+module Exchange
+  module ExternalAPI
+    # @author Beat Richartz
+    # A Class that handles api configuration options
+    # 
+    # @version 0.9
+    # @since 0.9
+    #
+    class Configuration < Exchange::Configurable
+
+      attr_accessor :retries, :app_id, :protocol
+      
+      def_delegators :instance, :retries, :retries=, :app_id, :app_id=, :protocol, :protocol=
+      
+      def parent_module
+        ExternalAPI
+      end
+      
+      def key
+        :api
+      end
+      
+    end
+  end 
+end

data/lib/exchange/external_api/ecb.rb

@@ -11,11 +11,11 @@ module Exchange
       
       # The base of the ECB API URL
       #
-      API_URL              = "http://www.ecb.europa.eu/stats/eurofxref"
+      API_URL              = "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)
+      CURRENCIES           = [: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] 
       
       # The result of the api call to the Central bank
       attr_accessor :callresult
@@ -35,26 +35,17 @@ module Exchange
         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
-        # 
-        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
-            #
-            t = times.shift while (r = find_rate!(result, t)).empty? && !times.empty?
-            
-            @callresult = r.to_s
-          end
+        Call.new(api_url(time), call_opts(time)) do |result|
+          t = time
+          
+          # Weekends do not have rates present
+          #
+          t = times.shift while (r = find_rate!(result, t)).empty? && !times.empty?
+                    
+          @base                 = :eur # We just have to assume, since it's the ECB
+          @rates                = extract_rates(r.children)
+          @timestamp            = time.to_i
         end
-
-        parsed = Nokogiri.parse(self.callresult)
-        
-        @base                 = 'EUR' # We just have to assume, since it's the ECB
-        @rates                = extract_rates(parsed.children.children)
-        @timestamp            = time.to_i
       end
       
       private
@@ -67,7 +58,7 @@ module Exchange
         #
         def api_url(time)
           border = Time.now - 90 * 86400
-          [
+          [ "#{config.protocol}:/", 
             API_URL, 
             border <= time ? 'eurofxref-hist-90d.xml' : 'eurofxref-hist.xml'
           ].join('/')
@@ -96,7 +87,7 @@ module Exchange
             map_to_currency_or_rate c
           }.compact.flatten
           
-          to_hash!(['EUR', BigDecimal.new("1")] + rate_array)
+          to_hash!([:eur, BigDecimal.new("1")] + rate_array)
         end
         
         # a helper method to map a key value pair to either currency or rate
@@ -109,7 +100,7 @@ module Exchange
           unless (values = xml.attributes.values).empty?
             values.map { |v|
               val = v.value
-              val.match(/\d+/) ? BigDecimal.new(val) : val 
+              val.match(/\d+/) ? BigDecimal.new(val) : val.downcase.to_sym
             }.sort_by(&:to_s).reverse 
           end
         end
@@ -121,7 +112,7 @@ module Exchange
         # @version 0.7
         #
         def map_retry_times time
-          Exchange.configuration.api.retries.times.map{ |i| time - 86400 * (i+1) }
+          config.retries.times.map{ |i| time - 86400 * (i+1) }
         end
         
         # a wrapper for the call options, since the cache period is quite complex

data/lib/exchange/external_api/json.rb

@@ -7,6 +7,16 @@ module Exchange
     # @version 0.6
     # @since 0.6
     #
-    JSON = Class.new Base
+    class Json < Base
+      
+      # Initializer, essentially takes the arguments passed to initialization, loads json 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
   end
 end

data/lib/exchange/external_api/open_exchange_rates.rb

@@ -0,0 +1,65 @@
+module Exchange
+  module ExternalAPI
+    # The Open Exchange Rates API class, handling communication with the Open Source Currency bot API
+    # You can find further information on the Open Exchange Rates API here: http://openexchangerates.org
+    # @author Beat Richartz
+    # @version 0.1
+    # @since 0.1
+    #
+    class OpenExchangeRates < Base
+      
+      # The base of the Open Exchange Rates exchange API
+      #
+      API_URL              = 'openexchangerates.org/api'
+      
+      # The currencies the Open Exchange Rates API can convert
+      #
+      CURRENCIES           = [: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 Open Exchange Rates 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 Open Exchange Rates API to use the file of March 2, 2010
+      #   Exchange::ExternalAPI::OpenExchangeRates.new.update(:at => Time.gm(3,2,2010))
+      #
+      def update(opts={})
+        time = helper.assure_time(opts[:at])
+        
+        Call.new(api_url(time), :at => time) do |result|
+          @base                 = result['base'].downcase.to_sym
+          @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.map{|k| k.downcase.to_sym }.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
+        # @since 0.1
+        # @version 0.2.6
+        #
+        def api_url(time=nil)
+          today   = Time.now
+          [ 
+            "#{config.protocol}:/", 
+            API_URL, 
+            time && (time.year != today.year || time.yday != today.yday) ? "historical/#{time.strftime("%Y-%m-%d")}.json" : "latest.json"
+          ].join('/') + "?app_id=#{config.app_id}"
+        end
+        
+    end
+  end
+end

data/lib/exchange/external_api/xavier_media.rb

@@ -10,9 +10,9 @@ module Exchange
     class XavierMedia < XML
       
       # The base of the Xaviermedia API URL
-      API_URL              = "http://api.finance.xaviermedia.com/api"
+      API_URL              = "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)
+      CURRENCIES           = [: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.
@@ -40,7 +40,7 @@ module Exchange
         # @return [String] An Xaviermedia API URL for the specified time
         #
         def api_url(time)
-          [API_URL, "#{time.strftime("%Y/%m/%d")}.xml"].join('/')
+          ["#{config.protocol}:/", API_URL, "#{time.strftime("%Y/%m/%d")}.xml"].join('/')
         end
         
         # Options for the API call to make
@@ -51,7 +51,7 @@ module Exchange
         # @version 0.6
         #
         def api_opts(opts={})
-          retry_urls = Exchange.configuration.api.retries.times.map { |i| api_url(opts[:at] - 86400 * (i+1)) }
+          retry_urls = config.retries.times.map { |i| api_url(opts[:at] - 86400 * (i+1)) }
           
           { :format => :xml, :at => opts[:at], :retry_with => retry_urls }
         end
@@ -73,18 +73,18 @@ module Exchange
         # @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
+          rates_array = result.css('fx currency_code').children.map{|c| c.to_s.downcase.to_sym }.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
+        # @return [Symbol] The base currency for the rates
         # @since 0.7
         # @version 0.7
         #
         def extract_base_currency(result)
-          result.css('basecurrency').children[0].to_s
+          result.css('basecurrency').children[0].to_s.downcase.to_sym
         end
         
     end

data/lib/exchange/iso_4217.rb

@@ -23,7 +23,7 @@ module Exchange
         def install_operation op      
           self.class_eval <<-EOV
             def #{op}(amount, currency, precision=nil)
-              minor = definitions[currency.to_s.upcase]['minor_unit']
+              minor = definitions[currency][:minor_unit]
               (amount.is_a?(BigDecimal) ? amount : BigDecimal.new(amount.to_s, minor)).#{op}(precision || minor)
             end
           EOV
@@ -36,7 +36,34 @@ module Exchange
     # @return [Hash] The iso427 Definitions with the currency code as keys
     #
     def definitions
-      @@definitions ||= YAML.load_file(File.join(ROOT_PATH, 'iso4217.yml'))
+      return @definitions if @definitions
+      loaded       = YAML.load_file(File.join(ROOT_PATH, 'iso4217.yml'))
+      @definitions = {}
+      
+      loaded.each_pair do |k,v| 
+        v.keys.each do |key|
+          v[key.to_sym] = v.delete(key)
+        end
+        
+        @definitions[k.downcase.to_sym] = v
+      end
+      
+      @definitions
+    end
+    
+    # All currencies defined by ISO 4217 as an array of symbols for inclusion testing
+    # @return [Array] An Array of currency symbols
+    #
+    def currencies
+      @currencies  ||= definitions.keys.map(&:to_s).sort.map(&:to_sym)
+    end
+    
+    # Check if a currency is defined by ISO 4217 standards
+    # @param [Symbol] currency the downcased currency symbol
+    # @return [Boolean] true if the symbol matches a currency, false if not
+    #
+    def defines? currency
+      currencies.include? currency
     end
     
     # Use this to instantiate a currency amount. For one, it is important that we use BigDecimal here so nothing gets lost because
@@ -48,7 +75,7 @@ module Exchange
     #   Exchange::ISO4217.instantiate("4523", "usd") #=> #<Bigdecimal 4523.00>
     #
     def instantiate(amount, currency)
-      BigDecimal.new(amount.to_s, definitions[currency.to_s.upcase]['minor_unit'])
+      BigDecimal.new(amount.to_s, definitions[currency][:minor_unit])
     end
     
     # Converts the currency to a string in ISO 4217 standardized format, either with or without the currency. This leaves you
@@ -68,7 +95,7 @@ module Exchange
     #   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"
+      format      = "%.#{definitions[currency][:minor_unit]}f"
       "#{currency.to_s.upcase + ' ' unless opts[:amount_only]}#{format % amount}"
     end
     
@@ -101,7 +128,7 @@ module Exchange
     
     # Forwards the assure_time method to the instance using singleforwardable
     #
-    def_delegators :instance, :definitions, :instantiate, :stringify, :round, :ceil, :floor
+    def_delegators :instance, :definitions, :instantiate, :stringify, :round, :ceil, :floor, :currencies, :defines?
     
   end
 end