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:

  • Beat Richartz

Since:

  • 0.1

Version:

  • 0.1

Direct Known Subclasses

Call, Json, OpenExchangeRates, Random, XML

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(*args) ⇒ Base

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

#baseString (readonly)

Returns 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

#cacheExchange::Cache (readonly)

Returns The cache subclass

Returns:

Since:

  • 0.1


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

def cache
  @cache
end

#helperExchange::Helper (readonly)

Returns The Exchange Helper

Returns:

Since:

  • 0.1


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

def helper
  @helper
end

#ratesHash (readonly)

Returns 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

#timestampInteger (readonly)

Returns 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

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

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

#rate(from, to, opts = {}) ⇒ Float

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

#test_for_rates_and_raise_if_nil(rate_from, rate_to, time = nil) ⇒ Object

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

#to_hash!(array) ⇒ Hash

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