Class: Exchange::ExternalAPI::Base

Inherits:
Object
  • Object
show all
Defined in:
lib/exchange/external_api/base.rb

Overview

The Base class of all External APIs, handling basic exchange rates and conversion

Author:

Since:

Version:

Direct Known Subclasses

Call, Json, OpenExchangeRates, Random, XML

Instance Attribute Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (Base) initialize(*args)

Initialize with a convenience accessor for the Cache and the api subclass

Parameters:

  • args (Any) —

    The args to initialize with

Since:

  • 0.1



109
110
111
112
113
114
 
# File 'lib/exchange/external_api/base.rb', line 109

def initialize *args
  @cache  = Exchange.configuration.cache.subclass
  @helper = Exchange::Helper.instance
  
  super *args
end

Instance Attribute Details

- (String) base (readonly)

The currency which was the base for the rates

Returns:

  • (String) —

    The currency which was the base for the rates

Since:

  • 0.1



86
87
88
 
# File 'lib/exchange/external_api/base.rb', line 86

def base
  @base
end

- (Exchange::Cache) cache (readonly)

The cache subclass

Returns:

Since:

  • 0.1



100
101
102
 
# File 'lib/exchange/external_api/base.rb', line 100

def cache
  @cache
end

- (Exchange::Helper) helper (readonly)

The Exchange Helper

Returns:

Since:

  • 0.1



104
105
106
 
# File 'lib/exchange/external_api/base.rb', line 104

def helper
  @helper
end

- (Hash) rates (readonly)

A Hash which delivers the exchange rate of every available currency to the base currency

Returns:

  • (Hash) —

    A Hash which delivers the exchange rate of every available currency to the base currency

Since:

  • 0.1



96
97
98
 
# File 'lib/exchange/external_api/base.rb', line 96

def rates
  @rates
end

- (Integer) timestamp (readonly)

A unix timestamp for the rates, delivered by the API

Returns:

  • (Integer) —

    A unix timestamp for the rates, delivered by the API

Since:

  • 0.1



91
92
93
 
# File 'lib/exchange/external_api/base.rb', line 91

def timestamp
  @timestamp
end

Instance Method Details

- (Float) convert(amount, from, to, opts = {})

Converts an amount of one currency into another

Examples:

Convert 23 EUR to CHF at the rate of December 1 2011

Exchange::ExternalAPI::Base.new.convert(23, :eur, :chf, :at => Time.gm(12,1,2011))
  #=> 30.12

Parameters:

  • amount (Fixed, Float) —

    The amount of the currency to be converted

  • from (String, Symbol) —

    The currency to be converted from

  • to (String, Symbol) —

    The currency which should be converted to

  • opts (Hash) (defaults to: {}) —

    Options to throw at the conversion

Options Hash (opts):

  • :at (Time) —

    Define a Time here to convert at a historical rate

Returns:

  • (Float) —

    The amount in the currency converted to, rounded to two decimals

Since:

  • 0.1



153
154
155
 
# File 'lib/exchange/external_api/base.rb', line 153

def convert amount, from, to, opts={}
  amount * rate(from, to, opts)
end

- (Float) rate(from, to, opts = {})

Delivers an exchange rate from one currency to another with the option of getting a historical exchange rate. This rate has to be multiplied with the amount of the currency which you define in from

Examples:

Get the exchange rate for a conversion from USD to EUR at March 23 2009

Exchange::ExternalAPI::Base.new.rate(:usd, :eur, :at => Time.gm(3,23,2009))
  #=> 1.232231231

Parameters:

  • from (String, Symbol) —

    The currency which should be converted

  • to (String, Symbol) —

    The currency which the should be converted to

  • opts (Hash) (defaults to: {}) —

    The options to throw at the rate

Options Hash (opts):

  • :at (Time) —

    Define a Time here to get a historical rate

Returns:

  • (Float) —

    The exchange rate for those two currencies

Since:

  • 0.1



127
128
129
130
131
132
133
134
135
136
137
138
139
140
 
# File 'lib/exchange/external_api/base.rb', line 127

def rate from, to, opts={}        
  rate = cache.cached(self.class, opts.merge(:key_for => [from, to])) do
    update(opts)
    
    rate_from   = rates[from]
    rate_to     = rates[to]
    
    test_for_rates_and_raise_if_nil rate_from, rate_to, opts[:at]
    
    rate_to / rate_from
  end
  
  rate.is_a?(BigDecimal) ? rate : BigDecimal.new(rate.to_s)
end

- (Object) test_for_rates_and_raise_if_nil(rate_from, rate_to, time = nil)

Test for a error to be thrown when no rates are present

Parameters:

  • rate_from (String) —

    The rate from which should be converted

  • rate_to (String) —

    The rate to which should be converted

  • time (Time) (defaults to: nil) —

    The time at which should be converted

Raises:

  • (NoRateError) —

    An error indicating that there is no rate present when there is no rate present

Since:

  • 0.1



171
172
173
 
# File 'lib/exchange/external_api/base.rb', line 171

def test_for_rates_and_raise_if_nil rate_from, rate_to, time=nil
  raise NoRateError.new("No rates where found for #{rate_from} to #{rate_to} #{'at ' + time.to_s if time}") unless rate_from && rate_to
end

- (Hash) to_hash!(array)

Converts an array to a hash

Parameters:

  • array (Array) —

    The array to convert

Returns:

  • (Hash) —

    The hash out of the array

Since:

  • 0.1



161
162
163
 
# File 'lib/exchange/external_api/base.rb', line 161

def to_hash! array
  Hash[*array]
end