exchange 0.6.0 → 0.8.0

data/exchange.gemspec

@@ -1,107 +1,27 @@
-# Generated by jeweler
-# DO NOT EDIT THIS FILE DIRECTLY
-# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
+$LOAD_PATH << File.join(File.dirname(__FILE__), 'lib')
+require 'exchange/base'
 
 Gem::Specification.new do |s|
-  s.name = "exchange"
-  s.version = "0.6.0"
-
-  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.authors = ["Beat Richartz"]
-  s.date = "2012-10-04"
-  s.description = "The Exchange Gem gives you easy access to currency functions directly on your Numbers. Imagine a conversion as easy as \n    1.eur.to_usd\n  or even better \n    1.eur.to_usd(:at => Time.now - 84600)\n  which gets you an exchange at the rates of yesterday."
-  s.email = "exchange_gem@gmail.com"
-  s.extra_rdoc_files = [
-    "LICENSE.txt",
-    "README.rdoc"
-  ]
-  s.files = [
-    ".document",
-    ".rspec",
-    ".travis.yml",
-    "Gemfile",
-    "Gemfile.lock",
-    "LICENSE.txt",
-    "README.rdoc",
-    "Rakefile",
-    "VERSION",
-    "changelog.rdoc",
-    "exchange.gemspec",
-    "iso4217.yml",
-    "lib/core_extensions/conversability.rb",
-    "lib/exchange.rb",
-    "lib/exchange/base.rb",
-    "lib/exchange/cache.rb",
-    "lib/exchange/cache/base.rb",
-    "lib/exchange/cache/file.rb",
-    "lib/exchange/cache/memcached.rb",
-    "lib/exchange/cache/no_cache.rb",
-    "lib/exchange/cache/rails.rb",
-    "lib/exchange/cache/redis.rb",
-    "lib/exchange/configuration.rb",
-    "lib/exchange/currency.rb",
-    "lib/exchange/external_api.rb",
-    "lib/exchange/external_api/base.rb",
-    "lib/exchange/external_api/call.rb",
-    "lib/exchange/external_api/currency_bot.rb",
-    "lib/exchange/external_api/ecb.rb",
-    "lib/exchange/external_api/json.rb",
-    "lib/exchange/external_api/xavier_media.rb",
-    "lib/exchange/external_api/xml.rb",
-    "lib/exchange/gem_loader.rb",
-    "lib/exchange/helper.rb",
-    "lib/exchange/iso_4217.rb",
-    "spec/core_extensions/conversability_spec.rb",
-    "spec/exchange/cache/base_spec.rb",
-    "spec/exchange/cache/file_spec.rb",
-    "spec/exchange/cache/memcached_spec.rb",
-    "spec/exchange/cache/no_cache_spec.rb",
-    "spec/exchange/cache/rails_spec.rb",
-    "spec/exchange/cache/redis_spec.rb",
-    "spec/exchange/configuration_spec.rb",
-    "spec/exchange/currency_spec.rb",
-    "spec/exchange/external_api/base_spec.rb",
-    "spec/exchange/external_api/call_spec.rb",
-    "spec/exchange/external_api/currency_bot_spec.rb",
-    "spec/exchange/external_api/ecb_spec.rb",
-    "spec/exchange/external_api/xavier_media_spec.rb",
-    "spec/exchange/gem_loader_spec.rb",
-    "spec/exchange/helper_spec.rb",
-    "spec/exchange/iso_4217_spec.rb",
-    "spec/spec_helper.rb",
-    "spec/support/api_responses/example_ecb_xml_90d.xml",
-    "spec/support/api_responses/example_ecb_xml_daily.xml",
-    "spec/support/api_responses/example_ecb_xml_history.xml",
-    "spec/support/api_responses/example_historic_json.json",
-    "spec/support/api_responses/example_json_api.json",
-    "spec/support/api_responses/example_xml_api.xml"
-  ]
-  s.homepage = "http://github.com/beatrichartz/exchange"
-  s.licenses = ["MIT"]
-  s.require_paths = ["lib"]
-  s.rubygems_version = "1.8.24"
-  s.summary = "Simple Exchange Rate operations for your ruby app"
-
-  if s.respond_to? :specification_version then
-    s.specification_version = 3
-
-    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<exchange>, [">= 0"])
-      s.add_development_dependency(%q<yard>, ["~> 0.7.4"])
-      s.add_development_dependency(%q<bundler>, [">= 1.0.0"])
-      s.add_development_dependency(%q<jeweler>, ["~> 1.8.3"])
-    else
-      s.add_dependency(%q<exchange>, [">= 0"])
-      s.add_dependency(%q<yard>, ["~> 0.7.4"])
-      s.add_dependency(%q<bundler>, [">= 1.0.0"])
-      s.add_dependency(%q<jeweler>, ["~> 1.8.3"])
-    end
-  else
-    s.add_dependency(%q<exchange>, [">= 0"])
-    s.add_dependency(%q<yard>, ["~> 0.7.4"])
-    s.add_dependency(%q<bundler>, [">= 1.0.0"])
-    s.add_dependency(%q<jeweler>, ["~> 1.8.3"])
-  end
+  s.name              = "exchange"
+  s.version           = Exchange::VERSION
+  s.authors           = ["Beat Richartz"]
+  s.date              = "2012-10-09"
+  s.description       = "The Exchange Gem gives you easy access to currency functions directly on your Numbers. Imagine a conversion as easy as \n    1.eur.to_usd\n  or even better \n    1.eur.to_usd(:at => Time.now - 84600)\n  which gets you an exchange at the rates of yesterday."
+  s.email             = "exchange_gem@gmail.com"
+  s.homepage          = "http://github.com/beatrichartz/exchange"
+  s.licenses          = ["MIT"]
+  s.require_paths     = ["lib"]
+  s.rubygems_version  = "1.8.24"
+  s.summary           = "Simple Exchange Rate operations for your ruby app"
+  
+  s.files             = `git ls-files`.split("\n")
+  s.test_files        = `git ls-files -- spec/*`.split("\n")
+  s.executables       = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths     = ["lib"]
+  
+  s.add_dependency             "json", ">= 1.0.0"
+  s.add_development_dependency "yard", ">= 0.7.4"
+  s.add_development_dependency "bundler", ">= 1.0.0"
 end
 

data/lib/core_extensions/conversability.rb

@@ -24,6 +24,9 @@ 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>
     #
+    # @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)
@@ -33,6 +36,5 @@ module Exchange
   end
 end
 
-Fixnum.send     :include, Exchange::Conversability
-Float.send      :include, Exchange::Conversability
-BigDecimal.send :include, Exchange::Conversability
+# include the Conversability methods in all number operations. Stack traces will indicate the module if something goes wrong.
+Numeric.send :include, Exchange::Conversability

data/lib/exchange/base.rb

@@ -2,7 +2,7 @@ module Exchange
   
   # The current version of the exchange gem
   #
-  VERSION = '0.6.0'
+  VERSION = '0.8.0'
   
   # The root installation path of the gem
   # @version 0.5

data/lib/exchange/cache/base.rb

@@ -7,15 +7,23 @@ module Exchange
   # @example Write your own caching module
   #   module Cache
   #     class MyCustomCache < Base
-  #       # a cache class has to have the class method "cached"
+  #       # A cache class has to have the method "cached".
+  #       # The cache Base is a singleton and forwards the method "cached"
+  #       # to the instance
+  #       #
   #       def cached api, opts={}, &block
-  #         # generate the key with key(api, opts[:at]) and you will get a unique key to store in your cache
+  #         # generate the storage with key(api, opts[:at]) and you will get a 
+  #         # unique key to store in your cache
+  #         #
   #         # Your code goes here
   #       end
   #     end
   #   end
+  #
   #   # Now, you can configure your Caching solution in the configuration. The Symbol will get camelcased and constantized
-  #   configuration.cache.subclass = :my_custom_cache
+  #   #
+  #   Exchange.configuration.cache.subclass = :my_custom_cache
+  #
   #   # Have fun, and don't forget to write tests.
   
   module Cache

data/lib/exchange/cache/memcached.rb

@@ -30,11 +30,12 @@ module Exchange
       # @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
+      # @yield [] This method takes a mandatory block with an arity of 0 for caching
       # @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)))
+        stored = client.get(key(api, opts))
+        result = opts[:plain] ? stored.to_s.gsub(/["\s+]/, '') : JSON.load(stored) if stored && !stored.empty?
         
         unless result
           result = super

data/lib/exchange/configuration.rb

@@ -52,9 +52,10 @@ module Exchange
         #
         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]
+            config_part = @config[key]
+            config_part = OpenStruct.new(config_part) unless config_part.is_a?(OpenStruct)
+            config_part.subclass = parent_module.const_get camelize(config_part.subclass) unless config_part.subclass.is_a?(Class)
+            @config[key] = config_part
           end
         end
         
@@ -89,20 +90,10 @@ module Exchange
     #   Exchange::Configuration.new do |c|
     #     c.allow_mixed_operations = false
     #     c.cache = {
-    #       :subclass => Cache::Redis,
+    #       :subclass => Exhange::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?

data/lib/exchange/currency.rb

@@ -1,6 +1,6 @@
 # Top Level Module of the the gem.
 # @author Beat Richartz
-# @version 0.1
+# @version 0.7
 # @since 0.1
 
 module Exchange
@@ -32,6 +32,10 @@ module Exchange
     #
     attr_reader :from
     
+    # @attr_reader
+    # @return [Exchange::ExternalAPI] The current api subclass
+    attr_reader :api
+    
     # Intialize the currency with a number and a currency
     # @param [Integer, Float] number The number the currency is instantiated from
     # @param [String, Symbol] currency The currency the currency object is in
@@ -52,6 +56,7 @@ module Exchange
       @currency         = currency
       @time             = Helper.assure_time(opts[:at], :default => :now)
       @from             = opts[:from]
+      @api              = Exchange.configuration.api.subclass
     end
     
     # Method missing is used to handle conversions from one currency object to another. It only handles currencies which are available in
@@ -62,14 +67,16 @@ module Exchange
     #   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 && 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")
+      match    = method.to_s.match /\Ato_(\w{3})$/
+      currency = $1
+      
+      if match && api_supports_currency?(currency)
+        return convert_to currency, { :at => time }.merge(args.first || {})
+      elsif match
+        test_for_no_rate_error(currency)
       end
 
-      self.value.send method, *args, &block
+      value.send method, *args, &block
     end
     
     # Converts this instance of currency into another currency
@@ -95,21 +102,20 @@ module Exchange
         #
         def install_operation op
           define_method op do |*precision|
-            @value = ISO4217.send(op, self.value, self.currency, precision.first)
-            self
+            Exchange::Currency.new(ISO4217.send(op, self.value, self.currency, precision.first), currency, :at => time, :from => self)
           end
         end
       
         # @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 !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
+              test_for_currency_mix_error(other)
+              new_value = value #{op} (other.kind_of?(Currency) ? other.convert_to(self.currency, :at => other.time) : other)
+              Exchange::Currency.new(new_value, currency, :at => time, :from => self)
             end
           EOV
         end
@@ -121,7 +127,7 @@ module Exchange
     # @return [Exchange::Currency] The currency you started with with a rounded value
     # @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
+    # @version 0.7.1
     # @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>
@@ -137,7 +143,7 @@ module Exchange
     # @return [Exchange::Currency] The currency you started with with a ceiled value
     # @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
+    # @version 0.7.1
     # @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>
@@ -153,7 +159,7 @@ module Exchange
     # @return [Exchange::Currency] The currency you started with with a floored value
     # @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
+    # @version 0.7.1
     # @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>
@@ -175,6 +181,8 @@ module Exchange
     # @example Configuration allows mixed operations (default)
     #   Exchange::Currency.new(20,:nok) + Exchange::Currency.new(20,:sek)
     #     #=> #<Exchange::Currency @value=37.56 @currency=:nok>
+    # @since 0.1
+    # @version 0.7
     #
     base_operation '+'
     
@@ -189,6 +197,8 @@ module Exchange
     # @example Configuration allows mixed operations (default)
     #   Exchange::Currency.new(20,:nok) - Exchange::Currency.new(20,:sek)
     #     #=> #<Exchange::Currency @value=7.56 @currency=:nok>
+    # @since 0.1
+    # @version 0.7
     #
     base_operation '-'
     
@@ -203,6 +213,8 @@ module Exchange
     # @example Configuration allows mixed operations (default)
     #   Exchange::Currency.new(20,:nok) * Exchange::Currency.new(20,:sek)
     #     #=> #<Exchange::Currency @value=70.56 @currency=:nok>
+    # @since 0.1
+    # @version 0.7
     #
     base_operation '*'
     
@@ -217,6 +229,8 @@ module Exchange
     # @example Configuration allows mixed operations (default)
     #   Exchange::Currency.new(20,:nok) / Exchange::Currency.new(20,:sek)
     #     #=> #<Exchange::Currency @value=1.56 @currency=:nok>
+    # @since 0.1
+    # @version 0.7
     #
     base_operation '/'
     
@@ -230,6 +244,8 @@ 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
+    # @since 0.1
+    # @version 0.6
     #
     def == other
       if is_same_currency?(other)
@@ -246,7 +262,7 @@ module Exchange
     # @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
+    # @version 0.6
     # @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
@@ -254,7 +270,7 @@ module Exchange
     #   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
       if is_same_currency?(other)
         self.value <=> other.value
@@ -279,7 +295,7 @@ module Exchange
     #   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),
@@ -292,6 +308,8 @@ module Exchange
       # 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
+      # @since 0.6
+      # @version 0.6
       #
       def is_currency? other
         other.is_a?(Exchange::Currency)
@@ -300,6 +318,8 @@ module Exchange
       # 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
+      # @since 0.6
+      # @version 0.6
       #
       def is_same_currency? other
         is_currency?(other) && other.currency == self.currency
@@ -308,10 +328,40 @@ module Exchange
       # 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
+      # @since 0.6
+      # @version 0.6
       #
       def is_other_currency? other
         is_currency?(other) && other.currency != self.currency
       end
+      
+      # determine wether the chosen api supports converting the given currency
+      # @param [String] currency The currency to test the api for
+      # @return [Boolean] True if the api supports the given currency, false if not
+      #
+      def api_supports_currency? currency
+        api::CURRENCIES.include?(currency)
+      end
+      
+      # Test if another currency is used in an operation, and if so, if the operation is allowed
+      # @param [Numeric, Exchange::Currency] other The counterpart in the operation
+      # @raise [CurrencyMixError] an error if mixing currencies is not allowed and currencies where mixed
+      # @since 0.6
+      # @version 0.6
+      #
+      def test_for_currency_mix_error 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 !Exchange.configuration.allow_mixed_operations && other.kind_of?(Currency) && other.currency != self.currency
+      end
+      
+      # Helper method to raise a no rate error for a given currency if no rate is given
+      # @param [String] currency a possible currency
+      # @raise [NoRateError] an error indicating that the given string is a currency, but no rate is present
+      # @since 0.7.2
+      # @version 0.7.2
+      #
+      def test_for_no_rate_error currency
+        raise NoRateError.new("Cannot convert to #{currency} because the defined api does not provide a rate") if ISO4217.definitions.keys.include?(currency.upcase)
+      end
   
   end