exchange 0.2.6 → 0.3.0

data/lib/core_extensions/conversability.rb

@@ -6,7 +6,10 @@ module Exchange
   # @since 0.1
   
   module Conversability
-    # Method missing is used here to allow instantiation and immediate conversion of Currency objects from a common Fixnum or Float
+    # Dynamic method generation is used here to allow instantiation and immediate conversion of Currency objects from 
+    # a common Fixnum or Float or BigDecimal. Since ruby 1.9 handles certain type conversion of Fixnum, Float 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>
@@ -20,13 +23,15 @@ module Exchange
     #   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>
     
-    def method_missing method, *args, &block
-      return Exchange::Currency.new(self, method, *args) if method.to_s.length == 3 && Exchange::Configuration.api_class::CURRENCIES.include?(method.to_s)
-    
-      super method, *args, &block
+    ISO4217.definitions.keys.each do |c|
+      define_method c.downcase.to_sym do |*args|
+        Currency.new(self, c, *args)
+      end
     end
+    
   end
 end
 
-Fixnum.send :include, Exchange::Conversability
-Float.send  :include, Exchange::Conversability
+Fixnum.send     :include, Exchange::Conversability
+Float.send      :include, Exchange::Conversability
+BigDecimal.send :include, Exchange::Conversability

data/lib/exchange.rb

@@ -1,11 +1,17 @@
+require 'bigdecimal'
 require 'open-uri'
 require 'bundler'
 require 'json'
 require 'nokogiri'
 require 'redis'
 require 'memcached'
+require 'exchange/helper'
 require 'exchange/configuration'
+require 'exchange/iso_4217'
 require 'exchange/currency'
 require 'exchange/external_api'
 require 'exchange/cache'
-require 'core_extensions/conversability'
+require 'core_extensions/conversability'
+
+# The error that gets thrown if no conversion rate is available
+NoRateError = Class.new(StandardError)

data/lib/exchange/cache.rb

@@ -2,3 +2,5 @@ require 'exchange/cache/base'
 require 'exchange/cache/memcached'
 require 'exchange/cache/redis'
 require 'exchange/cache/rails'
+require 'exchange/cache/file'
+require 'exchange/cache/no_cache'

data/lib/exchange/cache/base.rb

@@ -37,11 +37,15 @@ module Exchange
           # @example
           #   Exchange::Cache::Base.key(Exchange::ExternalAPI::CurrencyBot, Time.gm(2012,1,1)) #=> "Exchange_ExternalAPI_CurrencyBot_2012_1"
           
-          def key(api_class, time=nil)
-            time      ||= Time.now
-            key_parts = [api_class.to_s.gsub(/::/, '_'), time.year, time.yday]
-            key_parts << time.hour if Exchange::Configuration.update == :hourly
-            key_parts.join('_')
+          def key(api, opts={})
+            time          = Exchange::Helper.assure_time(opts[:at], :default => :now)
+            [ 'exchange',
+              api.to_s, 
+              time.year.to_s, 
+              time.yday.to_s, 
+              Exchange::Configuration.update == :hourly ? time.hour.to_s : nil,
+              *(opts[:key_for] || [])
+            ].compact.join('_')
           end
         
       end

data/lib/exchange/cache/file.rb

@@ -0,0 +1,65 @@
+module Exchange
+  module Cache
+    
+    # @author Beat Richartz
+    # A class that allows to store api call results in files. THIS NOT A RECOMMENDED CACHING OPTION!
+    # It just may be necessary to cache large files somewhere, this class allows you to do that
+    # 
+    # @version 0.3
+    # @since 0.3
+    
+    class File < Base
+      class << self
+        
+        # returns either cached data from a stored file or stores a file.
+        # This method has to be the same in all the cache classes in order for the configuration binding to work
+        # @param [Exchange::ExternalAPI::Subclass] api The API class the data has to be stored for
+        # @param [Hash] opts the options to cache with
+        # @option opts [Time] :at IS IGNORED FOR FILECACHE
+        # @option opts [Symbol] :cache_period The period to cache the file for
+        # @yield [] This method takes a mandatory block with an arity of 0 and calls it if no cached result is available
+        # @raise [CachingWithoutBlockError] an Argument Error when no mandatory block has been given
+        
+        def cached api, opts={}, &block
+          raise CachingWithoutBlockError.new('Caching needs a block') unless block_given?
+          
+          today = Time.now
+          dir   = Exchange::Configuration.filestore_path
+          path  = ::File.join(dir, key(api, opts[:cache_period]))
+          
+          if ::File.exists?(path)
+            result = ::File.read(path)
+          else
+            result = block.call
+            if result && !result.to_s.empty?
+              FileUtils.mkdir_p(dir) unless Dir.respond_to?(:exists?) && Dir.exists?(dir)
+              keep_files = [key(api, :daily), key(api, :monthly)]
+              Dir.entries(dir).each do |e|
+                ::File.delete(::File.join(dir, e)) unless keep_files.include?(e) || e.match(/\A\./)
+              end
+              ::File.open(path, 'w') {|f| f.write(result) }
+            end
+          end
+          
+          result
+        end
+        
+        private
+        
+          # A Cache Key generator for the file Cache Class and the time
+          # Generates a key which can handle expiration by itself
+          # @param [Exchange::ExternalAPI::Subclass] api_class The API to store the data for
+          # @param [optional, Symbol] cache_period The time for which the data is valid
+          # @return [String] A string that can be used as cache key
+          # @example
+          #   Exchange::Cache::Base.key(Exchange::ExternalAPI::CurrencyBot, :monthly) #=> "Exchange_ExternalAPI_CurrencyBot_monthly_2012_1"
+          
+          def key(api_class, cache_period=:daily)
+            time      = Time.now
+            [api_class.to_s.gsub(/::/, '_'), cache_period, time.year, time.send(cache_period == :monthly ? :month : :yday)].join('_')
+          end
+        
+      end
+    end
+  end
+end

data/lib/exchange/cache/memcached.rb

@@ -21,7 +21,7 @@ module Exchange
         # @return [::Memcached] an instance of the memcached client gem class
         
         def client
-          @@client ||= ::Memcached.new("#{Exchange::Configuration.cache_host}:#{Exchange::Configuration.cache_port}")
+          @@client ||= ::Memcached.new("#{Configuration.cache_host}:#{Configuration.cache_port}")
         end
         
         # returns either cached data from the memcached client or calls the block and caches it in memcached.
@@ -35,11 +35,11 @@ module Exchange
         def cached api, opts={}, &block
           raise CachingWithoutBlockError.new('Caching needs a block') unless block_given?
           begin
-            result = JSON.load client.get(key(api, opts[:at]))
+            result = JSON.load client.get(key(api, opts))
           rescue ::Memcached::NotFound
             result = block.call
-            if result && !result.empty?
-              client.set key(api, opts[:at]), result.to_json, Exchange::Configuration.update == :daily ? 86400 : 3600
+            if result && !result.to_s.empty?
+              client.set key(api, opts), result.to_json, Configuration.update == :daily ? 86400 : 3600
             end
           end
           

data/lib/exchange/cache/no_cache.rb

@@ -0,0 +1,33 @@
+module Exchange
+  module Cache
+    
+    # @author Beat Richartz
+    # A class that allows to store api call results in files. THIS NOT A RECOMMENDED CACHING OPTION!
+    # It just may be necessary to cache large files somewhere, this class allows you to do that
+    # 
+    # @version 0.3
+    # @since 0.3
+    
+    class NoCache < Base
+      class << self
+        
+        # returns either cached data from a stored file or stores a file.
+        # This method has to be the same in all the cache classes in order for the configuration binding to work
+        # @param [Exchange::ExternalAPI::Subclass] api The API class the data has to be stored for
+        # @param [Hash] opts the options to cache with
+        # @option opts [Time] :at IS IGNORED FOR FILECACHE
+        # @option opts [Symbol] :cache_period The period to cache the file for
+        # @yield [] This method takes a mandatory block with an arity of 0 and calls it if no cached result is available
+        # @raise [CachingWithoutBlockError] an Argument Error when no mandatory block has been given
+        
+        def cached api, opts={}, &block
+          raise CachingWithoutBlockError.new('Caching needs a block') unless block_given?
+          
+          block.call
+        end
+
+        
+      end
+    end
+  end
+end

data/lib/exchange/cache/rails.rb

@@ -33,8 +33,8 @@ module Exchange
         def cached api, opts={}, &block
           raise CachingWithoutBlockError.new('Caching needs a block') unless block_given?
           
-          result = client.fetch key(api, opts[:at]), :expires_in => Exchange::Configuration.update == :daily ? 86400 : 3600, &block
-          client.delete(key(api, opts[:at])) unless result && !result.empty?
+          result = client.fetch key(api, opts), :expires_in => Configuration.update == :daily ? 86400 : 3600, &block
+          client.delete(key(api, opts)) unless result && !result.to_s.empty?
           
           result
         end

data/lib/exchange/cache/redis.rb

@@ -21,7 +21,7 @@ module Exchange
         # @return [::Redis] an instance of the redis client gem class
         
         def client
-          @@client ||= ::Redis.new(:host => Exchange::Configuration.cache_host, :port => Exchange::Configuration.cache_port)
+          @@client ||= ::Redis.new(:host => Configuration.cache_host, :port => Configuration.cache_port)
         end
         
         # returns either cached data from the redis client or calls the block and caches it in redis.
@@ -35,13 +35,13 @@ module Exchange
         def cached api, opts={}, &block
           raise CachingWithoutBlockError.new('Caching needs a block') unless block_given?
           
-          if result = client.get(key(api, opts[:at]))
+          if result = client.get(key(api, opts))
             result = JSON.load result
           else
             result = block.call
-            if result && !result.empty?
-              client.set key(api, opts[:at]), result.to_json
-              client.expire key(api, opts[:at]), Exchange::Configuration.update == :daily ? 86400 : 3600
+            if result && !result.to_s.empty?
+              client.set key(api, opts), result.to_json
+              client.expire key(api, opts), Configuration.update == :daily ? 86400 : 3600
             end
           end
           

data/lib/exchange/configuration.rb

@@ -7,7 +7,7 @@ module Exchange
   # @since 0.1
   class Configuration    
     class << self
-      @@config ||= {:api => :currency_bot, :retries => 5, :allow_mixed_operations => true, :cache => :memcached, :cache_host => 'localhost', :cache_port => 11211, :update => :daily} 
+      @@config ||= {:api => :currency_bot, :retries => 5, :filestore_path => File.expand_path('exchange_filestore'), :allow_mixed_operations => true, :cache => :memcached, :cache_host => 'localhost', :cache_port => 11211, :update => :daily} 
       
       # A configuration method that stores the configuration of the gem. It allows to set the api from which the data gets retrieved,
       # the cache in which the data gets cached, the regularity of updates for the currency rates, how many times the api calls should be 
@@ -32,14 +32,16 @@ module Exchange
       # @yieldparam [optional, Integer] retries The number of times the gem should retry to connect to the api host. Defaults to 5.
       # @yieldparam [optional, Boolean] If set to false, Operations with with different currencies raise errors. Defaults to true.
       # @yieldparam [optional, Symbol] The regularity of updates for the API. Possible values: :daily, :hourly. Defaults to :daily.
+      # @yieldparam [optional, String] The path where files can be stored for the gem (used for large files from ECB). Make sure ruby has write access.
       # @example Set configuration values directly to the class
       #   Exchange::Configuration.cache = :redis
       #   Exchange::Configuration.api   = :xavier_media
+      
       def define &blk
         self.instance_eval(&blk)
       end
-      
-      [:api, :retries, :cache, :cache_host, :cache_port, :update, :allow_mixed_operations].each do |m|
+            
+      [:api, :retries, :cache, :cache_host, :cache_port, :filestore_path, :update, :allow_mixed_operations].each do |m|
         define_method m do
           @@config[m]
         end
@@ -52,20 +54,34 @@ module Exchange
       # @example
       #   Exchange::Configuration.api = :currency_bot
       #   Exchange::Configuration.api_class #=> Exchange::ExternalAPI::CurrencyBot
+      # @param [Hash] options A hash of Options
+      # @option options [Class] :api A api to return instead of the api class (use for fallback)
       # @return [Exchange::ExternalAPI::Subclass] A subclass of Exchange::ExternalAPI
       
-      def api_class
-        Exchange::ExternalAPI.const_get self.api.to_s.gsub(/(?:^|_)(.)/) { $1.upcase }
+      def api_class(options={})
+        @api_class ||= {}
+        return @api_class[options[:api] || self.api] if @api_class[options[:api] || self.api]
+
+        @api_class[options[:api] || self.api] = ExternalAPI.const_get((options[:api] || self.api).to_s.gsub(/(?:^|_)(.)/) { $1.upcase })
       end
       
       # The instantiated cache class according to the configuration
       # @example
       #   Exchange::Configuration.cache = :redis
       #   Exchange::Configuration.cache_class #=> Exchange::ExternalAPI::Redis
+      # @param [Hash] options A hash of Options
+      # @option options [Class] :api A api to return instead of the api class (use for fallback)
       # @return [Exchange::Cache::Subclass] A subclass of Exchange::Cache (or nil if caching has been set to false)
       
-      def cache_class
-        Exchange::Cache.const_get self.cache.to_s.gsub(/(?:^|_)(.)/) { $1.upcase } if self.cache
+      def cache_class(options={})
+        @cache_class ||= {}
+        return @cache_class[options[:cache] || self.cache] if @cache_class[options[:cache] || self.cache]
+        
+        @cache_class[options[:cache] || self.cache] = if self.cache
+          Cache.const_get((options[:cache] || self.cache).to_s.gsub(/(?:^|_)(.)/) { $1.upcase })
+        else
+          Cache::NoCache
+        end
       end
     end 
   end

data/lib/exchange/currency.rb

@@ -43,10 +43,10 @@ module Exchange
     #     #=> #<Exchange::Currency @number=37.0 @currency=:usd @time=#<Time> @from=#<Exchange::Currency @number=40.0 @currency=:usd>>
     
     def initialize value, currency, opts={}
-      @value            = value.to_f
+      @value            = ISO4217.instantiate(value, currency)
       @currency         = currency
-      @time             = assure_time(opts[:at], :default => :now)
-      @from             = opts[:from] if opts[:from]
+      @time             = Helper.assure_time(opts[:at], :default => :now)
+      @from             = opts[:from]
     end
     
     # Method missing is used to handle conversions from one currency object to another. It only handles currencies which are available in
@@ -57,9 +57,11 @@ module Exchange
     #   Exchange::Currency.new(40,:nok).to_sek(:at => Time.gm(2012,2,2))
     
     def method_missing method, *args, &block
-      if method.to_s.match(/\Ato_(\w+)/) && Exchange::Configuration.api_class::CURRENCIES.include?($1)
-        args.first[:at] ||= time if args.first
-        return self.convert_to($1, args.first || {:at => self.time})
+      match = method.to_s.match(/\Ato_(\w{3})/)
+      if match && Configuration.api_class::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")
       end
 
       self.value.send method, *args, &block
@@ -76,7 +78,7 @@ module Exchange
     #   Exchange::Currency.new(40,:nok).convert_to('sek', :at => Time.gm(2012,2,2))
     
     def convert_to other, opts={}
-      Exchange::Currency.new(Exchange::Configuration.api_class.new.convert(value, currency, other, opts), other, opts.merge(:from => self))
+      Currency.new(Configuration.api_class.new.convert(value, currency, other, opts), other, opts.merge(:from => self))
     end
     
     class << self
@@ -86,8 +88,8 @@ module Exchange
         # @macro [attach] install_operations
          
         def install_operation op
-          define_method op do
-            @value = self.value.send(op)
+          define_method op do |*precision|
+            @value = ISO4217.send(op, self.value, self.currency, precision.first)
             self
           end
         end
@@ -99,8 +101,8 @@ module Exchange
         def base_operation op
           self.class_eval <<-EOV
             def #{op}(other)
-              #{'raise Exchange::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?(Exchange::Currency) && other.currency != self.currency'}
-              @value #{op}= other.kind_of?(Exchange::Currency) ? other.convert_to(self.currency, :at => other.time) : 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'}
+              @value #{op}= other.kind_of?(Currency) ? other.convert_to(self.currency, :at => other.time) : other
               self
             end
           EOV
@@ -108,29 +110,50 @@ module Exchange
       
     end
     
-    # Round the currency (Equivalent to normal round)
+    # Round the currency. Since this is a currency, it will round to the standard decimal value.
+    # If you want to round it to another precision, you have to specifically ask for it.
     # @return [Exchange::Currency] The currency you started with with a rounded value
-    # @example
-    #   Exchange::Currency.new(40.5, :usd).round
-    #     #=> #<Exchange::Currency @number=41 @currency=:usd>
+    # @param [Integer] precision The precision you want the rounding to have. Defaults to the ISO 4217 standard value for the currency
+    # @since 0.1
+    # @version 0.3
+    # @example Round your currency to the iso standard number of decimals
+    #   Exchange::Currency.new(40.545, :usd).round
+    #     #=> #<Exchange::Currency @value=40.55 @currency=:usd>
+    # @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
     
     
-    # Ceil the currency (Equivalent to normal ceil)
+    # Ceil the currency. Since this is a currency, it will ceil to the standard decimal value.
+    # If you want to ceil it to another precision, you have to specifically ask for it.
     # @return [Exchange::Currency] The currency you started with with a ceiled value
-    # @example
-    #   Exchange::Currency.new(40.4, :usd).ceil
-    #     #=> #<Exchange::Currency @number=41 @currency=:usd>
+    # @param [Integer] precision The precision you want the ceiling to have. Defaults to the ISO 4217 standard value for the currency
+    # @since 0.1
+    # @version 0.3
+    # @example Ceil your currency to the iso standard number of decimals
+    #   Exchange::Currency.new(40.544, :usd).ceil
+    #     #=> #<Exchange::Currency @value=40.55 @currency=:usd>
+    # @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
     
     
-    # Floor the currency (Equivalent to normal floor)
+    # Floor the currency. Since this is a currency, it will ceil to the standard decimal value.
+    # If you want to ceil it to another precision, you have to specifically ask for it.
     # @return [Exchange::Currency] The currency you started with with a floored value
-    # @example
-    #   Exchange::Currency.new(40.7, :usd).floor
-    #     #=> #<Exchange::Currency @number=40 @currency=:usd>
+    # @param [Integer] precision The precision you want the flooring to have. Defaults to the ISO 4217 standard value for the currency
+    # @since 0.1
+    # @version 0.3
+    # @example Floor your currency to the iso standard number of decimals
+    #   Exchange::Currency.new(40.545, :usd).floor
+    #     #=> #<Exchange::Currency @value=40.54 @currency=:usd>
+    # @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
     
@@ -191,17 +214,42 @@ module Exchange
     
     base_operation '/'
     
+    # Compare a currency with another currency or another value. If the other is not an instance of Exchange::Currency, the value 
+    # of the currency is compared
+    # @param [Whatever you want to throw at it] other The counterpart to compare
+    # @return [Boolean] true if the other is equal, false if not
+    # @example Compare two currencies
+    #   Exchange::Currency.new(40, :usd) == Exchange::Currency.new(34, :usd) #=> true
+    # @example Compare two different currencies, the other will get converted for comparison
+    #   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
-        other.value == self.value
+        other.round.value == self.round.value
       elsif other.is_a?(Exchange::Currency)
-        other.convert_to(self.currency, :at => other.time).value == self.value
+        other.convert_to(self.currency, :at => other.time).round.value == self.round.value
       else
         self.value == other
       end
     end
     
+    # Sortcompare a currency with another currency. If the other is not an instance of Exchange::Currency, the value 
+    # of the currency is compared. Different currencies will be converted to the comparing instances currency
+    # @param [Whatever you want to throw at it] other The counterpart to compare
+    # @return [Fixed] a number which can be used for sorting
+    # @since 0.3
+    # @version 0.3
+    # @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
+    #   Exchange::Currency.new(40, :usd) <=> Exchange::Currency.new(28, :eur) #=> -1
+    # @example Sort multiple currencies in an array
+    #   [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))
@@ -214,21 +262,27 @@ module Exchange
         
     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
-      # @version 0.2
-      
-      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
+    # 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.
+    # @since 0.3
+    # @version 0.3
+    # @param [Symbol] format :currency (default) if you want a string with currency, :amount if you want just the amount.
+    # @return [String] The formatted string
+    # @example Convert a currency to a string
+    #   Exchange::Currency.new(49.567, :usd).to_s #=> "USD 49.57"
+    # @example Convert a currency without minor to a string
+    #   Exchange::Currency.new(45, :jpy).to_s #=> "JPY 45"
+    # @example Convert a currency with a three decimal minor to a string
+    #   Exchange::Currency.new(34.34, :omr).to_s #=> "OMR 34.340"
+    # @example Convert a currency to a string without the currency
+    #   Exchange::ISO4217.stringif(34.34, :omr).to_s(:iso) #=> "34.340"
+    
+    def to_s format=:currency
+      [
+        format == :currency && ISO4217.stringify(self.value, self.currency),
+        format == :amount && ISO4217.stringify(self.value, self.currency, :amount_only => true)
+      ].detect{|l| l.is_a?(String) }
+    end
   
   end