exchange 0.2.6

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format documentation

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+script: bundle exec rspec

data/Gemfile

@@ -0,0 +1,17 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+gem "nokogiri",   ">= 1.4.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.
+group :development do
+  gem "shoulda", ">= 0"
+  gem "yard", "~> 0.7.4"
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.8.3"
+  gem "rspec"
+end

data/Gemfile.lock

@@ -0,0 +1,41 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    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.5)
+    memcached (1.3.6)
+    nokogiri (1.5.0)
+    rake (0.9.2.2)
+    rdoc (3.12)
+      json (~> 1.4)
+    redis (2.2.2)
+    rspec (2.8.0)
+      rspec-core (~> 2.8.0)
+      rspec-expectations (~> 2.8.0)
+      rspec-mocks (~> 2.8.0)
+    rspec-core (2.8.0)
+    rspec-expectations (2.8.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.8.0)
+    shoulda (2.11.3)
+    yard (0.7.5)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.0.0)
+  jeweler (~> 1.8.3)
+  json (>= 1.6.5)
+  memcached (>= 1.3.0)
+  nokogiri (>= 1.4.0)
+  redis (>= 2.2.0)
+  rspec
+  shoulda
+  yard (~> 0.7.4)

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2012 beatrichartz
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,262 @@
+= exchange {<img src="https://secure.travis-ci.org/beatrichartz/exchange.png" />}[http://travis-ci.org/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, ruby 1.9.2 and 1.9.3. You can use it with just plain ruby projects, in Rails 2 and 3, Sinatra, Padrino or whatever Framework you like.
+
+=== Easy Conversion
+
+Imagine a conversion as easy as 
+  1.eur.to_usd
+or even better 
+  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
+
+Imagine the exchange rates getting cached, and you hitting the internet only daily to get new rates (hourly if you're eager to have the absolutely newest ones)
+
+=== Use two great APIs or your own
+
+Two open APIs are already included: Currency Bot (http://currencybot.github.com/) and Xaviermedia (http://www.xavierforum.com/viewtopic.php?f=5&t=10979&sid=671a685edbfa5dbec219fbc6793d5057)
+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
+
+=== Use great caches or your own
+
+Also, the gem allows you to use one of three available caching solutions: Memcached via the Memcached gem, Redis via the redis gem or the Rails cache.
+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
+
+== Installation
+=== Bundler / Rails
+Add it to your Gemfile  
+  gem "exchange", ">=0.2.5"
+=== Manually
+Just install it as a gem :)
+  gem install exchange
+
+== Basic Operations
+
+=== Convert
+
+Converting one currency to another is as easy as 1,2,3. Don't be afraid, even if it returns a currency object, all Fixed and Float operations can be applied as method missing routes to the value
+
+  1.usd.to_eur                                  #=> #<Exchange::Currency @value=0.93 @currency=:eur>
+  2.3.dkk.to_sek                                #=> #<Exchange::Currency @value=3.33 @currency=:sek>
+  45.54.nok.to_sek                              #=> #<Exchange::Currency @value=3.33 @currency=:sek>
+
+Easily convert one currency to another at a historical rate
+
+  1.52.usd.to_eur :at => '2011-01-01'           #=> #<Exchange::Currency @value=1.23 @currency=:eur>
+  3.45.eur.to_sek :at => Time.gm(2011,3,3)      #=> #<Exchange::Currency @value=19.23 @currency=:sek>
+  345.sek.to_nok :at => Time.gm(2011,3,3)       #=> #<Exchange::Currency @value=348 @currency=:nok>
+  
+Or even define an instance of currency as historic by adding a time.
+
+  1.52.usd(:at => '2011-01-01').to_eur          #=> #<Exchange::Currency @value=1.23 @currency=:eur>
+  3.45.eur(:at => Time.gm(2011,3,3)).to_sek     #=> #<Exchange::Currency @value=19.23 @currency=:sek>
+  345.sek(:at => Time.gm(2011,3,3)).to_nok      #=> #<Exchange::Currency @value=348 @currency=:nok>
+  
+Do multiple conversion steps at once (if in any way useful)
+
+  3.chf.to_eur(:at => '2011-02-04').to_usd      #=> #<Exchange::Currency @value=5.3 @currency=:eur>
+  
+  
+=== Compare
+
+Compare Currencies, they will convert implicitly
+
+  2.eur > 2.usd                                 #=> true (2.usd get converted to eur and compared)
+  2.nok < 2.sek                                 #=> false (2.sek get converted to nok and compared)
+  5.eur == 4.34.chf                             #=> true
+  50.eur == 4.34.chf                            #=> false
+  50.eur.to_sek == 50.eur                       #=> true
+  50.eur(:at => '2011-1-1') == 50.sek           #=> false
+
+Sort multiple currencies at once
+
+  [5.eur, 4.usd, 4.chf(:at => '2010-01-01')].sort   #=> [#<Exchange::Currency @value=4 @currency=:usd>, #<Exchange::Currency @value=4 @currency=:chf>, #<Exchange::Currency @value=5 @currency=:eur>]
+  
+This is true, because it uses the same historic conversion rate
+
+  3.eur(:at => '201-01-01').to_usd == 3.eur.to_usd(:at => '201-01-01')
+  
+But this is false, obviously, because the second instance uses the present exchange rate
+
+  3.eur(:at => '201-01-01').to_usd == 3.eur.to_usd
+  
+=== Operate
+
+Add, Subtract, Multiply, Divide Currencies and don't lose a dime. The result will get returned in the currency of the first argument
+
+  1.usd + 1.32.eur                              #=> #<Exchange::Currency @value=2.54 @currency=:usd>
+  1.usd - 1.32.eur                              #=> #<Exchange::Currency @value=-0.2 @currency=:usd>
+  1.usd * 1.32.eur                              #=> #<Exchange::Currency @value=3.44 @currency=:usd>
+  1.usd / 1.32.eur                              #=> #<Exchange::Currency @value=0.89 @currency=:usd>
+  
+  
+If you define a currency object as historic. It will use historic conversion if it gets converted (in this example, the 1.32 eur will get converted to usd at the rate of January 1 2008)
+
+  1.usd - 1.32.eur(:at => '2008-1-1')           #=> #<Exchange::Currency @value=2.54 @currency=:usd>
+
+You can just instantiate currencies and apply operations
+
+  3.1.eur.round                                   #=> #<Exchange::Currency @value=3 @currency=:eur>
+
+Convert one currency to another and round, ceil or floor it, it still retains currency information of the actual and previous currency
+
+  1.34.usd.to_eur.round                         #=> #<Exchange::Currency @value=1 @currency=:eur>
+  10.34.usd.to_nok.ceil                         #=> #<Exchange::Currency @value=45 @currency=:nok>
+  5.34.usd.to_eur.floor                         #=> #<Exchange::Currency @value=4 @currency=:eur>
+  5.34.usd.to_eur.floor.from                    #=> #<Exchange::Currency @value=5.34 @currency=:usd>
+  
+  
+=== Retain Information
+
+Access the original currency and its value after conversion, even over multiple steps
+  converted = 2.eur.to_usd                      #=> #<Exchange::Currency @value=2.12 @currency=:usd>
+  converted.from                                #=> #<Exchange::Currency @value=2 @currency=:eur>
+  converted2 = converted.to_nok                 #=> #<Exchange::Currency @value=22.12 @currency=:nok>
+  converted2.from                               #=> #<Exchange::Currency @value=2.12 @currency=:usd>
+
+== Configuration
+
+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|
+    # your configuration goes here
+  end
+  
+
+=== Options
+
+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
+  :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
+  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
+  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
+  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
+  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
+  end
+
+Use the Xaviermedia API as the source of your conversion rates
+  Exchange::Configuration.define do |c|
+    c.api = :xavier_media
+  end
+  
+== Connect your own API and Cache
+
+=== Your own API
+
+Easily connect to your custom API by writing an ExternalAPI Class, or use your own caching solution to cache. Please note that only open source APIs can be accepted as contributions to this gem. Private / Premium APIs have to be written as your own.
+  module Exchange
+    module ExternalAPI
+      class MyCustom < Base
+        # 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
+        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.new(api_url(time), :at => time) do |result|
+
+            # assign the currency conversion base, attention, this is readonly, so don't do self.base = 
+            @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.
+            @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            = result['timestamp'].to_i
+          end
+        end
+        
+        private
+
+          def api_url(time)
+            # code a helper function that builds your api url for the specified time
+          end
+
+      end
+    end
+  end
+
+Now, you can configure your API in the configuration. The Symbol will get camelcased and constantized
+
+  Exchange::Configuration.api = :my_custom
+
+Have fun, and don't forget to write tests.
+
+=== Your own Cache
+
+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
+      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
+
+Have fun, and don't forget to write tests.
+
+
+== Contributing to exchange
+
+Please note that only open source APIs can be accepted as contributions to this gem. Private / Premium APIs have to be written as your own extension and will not be added to the gem code.
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
+* Fork the project.
+* Start a feature/bugfix branch.
+* Commit and push until you are happy with your contribution.
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Make sure to add documentation for it. This is important so everyone else can see what your code can do.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+== Copyright
+
+Copyright (c) 2012 Beat Richartz. See LICENSE.txt for
+further details.
+

data/Rakefile

@@ -0,0 +1,46 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "exchange"
+  gem.homepage = "http://github.com/beatrichartz/exchange"
+  gem.license = "MIT"
+  gem.summary = %Q{Simple Exchange Rate operations for your ruby app}
+  gem.description = %Q{The Exchange Gem gives you easy access to currency functions directly on your Numbers. Imagine a conversion as easy as 
+    1.eur.to_usd
+  or even better 
+    1.eur.to_usd(:at => Time.now - 84600)
+  which gets you an exchange at the rates of yesterday.}
+  gem.email = "exchange_gem@gmail.com"
+  gem.authors = ["Beat Richartz"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+task :default => :test
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+require 'yard'
+YARD::Rake::YardocTask.new
+
+# RSpec::Core::RakeTask.new(:rcov) do |spec|
+#   spec.pattern = 'spec/**/*_spec.rb'
+#   spec.rcov = true
+# end

data/VERSION

@@ -0,0 +1 @@
+0.2.6

data/exchange.gemspec

@@ -0,0 +1,102 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = "exchange"
+  s.version = "0.2.6"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Beat Richartz"]
+  s.date = "2012-02-03"
+  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",
+    "exchange.gemspec",
+    "lib/core_extensions/conversability.rb",
+    "lib/exchange.rb",
+    "lib/exchange/cache.rb",
+    "lib/exchange/cache/base.rb",
+    "lib/exchange/cache/memcached.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/xavier_media.rb",
+    "spec/core_extensions/conversability_spec.rb",
+    "spec/exchange/cache/base_spec.rb",
+    "spec/exchange/cache/memcached_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/xavier_media_spec.rb",
+    "spec/spec_helper.rb",
+    "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.11"
+  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<nokogiri>, [">= 1.4.0"])
+      s.add_runtime_dependency(%q<json>, [">= 1.6.5"])
+      s.add_runtime_dependency(%q<memcached>, [">= 1.3.0"])
+      s.add_runtime_dependency(%q<redis>, [">= 2.2.0"])
+      s.add_development_dependency(%q<shoulda>, [">= 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"])
+      s.add_development_dependency(%q<rspec>, [">= 0"])
+    else
+      s.add_dependency(%q<nokogiri>, [">= 1.4.0"])
+      s.add_dependency(%q<json>, [">= 1.6.5"])
+      s.add_dependency(%q<memcached>, [">= 1.3.0"])
+      s.add_dependency(%q<redis>, [">= 2.2.0"])
+      s.add_dependency(%q<shoulda>, [">= 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"])
+      s.add_dependency(%q<rspec>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<nokogiri>, [">= 1.4.0"])
+    s.add_dependency(%q<json>, [">= 1.6.5"])
+    s.add_dependency(%q<memcached>, [">= 1.3.0"])
+    s.add_dependency(%q<redis>, [">= 2.2.0"])
+    s.add_dependency(%q<shoulda>, [">= 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"])
+    s.add_dependency(%q<rspec>, [">= 0"])
+  end
+end
+