exchange 0.5.1 → 0.6.0

data/lib/exchange/cache/memcached.rb

@@ -11,42 +11,41 @@ module Exchange
     #     c.cache_host = 'Your memcached host' 
     #     c.cache_port = 'Your memcached port'
     #   end
+    #
     class Memcached < Base
-      class << self
         
-        # instantiates a memcached client and memoizes it in a class variable.
-        # Use this client to access memcached data. For further explanation of use visit the memcached gem documentation
-        # @example
-        #   Exchange::Cache::Memcached.client.set('FOO', 'BAR')
-        # @return [::Memcached] an instance of the memcached client gem class
-        
-        def client
-          @@client ||= ::Memcached.new("#{Configuration.cache_host}:#{Configuration.cache_port}")
-        end
+      # instantiates a memcached client and memoizes it in a class variable.
+      # Use this client to access memcached data. For further explanation of use visit the memcached gem documentation
+      # @example
+      #   Exchange::Cache::Memcached.client.set('FOO', 'BAR')
+      # @return [Dalli::Client] an instance of the dalli gem client class
+      #
+      def client
+        Exchange::GemLoader.new('dalli').try_load unless defined?(::Dalli)
+        @client ||= Dalli::Client.new("#{Exchange.configuration.cache.host}:#{Exchange.configuration.cache.port}")
+      end
+      
+      # returns either cached data from the memcached client or calls the block and caches it in memcached.
+      # 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 the historic time of the exchange rates to be cached
+      # @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
+        result = opts[:plain] ? client.get(key(api, opts)).to_s.gsub(/["\s+]/, '') : JSON.load(client.get(key(api, opts)))
         
-        # returns either cached data from the memcached client or calls the block and caches it in memcached.
-        # 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 the historic time of the exchange rates to be cached
-        # @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?
-          begin
-            result = opts[:plain] ? client.get(key(api, opts)).gsub(/["\s+]/, '') : JSON.load(client.get(key(api, opts)))
-          rescue ::Memcached::NotFound
-            result = block.call
-            if result && !result.to_s.empty?
-              client.set key(api, opts), result.to_json, Configuration.update == :daily ? 86400 : 3600
-            end
+        unless result
+          result = super
+          if result && !result.to_s.empty?
+            client.set key(api, opts), result.to_json, Exchange.configuration.cache.expire == :daily ? 86400 : 3600
           end
-          
-          result
         end
         
+        result
       end
+      
     end
   end
 end

data/lib/exchange/cache/no_cache.rb

@@ -2,32 +2,12 @@ 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
+    # A class to set caching to false
     # 
-    # @version 0.3
+    # @version 0.6
     # @since 0.3
+    #
+    NoCache = Class.new Base
     
-    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

@@ -9,37 +9,37 @@ module Exchange
     #   Exchange::Configuration.define do |c| 
     #     c.cache = :rails
     #   end
+    #
     class Rails < Base
-      class << self
         
-        # returns a Rails cache client. This has not to be stored since rails already memoizes it.
-        # Use this client to access rails cache data. For further explanation of use visit the rails documentation
-        # @example
-        #   Exchange::Cache::Rails.client.set('FOO', 'BAR')
-        # @return [ActiveSupport::Cache::Subclass] an instance of the rails cache class (presumably a subclass of ActiveSupport::Cache)
-        
-        def client
-          ::Rails.cache if defined?(::Rails)
-        end
-        
-        # returns either cached data from the memcached client or calls the block and caches it in rails cache.
-        # 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 the historic time of the exchange rates to be cached
-        # @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
+      # returns a Rails cache client. This has not to be stored since rails already memoizes it.
+      # Use this client to access rails cache data. For further explanation of use visit the rails documentation
+      # @example
+      #   Exchange::Cache::Rails.client.set('FOO', 'BAR')
+      # @return [ActiveSupport::Cache::Subclass] an instance of the rails cache class (presumably a subclass of ActiveSupport::Cache)
+      #
+      def client
+        Exchange::GemLoader.new('rails').try_load unless defined?(::Rails)
+        ::Rails.cache
+      end
+      
+      # returns either cached data from the memcached client or calls the block and caches it in rails cache.
+      # 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 the historic time of the exchange rates to be cached
+      # @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?
         
-        def cached api, opts={}, &block
-          raise CachingWithoutBlockError.new('Caching needs a block') unless block_given?
-          
-          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
+        result = client.fetch key(api, opts), :expires_in => Exchange.configuration.cache.expire == :daily ? 86400 : 3600, &block
+        client.delete(key(api, opts)) unless result && !result.to_s.empty?
         
+        result
       end
+        
     end
   end
 end

data/lib/exchange/cache/redis.rb

@@ -12,43 +12,40 @@ module Exchange
     #     c.cache_port = 'Your redis port (an Integer)'
     #   end
     class Redis < Base
-      class << self
-        
-        # instantiates a redis client and memoizes it in a class variable.
-        # Use this client to access redis data. For further explanation of use visit the redis gem documentation
-        # @example
-        #   Exchange::Cache::Redis.client.set('FOO', 'BAR')
-        # @return [::Redis] an instance of the redis client gem class
-        
-        def client
-          @@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.
-        # 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 the historic time of the exchange rates to be cached
-        # @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?
-          
-          if result = client.get(key(api, opts))
-            result = opts[:plain] ? result.gsub(/["\s+]/, '') : JSON.load(result)
-          else
-            result = block.call
-            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
+              
+      # instantiates a redis client and memoizes it in a class variable.
+      # Use this client to access redis data. For further explanation of use visit the redis gem documentation
+      # @example
+      #   Exchange::Cache::Redis.client.set('FOO', 'BAR')
+      # @return [::Redis] an instance of the redis client gem class
+      #
+      def client
+        Exchange::GemLoader.new('redis').try_load unless defined?(::Redis)
+        @client ||= ::Redis.new(:host => Exchange.configuration.cache.host, :port => Exchange.configuration.cache.port)
+      end
+      
+      # returns either cached data from the redis client or calls the block and caches it in redis.
+      # 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 the historic time of the exchange rates to be cached
+      # @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          
+        if result = client.get(key(api, opts))
+          result = opts[:plain] ? result.gsub(/["\s+]/, '') : JSON.load(result)
+        else
+          result = super
+          if result && !result.to_s.empty?
+            client.set key(api, opts), result.to_json
+            client.expire key(api, opts), Exchange.configuration.cache.expire == :daily ? 86400 : 3600
           end
-          
-          result
         end
         
+        result
       end
+      
     end
   end
 end

data/lib/exchange/configuration.rb

@@ -1,88 +1,182 @@
 module Exchange
+  
+  class << self
+    
+    # A configuration setter for the Exchange gem. This comes in handy if you want to have backup or test setting
+    # @param [Exchange::Configuration] configuration the configuration to install
+    # @raise [ArgumentError] if fed with anything else than an Exchange::Configuration
+    # @return [Exchange::Configuration] The configuration installed
+    #
+    def configuration= configuration
+      if configuration.is_a? Exchange::Configuration
+        @configuration = configuration
+      else
+        raise ArgumentError.new("The configuration needs to be an instance of Exchange::Configuration")
+      end
+    end
+    
+    # A getter for the configuration, returns the currently installed configuration or a default configuration
+    # if no configuration is installed
+    # @return [Exchange::Configuration] The currently installed / the default configuration
+    #
+    def configuration
+      @configuration ||= Configuration.new
+    end
+  end
+  
   # @author Beat Richartz
   # A configuration class 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 
   # retried on failure, and wether operations mixing currencies should raise errors or not
-  # @version 0.1
+  # @version 0.6
   # @since 0.1
-  class Configuration    
+  #
+  class Configuration
+    
     class << self
-      @@config ||= {:api => :xavier_media, :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 
-      # retried on failure, and wether operations mixing currencies should raise errors or not
-      # @version 0.1
-      # @since 0.1
-      # @example Set a configuration by passing a block to the configuration
-      #   Exchange::Configuration.define do |c| 
-      #     c.cache       = :redis
-      #     c.cache_host  = '127.0.0.1'
-      #     c.cache_port  = 6547
-      #     c.api         = :currency_bot
-      #     c.retries     = 1
-      #     c.allow_mixed_operations  = false
-      #     c.update      = :hourly
-      #   end
-      # @yield [Exchange::Configuration] yields a the configuration class
-      # @yieldparam [optional, Symbol] cache The cache type to use. Possible Values: :redis, :memcached or :rails or false to disable caching. Defaults to :memcached
-      # @yieldparam [optional, String] cache_host A string with the hostname or IP to set the cache host to. Does not have to be set for Rails cache
-      # @yieldparam [optional, Integer] cache_port An integer for the cache port. Does not have to be set for Rails cache
-      # @yieldparam [optional, Symbol] api The API to use. Possible Values: :currency_bot (Open Source currency bot API) or :xavier_media (Xavier Media API). Defaults to :currency_bot
-      # @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, :api_app_id, :retries, :cache, :cache_host, :cache_port, :filestore_path, :update, :allow_mixed_operations].each do |m|
-        define_method m do
-          @@config[m]
-        end
-        define_method :"#{m}=" do |data|
-          @@config.merge! m => data
+      private
+        
+        # @private
+        # @macro [setter] install_setter
+        #
+        def install_setter key
+          define_method :"#{key}=" do |data|
+            @config[key] = DEFAULTS[key].merge(data)
+          end
         end
-      end
-      
-      # The instantiated api class according to the configuration
-      # @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(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(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
+        # @private
+        # @macro [getter] install_getter
+        #
+        def install_getter key, parent_module
+          define_method key do
+            @config[key] = OpenStruct.new(@config[key]) unless @config[key].is_a?(OpenStruct)
+            @config[key].subclass = parent_module.const_get camelize(@config[key].subclass) unless @config[key].subclass.is_a?(Class)
+            @config[key]
+          end
         end
-      end
+        
+    end
+    
+    # The configuration defaults
+    # @version 0.6
+    # @since 0.6
+    #
+    DEFAULTS = { 
+                  :api => {
+                    :subclass => ExternalAPI::XavierMedia, 
+                    :retries => 5
+                  },
+                  :cache => {
+                    :subclass => Cache::Memcached,
+                    :host => 'localhost',
+                    :port => 11211,
+                    :expire => :daily
+                  },
+                  :allow_mixed_operations => true
+                }
+    
+    # Initialize a new configuration. Takes a hash and/or a block. Lets you easily set the configuration the way you want it to be
+    # @version 0.6
+    # @since 0.6
+    # @param [Hash] configuration The configuration as a hash
+    # @param [Proc] block A block to yield the configuration with
+    # @example Define the configuration with a hash
+    #   Exchange::Configuration.new(:allow_mixed_operations => false, :api => {:subclass => :currency_bot, :retries => 2})
+    # @example Define the configuration with a block
+    #   Exchange::Configuration.new do |c|
+    #     c.allow_mixed_operations = false
+    #     c.cache = {
+    #       :subclass => Cache::Redis,
+    #       :expire => :hourly
+    #     }
+    #
+    # @yield [Exchange::Configuration] yields an instance of the configuration class
+    # @yieldparam [optional, Symbol] cache The cache type to use. Possible Values: :redis, :memcached or :rails or false to disable caching. Defaults to :memcached
+    # @yieldparam [optional, String] cache_host A string with the hostname or IP to set the cache host to. Does not have to be set for Rails cache
+    # @yieldparam [optional, Integer] cache_port An integer for the cache port. Does not have to be set for Rails cache
+    # @yieldparam [optional, Symbol] api The API to use. Possible Values: :currency_bot (Open Source currency bot API) or :xavier_media (Xavier Media API). Defaults to :currency_bot
+    # @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.
+    #
+    def initialize configuration={}, &block
+      @config = DEFAULTS.merge(configuration)
+      self.instance_eval(&block) if block_given?
+      super()
     end 
+    
+    # Getter for the mixed operations configuration. If set to true, operations with mixed currencies will not raise errors
+    # If set to false, mixed operations will raise errors
+    # @since 0.6
+    # @version 0.6
+    # @return [Boolean] True if mixed operations are allowed, false if not
+    #
+    def allow_mixed_operations
+      @config[:allow_mixed_operations]
+    end
+    
+    # Setter for the mixed operations configuration. If set to true, operations with mixed currencies will not raise errors
+    # If set to false, mixed operations will raise errors
+    # @since 0.6
+    # @version 0.6
+    # @param [Boolean] data The configuration to set
+    # @return [Boolean] The configuration set
+    #
+    def allow_mixed_operations= data
+      @config[:allow_mixed_operations] = data
+    end
+    
+    # Setter for the api configuration.
+    # @since 0.6
+    # @version 0.6
+    # @param [Hash] The hash to set the configuration to
+    # @option [Symbol] :subclass The API subclass to use as a underscored symbol (will be camelized and constantized)
+    # @option [Integer] :retries The amount of retries on connection failure
+    # @example set the api to be ecb with a maximum of 8 retries on connection failure
+    #   configuration.api = { :subclass => :ecb, :retries => 8 }
+    #
+    install_setter :api
+    
+    # Setter for the cache configuration.
+    # @since 0.6
+    # @version 0.6
+    # @param [Hash] The hash to set the configuration to
+    # @option [Symbol] :subclass The Cache subclass to use as a underscored symbol (will be camelized and constantized)
+    # @option [String] :host The cache connection host
+    # @option [Integer] :port The cache connection port
+    # @option [Symbol] :expire The expiration period for the cache, can be :daily or :hourly, defaults to daily
+    # @example set the cache to be redis on localhost:6578 with hourly expiration
+    #   configuration.cache = { :subclass => :redis, :host => 'localhost', :port => 6578, :expire => :hourly }
+    #
+    install_setter :cache
+    
+    # Getter for the api configuration. Instantiates the configuration as an open struct, if called for the first time.
+    # Also camelizes and constantizes the api subclass, if used for the first time.
+    # @return [OpenStruct] an openstruct with the complete api configuration
+    #
+    install_getter :api, ExternalAPI
+    
+    # Getter for the cache configuration. Instantiates the configuration as an open struct, if called for the first time.
+    # Also camelizes and constantizes the cache subclass, if used for the first time.
+    # @return [OpenStruct] an openstruct with the complete cache configuration
+    #
+    install_getter :cache, Cache
+
+    private
+      
+      # Camelize a string or a symbol
+      # @param [String, Symbol] s The string to camelize
+      # @return [String] a camelized string
+      # @example Camelize an underscored symbol
+      #   camelize(:some_thing) #=> "SomeThing"
+      #
+      def camelize s
+        s = s.to_s.gsub(/(?:^|_)(.)/) { $1.upcase }
+      end
+      
   end
 end