exchange 0.5.1 → 0.6.0

data/lib/exchange/currency.rb

@@ -8,23 +8,28 @@ module Exchange
   # Currency Objects instantiated from the currency class can be used for basic mathematical operations and currency conversions
   # @version 0.1
   # @since 0.1
+  #
   class Currency
     include Comparable
     
     # @attr_reader
     # @return [BigDecimal] number The number the currency object has been instantiated from
+    #
     attr_reader :value
     
     # @attr_reader
     # @return [Symbol, String] currency the currency of the currency object
+    #
     attr_reader :currency
     
     # @attr_reader
     # @return [Time] The time at which the conversion has taken place or should take place if the object is involved in operations
+    #
     attr_reader :time
     
     # @attr_reader
     # @return [Exchange::Currency] The original currency object this currency object was converted from
+    #
     attr_reader :from
     
     # Intialize the currency with a number and a currency
@@ -41,7 +46,7 @@ module Exchange
     # @example Instantiate a currency object of 40 US Dollars and convert it to Euro. It shows the conversion date and the original currency
     #   Exchange::Currency.new(40, :usd).to_eur(:at => Time.gm(2012,9,1)) 
     #     #=> #<Exchange::Currency @number=37.0 @currency=:usd @time=#<Time> @from=#<Exchange::Currency @number=40.0 @currency=:usd>>
-    
+    #
     def initialize value, currency, opts={}
       @value            = ISO4217.instantiate(value, currency)
       @currency         = currency
@@ -55,10 +60,10 @@ module Exchange
     #   Exchange::Currency.new(40,:usd).to_chf
     # @example Calls convert_to with 'sek' and :at => Time.gm(2012,2,2)
     #   Exchange::Currency.new(40,:nok).to_sek(:at => Time.gm(2012,2,2))
-    
+    #
     def method_missing method, *args, &block
       match = method.to_s.match(/\Ato_(\w{3})/)
-      if match && Configuration.api_class::CURRENCIES.include?($1)
+      if match && Exchange.configuration.api.subclass::CURRENCIES.include?($1)
         return self.convert_to($1, {:at => self.time}.merge(args.first || {}))
       elsif match && ISO4217.definitions.keys.include?($1.upcase)
         raise NoRateError.new("Cannot convert to #{$1} because the defined api does not provide a rate")
@@ -76,17 +81,18 @@ module Exchange
     #   Exchange::Currency.new(40,:usd).convert_to('chf')
     # @example convert to 'sek' at a specific rate
     #   Exchange::Currency.new(40,:nok).convert_to('sek', :at => Time.gm(2012,2,2))
-    
+    #
     def convert_to other, opts={}
-      Currency.new(Configuration.api_class.new.convert(value, currency, other, opts), other, opts.merge(:from => self))
+      Currency.new(Exchange.configuration.api.subclass.new.convert(value, currency, other, opts), other, opts.merge(:from => self))
     end
     
     class << self
       
       private
+      
         # @private
         # @macro [attach] install_operations
-         
+        #
         def install_operation op
           define_method op do |*precision|
             @value = ISO4217.send(op, self.value, self.currency, precision.first)
@@ -97,11 +103,11 @@ module Exchange
         # @private
         # @macro [attach] base_operations
         #   @method $1(other)
-      
+        #
         def base_operation op
           self.class_eval <<-EOV
             def #{op}(other)
-              #{'raise CurrencyMixError.new("You\'re trying to mix up #{self.currency} with #{other.currency}. You denied mixing currencies in the configuration, allow it or convert the currencies before mixing") if !Configuration.allow_mixed_operations && other.kind_of?(Currency) && other.currency != self.currency'}
+              #{'raise CurrencyMixError.new("You\'re trying to mix up #{self.currency} with #{other.currency}. You denied mixing currencies in the configuration, allow it or convert the currencies before mixing") if !Exchange.configuration.allow_mixed_operations && other.kind_of?(Currency) && other.currency != self.currency'}
               @value #{op}= other.kind_of?(Currency) ? other.convert_to(self.currency, :at => other.time) : other
               self
             end
@@ -122,7 +128,7 @@ module Exchange
     # @example Round your currency to another number of decimals
     #   Exchange::Currency.new(40.545, :usd).round(0)
     #     #=> #<Exchange::Currency @value=41 @currency=:usd>
-    
+    #
     install_operation :round
     
     
@@ -138,7 +144,7 @@ module Exchange
     # @example Ceil your currency to another number of decimals
     #   Exchange::Currency.new(40.445, :usd).ceil(0)
     #     #=> #<Exchange::Currency @value=41 @currency=:usd>
-    
+    #
     install_operation :ceil
     
     
@@ -154,7 +160,7 @@ module Exchange
     # @example Floor your currency to another number of decimals
     #   Exchange::Currency.new(40.545, :usd).floor(0)
     #     #=> #<Exchange::Currency @value=40 @currency=:usd>
-    
+    #
     install_operation :floor
     
     
@@ -163,13 +169,13 @@ module Exchange
     # @return [Exchange::Currency] The currency with the added value
     # @raise [CurrencyMixError] If the configuration does not allow mixed operations, this method will raise an error if two different currencies are used in the operation
     # @example Configuration disallows mixed operations
-    #   Exchange::Configuration.allow_mixed_operations = false
+    #   Exchange.configuration.allow_mixed_operations = false
     #   Exchange::Currency.new(20,:nok) + Exchange::Currency.new(20,:sek)
     #     #=> #<CurrencyMixError "You tried to mix currencies">
     # @example Configuration allows mixed operations (default)
     #   Exchange::Currency.new(20,:nok) + Exchange::Currency.new(20,:sek)
     #     #=> #<Exchange::Currency @value=37.56 @currency=:nok>
-    
+    #
     base_operation '+'
     
     # Subtract a value from the currency
@@ -177,13 +183,13 @@ module Exchange
     # @return [Exchange::Currency] The currency with the added value
     # @raise [CurrencyMixError] If the configuration does not allow mixed operations, this method will raise an error if two different currencies are used in the operation
     # @example Configuration disallows mixed operations
-    #   Exchange::Configuration.allow_mixed_operations = false
+    #   Exchange.configuration.allow_mixed_operations = false
     #   Exchange::Currency.new(20,:nok) - Exchange::Currency.new(20,:sek)
     #     #=> #<CurrencyMixError "You tried to mix currencies">
     # @example Configuration allows mixed operations (default)
     #   Exchange::Currency.new(20,:nok) - Exchange::Currency.new(20,:sek)
     #     #=> #<Exchange::Currency @value=7.56 @currency=:nok>
-    
+    #
     base_operation '-'
     
     # Multiply a value with the currency
@@ -191,13 +197,13 @@ module Exchange
     # @return [Exchange::Currency] The currency with the multiplied value
     # @raise [CurrencyMixError] If the configuration does not allow mixed operations, this method will raise an error if two different currencies are used in the operation
     # @example Configuration disallows mixed operations
-    #   Exchange::Configuration.allow_mixed_operations = false
+    #   Exchange.configuration.allow_mixed_operations = false
     #   Exchange::Currency.new(20,:nok) * Exchange::Currency.new(20,:sek)
     #     #=> #<CurrencyMixError "You tried to mix currencies">
     # @example Configuration allows mixed operations (default)
     #   Exchange::Currency.new(20,:nok) * Exchange::Currency.new(20,:sek)
     #     #=> #<Exchange::Currency @value=70.56 @currency=:nok>
-    
+    #
     base_operation '*'
     
     # Divide the currency by a value
@@ -205,13 +211,13 @@ module Exchange
     # @return [Exchange::Currency] The currency with the divided value
     # @raise [CurrencyMixError] If the configuration does not allow mixed operations, this method will raise an error if two different currencies are used in the operation
     # @example Configuration disallows mixed operations
-    #   Exchange::Configuration.allow_mixed_operations = false
+    #   Exchange.configuration.allow_mixed_operations = false
     #   Exchange::Currency.new(20,:nok) / Exchange::Currency.new(20,:sek)
     #     #=> #<CurrencyMixError "You tried to mix currencies">
     # @example Configuration allows mixed operations (default)
     #   Exchange::Currency.new(20,:nok) / Exchange::Currency.new(20,:sek)
     #     #=> #<Exchange::Currency @value=1.56 @currency=:nok>
-    
+    #
     base_operation '/'
     
     # Compare a currency with another currency or another value. If the other is not an instance of Exchange::Currency, the value 
@@ -224,11 +230,11 @@ module Exchange
     #   Exchange::Currency.new(40, :usd) == Exchange::Currency.new(34, :eur) #=> true, will implicitly convert eur to usd at the actual rate
     # @example Compare a currency with a number, the value of the currency will get compared
     #   Exchange::Currency.new(35, :usd) == 35 #=> true
-    
+    #
     def == other
-      if other.is_a?(Exchange::Currency) && other.currency == self.currency
+      if is_same_currency?(other)
         other.round.value == self.round.value
-      elsif other.is_a?(Exchange::Currency)
+      elsif is_currency?(other)
         other.convert_to(self.currency, :at => other.time).round.value == self.round.value
       else
         self.value == other
@@ -241,6 +247,7 @@ module Exchange
     # @return [Fixed] a number which can be used for sorting
     # @since 0.3
     # @version 0.3
+    # @todo which historic conversion should be used when two are present?
     # @example Compare two currencies in terms of value
     #   Exchange::Currency.new(40, :usd) <=> Exchange::Currency.new(28, :usd) #=> -1
     # @example Compare two different currencies, the other will get converted for comparison
@@ -249,17 +256,13 @@ module Exchange
     #   [1.usd, 1.eur, 1.chf].sort.map(&:currency) #=> [:usd, :chf, :eur]
     
     def <=> other
-      # TODO which historic conversion should be used when two are present?
-      if other.is_a?(Exchange::Currency) && ((other.currency == self.currency && self.value < other.value) || (other.currency != self.currency && self.value < other.convert_to(self.currency, :at => other.time).value))
-        -1
-      elsif other.is_a?(Exchange::Currency) && ((other.currency == self.currency && self.value > other.value) || (other.currency != self.currency && self.value > other.convert_to(self.currency, :at => other.time).value))
-        1
-      elsif other.is_a?(Exchange::Currency)
-        0
+      if is_same_currency?(other)
+        self.value <=> other.value
+      elsif is_other_currency?(other)
+        self.value <=> other.convert_to(self.currency, :at => other.time).value
       else
         self.value <=> other
       end
-        
     end
     
     # Converts the currency to a string in ISO 4217 standardized format, either with or without the currency. This leaves you
@@ -283,9 +286,37 @@ module Exchange
         format == :amount && ISO4217.stringify(self.value, self.currency, :amount_only => true)
       ].detect{|l| l.is_a?(String) }
     end
+    
+    private
+    
+      # determine if another given object is an instance of Exchange::Currency
+      # @param [Object] other The object to be tested against
+      # @return [Boolean] true if the other is an instance of Exchange::Currency, false if not
+      #
+      def is_currency? other
+        other.is_a?(Exchange::Currency)
+      end
+      
+      # determine if another given object is an instance of Exchange::Currency and the same currency
+      # @param [Object] other The object to be tested against
+      # @return [Boolean] true if the other is an instance of Exchange::Currency and has the same currency as self, false if not
+      #
+      def is_same_currency? other
+        is_currency?(other) && other.currency == self.currency
+      end
+      
+      # determine if another given object is an instance of Exchange::Currency and has another currency
+      # @param [Object] other The object to be tested against
+      # @return [Boolean] true if the other is an instance of Exchange::Currency and has another currency as self, false if not
+      #
+      def is_other_currency? other
+        is_currency?(other) && other.currency != self.currency
+      end
   
   end
   
   # The error that will get thrown when currencies get mixed up in base operations
+  #
   CurrencyMixError = Class.new(ArgumentError)
+  
 end

data/lib/exchange/external_api.rb

@@ -1,4 +1,6 @@
 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/xavier_media'

data/lib/exchange/external_api/base.rb

@@ -42,27 +42,31 @@ module Exchange
   #     end
   #   end
   #   # Now, you can configure your API in the configuration. The Symbol will get camelcased and constantized
-  #   Exchange::Configuration.api = :my_custom
+  #   Exchange::Configuration.api.subclass = :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
       
       
@@ -76,8 +80,9 @@ module Exchange
       # @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={})
-        rate = Exchange::Configuration.cache_class.cached(Exchange::Configuration.api, opts.merge(:key_for => [from, to], :plain => true)) do
+        rate = Exchange.configuration.cache.subclass.cached(Exchange.configuration.api.subclass, 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]
@@ -97,10 +102,11 @@ module Exchange
       # @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 * rate(from, to, opts)
       end
-        
+      
     end
   end
 end

data/lib/exchange/external_api/call.rb

@@ -5,7 +5,7 @@ module Exchange
     # @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
@@ -29,13 +29,15 @@ module Exchange
       # @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
-        result = Exchange::Configuration.cache_class(options).cached(options[:api] || Exchange::Configuration.api, options) do
-          load_url(url, options[:retries] || Exchange::Configuration.retries, options[:retry_with])
+        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])
         end
         
-        parsed = options[:format] == :xml ? Nokogiri.parse(result) : JSON.load(result)
+        parsed = options[:format] == :xml ? Nokogiri.parse(result) : ::JSON.load(result)
         
         return parsed unless block_given?
         yield  parsed
@@ -47,12 +49,11 @@ 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
-      
+        #
         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 => e
             retries -= 1
@@ -69,6 +70,8 @@ module Exchange
     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

@@ -1,15 +1,19 @@
 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/
+    # You can find further information on the currency bot API here: http://openexchangerates.org
     # @author Beat Richartz
     # @version 0.1
     # @since 0.1
-    
+    #
     class CurrencyBot < Base
+      
       # The base of the Currency Bot exchange API
+      #
       API_URL              = 'http://openexchangerates.org/api'
+      
       # 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
@@ -18,7 +22,7 @@ module Exchange
       # @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 = Exchange::Helper.assure_time(opts[:at])
         
@@ -36,10 +40,10 @@ module Exchange
         # @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?app_id=#{Exchange::Configuration.api_app_id}" : "latest.json?app_id=#{Exchange::Configuration.api_app_id}"].join('/')
+          [API_URL, time && (time.year != today.year || time.yday != today.yday) ? "historical/#{time.strftime("%Y-%m-%d")}.json" : "latest.json"].join('/') + "?app_id=#{Exchange.configuration.api.app_id}"
         end
         
     end

data/lib/exchange/external_api/ecb.rb

@@ -6,13 +6,18 @@ module Exchange
     # @author Beat Richartz
     # @version 0.3
     # @since 0.3
-    
-    class ECB < Base
+    #
+    class Ecb < XML
+      
       # 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)
       
+      # The result of the api call to the Central bank
       attr_accessor :callresult
       
       # Updates the rates by getting the information from ECB API for today or a defined historical date
@@ -20,23 +25,26 @@ module Exchange
       # 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))
-      
+      # @example Update the ecb API to use the file of March 2, 2010
+      #   Exchange::ExternalAPI::Ecb.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 Exchange::Configuration.cache
+        times         = Exchange.configuration.api.retries.times.map{ |i| time - 86400 * (i+1) }
         
-        Exchange::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|
+        # 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
+          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
+            
             @callresult = r.to_s
           end
         end
@@ -55,7 +63,7 @@ module Exchange
         # 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
           [
@@ -64,6 +72,14 @@ module Exchange
           ].join('/')
         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
+        #
+        def call_opts time
+          {:format => :xml, :at => time, :cache => :file, :cache_period => time >= Time.now - 90 * 86400 ? :daily : :monthly}
+        end
+        
     end
   end
 end