exchange 0.6.0 → 0.8.0

data/.gitignore

@@ -0,0 +1,54 @@
+.rvmrc
+
+# rcov generated
+coverage
+coverage.data
+
+# rdoc generated
+rdoc
+
+# yard generated
+doc
+.yardoc
+
+# bundler
+.bundle
+
+# filestore
+exchange_filestore
+
+# jeweler generated
+pkg
+
+# Have editor/IDE/OS specific files you need to ignore? Consider using a global gitignore: 
+#
+# * Create a file at ~/.gitignore
+# * Include files you want ignored
+# * Run: git config --global core.excludesfile ~/.gitignore
+#
+# After doing this, these files will be ignored in all your git projects,
+# saving you from having to 'pollute' every project you touch with them
+#
+# Not sure what to needs to be ignored for particular editors/OSes? Here's some ideas to get you started. (Remember, remove the leading # of the line)
+#
+# For MacOS:
+#
+#.DS_Store
+
+# For TextMate
+#*.tmproj
+#tmtags
+
+# For emacs:
+#*~
+#\#*
+#.\#*
+
+# For vim:
+#*.swp
+
+# For redcar:
+#.redcar
+
+# For rubinius:
+#*.rbc

data/.travis.yml

@@ -4,4 +4,8 @@ rvm:
   - 1.9.2
   - 1.9.3
   - ree
+  - rbx-18mode
+  - rbx-19mode
+  - jruby
+  
 script: bundle exec rspec

data/Gemfile

@@ -1,26 +1,15 @@
 source "http://rubygems.org"
-# Add dependencies required to use your gem here.
-# Example:
-#gem "nokogiri",   ">= 1.5.0"
-#gem "json",       ">= 1.6.5"
-#gem "memcached",  ">= 1.3.0"
-#gem "redis",      ">= 2.2.0"
-
-# Add dependencies to develop your gem here.
-# Include everything needed to run rake, tests, features, etc.
 
 gemspec
 
 group :development do
-  gem "yard",       "~> 0.7.4"
+  gem "yard",       ">= 0.7.4"
   gem "bundler",    ">= 1.0.0"
-  gem "jeweler",    "~> 1.8.3"
 end
 
 group :test do
   gem "nokogiri",   ">= 1.5.0", :require => false
   gem "dalli",      ">= 2.0.0", :require => false
   gem "redis",      ">= 2.2.0", :require => false
-  gem "shoulda",    ">= 0"
   gem "rspec"
 end

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    exchange (0.6.0)
+    exchange (0.7.6)
       json (>= 1.0.0)
 
 GEM
@@ -9,43 +9,29 @@ GEM
   specs:
     dalli (2.2.1)
     diff-lcs (1.1.3)
-    git (1.2.5)
-    jeweler (1.8.3)
-      bundler (~> 1.0)
-      git (>= 1.2.5)
-      rake
-      rdoc
-    json (1.6.6)
+    json (1.7.5)
     nokogiri (1.5.5)
-    rake (0.9.2.2)
-    rdoc (3.12)
-      json (~> 1.4)
-    redis (3.0.1)
-    rspec (2.9.0)
-      rspec-core (~> 2.9.0)
-      rspec-expectations (~> 2.9.0)
-      rspec-mocks (~> 2.9.0)
-    rspec-core (2.9.0)
-    rspec-expectations (2.9.1)
+    nokogiri (1.5.5-java)
+    redis (3.0.2)
+    rspec (2.11.0)
+      rspec-core (~> 2.11.0)
+      rspec-expectations (~> 2.11.0)
+      rspec-mocks (~> 2.11.0)
+    rspec-core (2.11.1)
+    rspec-expectations (2.11.3)
       diff-lcs (~> 1.1.3)
-    rspec-mocks (2.9.0)
-    shoulda (3.0.1)
-      shoulda-context (~> 1.0.0)
-      shoulda-matchers (~> 1.0.0)
-    shoulda-context (1.0.0)
-    shoulda-matchers (1.0.0)
-    yard (0.7.5)
+    rspec-mocks (2.11.3)
+    yard (0.8.2.1)
 
 PLATFORMS
+  java
   ruby
 
 DEPENDENCIES
   bundler (>= 1.0.0)
   dalli (>= 2.0.0)
   exchange!
-  jeweler (~> 1.8.3)
   nokogiri (>= 1.5.0)
   redis (>= 2.2.0)
   rspec
-  shoulda
-  yard (~> 0.7.4)
+  yard (>= 0.7.4)

data/README.rdoc

@@ -1,68 +1,58 @@
-= exchange {<img src="https://secure.travis-ci.org/beatrichartz/exchange.png" />}[http://travis-ci.org/beatrichartz/exchange]
+= exchange {<img src="https://secure.travis-ci.org/beatrichartz/exchange.png" />}[http://travis-ci.org/beatrichartz/exchange] {<img src="https://gemnasium.com/beatrichartz/exchange.png" alt="Dependency Status" />}[https://gemnasium.com/beatrichartz/exchange] {<img src="https://codeclimate.com/badge.png" />}[https://codeclimate.com/github/beatrichartz/exchange]
 
-The Exchange Gem gives you easy access to currency functions directly on your Numbers. It has been tested against ruby 1.8.7, ree, ruby 1.9.2 and 1.9.3. You can use it with just plain ruby projects, in Rails 2 and 3, Sinatra or whatever Framework you like.
+The Exchange Gem gives you easy access to currency functions directly on your Numbers. {It is tested against}[http://travis-ci.org/beatrichartz/exchange]: ruby 1.9, ruby 1.8.7, ree, rubinius (1.8 and 1.9 mode) and jruby 
 
-=== Changelog
+You can use it with just plain ruby projects, in Rails 2 and 3, Sinatra or whatever Framework you like.
 
-== 0.6
-- Memcached, Redis, JSON and Nokogiri have been removed as explicit dependencies of the gem. The gem will now try to load the gems
-you want to use with it during runtime, and it will throw an exception if a gem required according to your configuration is not present.
-- The cache class is now a singleton and no class singleton anymore. This makes it easier to write a seamlessly integrating custom cache class for it.
-== 0.5
-- Changed the currency bot api to openexchangerates.org and changed the default api to xaviermedia. Since the openexchangerates.org api still supports a free plan with reasonable conditions, it will still be supported by the exchange gem, although it may be moved to a separate gem in the future
-== 0.4
-- Some potential 0 values on conversions when caching with memcached have been fixed.
-== 0.3
-- The ECB API has been added to the standard apis
-
-==== Features
+== Features
 
 === Easy Conversion
 
-Imagine a conversion as easy as 
+Conversion of currencies does not get any easier
   1.eur.to_usd
-or even better 
+or better for historic dates
   1.eur.to_usd(:at => Time.now - 84600)
-which gets you an exchange at the rates of yesterday.
 
 === Only one request per day to keep you up to date
 
-You're hitting the internet only daily to get new rates with this gem (hourly updates are available if you're eager to have the absolutely newest ones)
+You're hitting the internet only daily to get new rates (hourly updates are available if you're eager to have the absolutely newest ones)
 
 === ISO 4217 Currency formatting
 On of the issues with currencies is: You never know the format they should be in. With Exchange, you can just use the currencies
-to_s method, which takes care of the right format for you. A version with symbols is under construction. You can either have a
-a string with the currency code in front, or just the amount in the right format
+to_s method, which takes care of the right format for you. You can either have a string with the currency code in front, or just the amount in the right format
 
   Exchange::Currency.new(49.567, :usd).to_s           #=> "USD 49.57"
   Exchange::Currency.new(45, :jpy).to_s               #=> "JPY 45"
   Exchange::Currency.new(34.34, :omr).to_s            #=> "OMR 34.340"
   Exchange::ISO4217.stringif(34.34, :omr).to_s(:iso)  #=> "34.340"
 
-=== Use three great APIs or your own great API
+
+=== Use three great APIs or your own
 
 Three open APIs are already included: 
 
-- Xaviermedia (http://www.xavierforum.com/viewtopic.php?f=5&t=10979&sid=671a685edbfa5dbec219fbc6793d5057)
-- European Central Bank (http://www.ecb.int/stats/exchange/eurofxref/html/index.en.html)
-- Currency Bot (http://currencybot.github.com/)
+- {Xaviermedia}[http://www.xavierforum.com/viewtopic.php?f=5&t=10979&sid=671a685edbfa5dbec219fbc6793d5057]
+- {European Central Bank}[http://www.ecb.int/stats/exchange/eurofxref/html/index.en.html]
+- {Currency Bot}[http://currencybot.github.com/]
 
-but if you have another API you like to use, it becomes as easy as writing one Class and two methods to use it with the Exchange gem. Just visit the documentation here: http://rubydoc.info/github/beatrichartz/exchange/Exchange/ExternalAPI to see an example of a custom API Extension
+but if you have another API you like to use, it becomes as easy as writing one Class and two methods to use it. 
+{Example of a custom API Extension}[http://rubydoc.info/github/beatrichartz/exchange/Exchange/ExternalAPI]
 
 === Use great caches or your own great cache
 
-Also, the gem allows you to use one of three available caching solutions: 
+Use one of three available caching solutions: 
 
-- Memcached via the Memcached gem
+- Memcached via the Dalli gem
 - Redis via the redis gem
 - Rails cache (This gem does however not depend on rails)
 
-But, same here, if you don't like any of these or want to use your own caching solution, it is as easy as writing one Class and two methods to use it with Exchange. Just visit the documentation here: http://rubydoc.info/github/beatrichartz/exchange/Exchange/Cache for an example of a cache extension
+But, same here, if you don't like any of these or want to use your own caching solution, it is as easy as writing one Class and two methods to use it. 
+{Example of a custom cache extension}[http://rubydoc.info/github/beatrichartz/exchange/Exchange/Cache]
 
 == Installation
 === Bundler / Rails
 Add it to your Gemfile  
-  gem "exchange", ">=0.2.6"
+  gem "exchange", ">=0.7.3"
 === Manually
 Just install it as a gem
   gem install exchange
@@ -157,7 +147,7 @@ Access the original currency and its value after conversion, even over multiple
 
 You can configure the exchange gem to a variety of options, allowing you to control restrictions on operations, caching and which API the gem uses. Just set the configuration with
 
-  Exchange::Configuration.define do |c|
+  Exchange.configuration = Exchange::Configuration.new do |c|
     # your configuration goes here
   end
   
@@ -166,49 +156,64 @@ You can configure the exchange gem to a variety of options, allowing you to cont
 
 The options available are
   
-  :cache (default :memcached)               The cache type to use. Possible Values: :redis, :memcached or :rails or false to disable caching
-  :cache_host (default '127.0.0.1')         A string with the hostname or IP to set the cache host to. Does not have to be set for Rails cache
-  :cache_port (default 11211)               An integer for the cache port. Does not have to be set for Rails cache
-  :api (default :currency_bot)              The API to use. Possible Values: :currency_bot (Open Source currency bot API) or :xavier_media (Xavier Media API)
-  :retries (default 5)                      The number of times the gem should retry to connect to the api host
+  :cache                                    Takes the cache options as a hash, the options are:
+    :subclass (default :memcached)          The cache subclass to use for caching. Available: Rails cache, Redis, Memcached, Filecache
+    :host (default '127.0.0.1')             A string with the hostname or IP to set the cache host to. Does not have to be set for Rails cache
+    :port (default 11211)                   An integer for the cache port. Does not have to be set for Rails cache
+    :expire (default :daily)                Which period is used to expire the cache, :daily or :hourly are available
+    
+  :api                                      Takes the conversion api as a hash, the options are:
+    :subclass (default :xavier_media)         The api to use. Available: Xavier Media, ECB, Currency Bot
+    :retries (default 5)                      The number of times the gem should retry to connect to the api host
+    :app_id (default nil)                     The app id to use with your api request
+    
   :allow_mixed_opterations (default true)   If set to false, Operations with with different currencies raise errors.
-  :update (default :daily)                  The regularity of updates for the API. Possible values: :daily, :hourly.
 
-If your afraid of mixed currency operations, just don't allow them
-  Exchange::Configuration.allow_mixed_operations = false
+If you're afraid of mixed currency operations, just don't allow them
+  Exchange.configuration.allow_mixed_operations = false
   1.usd + 1.eur                                 #=> MixedCurrencyError
 
 === Caching Options  
 
 Use Memcached to cache the result (default). Exchange will cache the API files with a key starting with 'exchange_'
-  Exchange::Configuration.define do |c|
-    c.cache = :memcached
-    c.cache_host = 'yourhost'
-    c.cache_port = 2423 #your port
+  Exchange.configuration = Exchange::Configuration.new do |c|
+    c.cache = {
+      :subclass => :memcached,
+      :host     => 'yourhost',
+      :port     => 2434, #yourport
+    }
   end
 
 Use Redis to cache the result. Exchange will cache the API files with a key starting with 'exchange_'
-  Exchange::Configuration.define do |c|
-    c.cache = :redis
-    c.cache_host = 'yourhost'
-    c.cache_port = 2423 #your port
+  Exchange.configuration = Exchange::Configuration.new do |c|
+    c.cache = {
+      :subclass => :redis,
+      :host     => 'yourhost',
+      :port     => 2434, #yourport
+    }
   end
 
 Use Rails to cache the result. Exchange will cache the API files with a key starting with 'exchange_'
-  Exchange::Configuration.define do |c|
-    c.cache = :rails
+  Exchange.configuration = Exchange::Configuration.new do |c|
+    c.cache = {
+      :subclass => :rails
+    }
   end
   
 === API Options
 
-Use the currencybot Open Source API as a source of your conversion rates (default)
-  Exchange::Configuration.define do |c|
-    c.api = :currency_bot
+Use the Xaviermedia API as the source of your conversion rates
+  Exchange.configuration = Exchange::Configuration.new do |c|
+    c.api = {
+      :subclass => :xavier_media
+    }
   end
 
-Use the Xaviermedia API as the source of your conversion rates
-  Exchange::Configuration.define do |c|
-    c.api = :xavier_media
+Use the currencybot Open Source API as a source of your conversion rates
+  Exchange.configuration = Exchange::Configuration.new do |c|
+    c.api = {
+      :subclass => :currency_bot
+    }
   end
   
 == Connect your own API and Cache
@@ -222,21 +227,36 @@ Easily connect to your custom API by writing an ExternalAPI Class, or use your o
         # Define here which currencies your API can handle
         CURRENCIES = %W(usd chf)
         
-        # Every instance of ExternalAPI Class has to have an update function which gets the rates from the API
+        # Every instance of ExternalAPI Class has to have an update function which gets 
+        # the rates from the API
+        #
         def update(opts={})
           # assure that you will get a Time object for the historical dates
+          #
           time = assure_time(opts[:at]) 
 
-          # call your API (shown here with a helper function that builds your API URL). Like this, your calls will get cached.
+          # Call your API (shown here with a helper function that builds your API URL). 
+          # Like this, your calls will get cached.
+          #
           Call.new(api_url(time), :at => time) do |result|
 
-            # assign the currency conversion base, attention, this is readonly, so don't do self.base = 
+            # Assign the currency conversion base.
+            # Attention, this is readonly, self.base= won't work
+            #
             @base                 = result['base']
 
-            # assign the rates, this has to be a hash with the following format: {'USD' => 1.23242, 'CHF' => 1.34323}. Attention, this is readonly.
+            # assign the rates, this has to be a hash with the following format: 
+            # {'USD' => 1.23242, 'CHF' => 1.34323}. 
+            #
+            # Attention, this is readonly, self.rates= won't work
+            #
             @rates                = result['rates']
 
-            # timestamp the api call result. This may come in handy to assure you have the right result. Attention, this is readonly.
+            # Timestamp the api call result. This may come in handy to assure you have 
+            # the right result. 
+            #
+            # Attention, this is readonly, self.timestamp= won't work
+            #
             @timestamp            = result['timestamp'].to_i
           end
         end
@@ -253,7 +273,7 @@ Easily connect to your custom API by writing an ExternalAPI Class, or use your o
 
 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.
 
@@ -262,19 +282,22 @@ Have fun, and don't forget to write tests.
 Write your own caching module to use the gem with your own custom caching solution.
   module Cache
     class MyCustomCache < Base
-      class << self
-        # a cache class has to have the class method "cached"
-        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
-          # Your code goes here
-        end
+      # 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 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
 
-  Exchange::Configuration.cache = :my_custom_cache
+  Exchange.configuration.cache.subclass = :my_custom_cache
 
 Have fun, and don't forget to write tests.
 

data/changelog.rdoc

@@ -1,6 +1,25 @@
 = Changes to Exchange
 
-== 0.3.0
+== 0.7.3
+- jruby compatibility, horray!
+
+== 0.7.1
+- The DSL is now included into Numeric, which makes currency operations available for all subclasses (including your own) of Numeric
+- Some structurally unsound behaviour with ruby base operators (+, -, *, /, round, floor, ceil) has been corrected. It is recommended to update to this latest version of exchange if you are using a version less than 0.7.1. 
+- the api classes have been refactored to less complex, more readable code, 
+- general performance has improved quite a bit.
+
+== 0.6
+- Memcached, Redis, JSON and Nokogiri have been removed as explicit dependencies of the gem. The gem will now try to load the gems you want to use with it during runtime, and it will throw an exception if a gem required according to your configuration is not present.
+- The cache class is now a singleton and no class singleton anymore. This makes it easier to write a seamlessly integrating custom cache class for it.
+
+== 0.5
+- Changed the currency bot api to openexchangerates.org and changed the default api to xaviermedia. Since the openexchangerates.org api still supports a free plan with reasonable conditions, it will still be supported by the exchange gem, although it may be moved to a separate gem in the future
+
+== 0.4
+- Some potential 0 values on conversions when caching with memcached have been fixed.
+
+== 0.3
 - All Currencies & Rates get handled in BigDecimal now, preventing floating point errors
 - Major Performance inprovements on the DSL methods
 - New ECB API configuration possibility