currency 0.3.3 → 0.4.0

data/lib/currency/exchange/rate/source.rb

@@ -0,0 +1,84 @@
+# Copyright (C) 2006-2007 Kurt Stephens <ruby-currency(at)umleta.com>
+# See LICENSE.txt for details.
+
+require 'currency/exchange/rate'
+
+#
+# The Currency::Exchange::Rate::Source package is responsible for
+# providing rates between currencies at a given time.
+#
+# It is not responsible for purchasing or selling actual money.
+# See Currency::Exchange.
+#
+# Currency::Exchange::Rate::Source::Provider subclasses are true rate data
+# providers.  See the #load_rates method.  They provide groups of rates
+# at a given time.
+#
+# Other Currency::Exchange::Rate::Source::Base subclasses
+# are chained to provide additional rate source behavior,
+# such as caching and derived rates.  They provide individual rates between
+# currencies at a given time.  See the #rate method.  An application
+# will interface directly to a Currency::Exchange::Rate::Source::Base.
+# A rate aggregator like Currency::Exchange::Rate::Historical::Writer will
+# interface directly to a Currency::Exchange::Rate::Source::Provider.
+#
+# == IMPORTANT
+#
+# Rates sources should *never* install themselves
+# as a Currency::Exchange::Rate::Source.current or
+# Currency::Exchange::Rate::Source.default.  The application itself is
+# responsible setting up the default rate source.
+# The old auto-installation behavior of rate sources,
+# like Currency::Exchange::Xe, is no longer supported.
+#
+# == Initialization of Rate Sources
+#
+# A typical application will use the following rate source chain:
+#
+# * Currency::Exchange::Rate::Source::TimedCache
+# * Currency::Exchange::Rate::Deriver
+# * a Currency::Exchange::Rate::Source::Provider subclass, like Currency::Exchange::Rate::Source::Xe.
+#
+# Somewhere at initialization of application:
+#
+#   provider = Currency::Exchange::Rate::Source::Xe.new
+#   deriver  = Currency::Exchange::Rate::Deriver.new(:source => provider)
+#   cache    = Currency::Exchange::Rate::Source::TimedCache.new(:source => deriver)
+#   Currency::Exchange::Rate::Source.default = cache
+#
+module Currency::Exchange::Rate::Source
+
+    @@default = nil
+    @@current = nil
+
+    # Returns the default Currency::Exchange::Rate::Source::Base object.
+    #
+    # If one is not specfied an instance of Currency::Exchange::Rate::Source::Base is
+    # created.  Currency::Exchange::Rate::Source::Base cannot service any
+    # conversion rate requests.
+    def self.default 
+      @@default ||= Base.new
+    end
+
+    # Sets the default Currency::Exchange object.
+    def self.default=(x)
+      @@default = x
+    end
+
+    # Returns the current Currency::Exchange object used during
+    # explicit and implicit Money conversions.
+    # 
+    # If #current= has not been called and #default= has not been called,
+    # then UndefinedExchange is raised.
+    def self.current
+      @@current || self.default || (raise ::Currency::Exception::UndefinedExchange.new("Currency::Exchange.current not defined"))
+    end
+
+    # Sets the current Currency::Exchange object used during
+    # explicit and implicit Money conversions.
+    def self.current=(x)
+      @@current = x
+    end
+end
+
+require 'currency/exchange/rate/source/base'

data/lib/currency/exchange/rate/source/base.rb

@@ -0,0 +1,156 @@
+# Copyright (C) 2006-2007 Kurt Stephens <ruby-currency(at)umleta.com>
+# See LICENSE.txt for details.
+
+require 'currency/exchange/rate/source'
+
+# = Currency::Exchange::Rate::Source::Base
+#
+# The Currency::Exchange::Rate::Source::Base class is the base class for
+# currency exchange rate providers.
+#
+# Currency::Exchange::Rate::Source::Base subclasses are Currency::Exchange::Rate
+# factories.
+#
+# Represents a method of converting between two currencies.
+#
+# See Currency;:Exchange::Rate::source for more details.
+#
+class Currency::Exchange::Rate::Source::Base
+
+    # The name of this Exchange.
+    attr_accessor :name
+
+    # Currency to use as pivot for deriving rate pairs.
+    # Defaults to :USD.
+    attr_accessor :pivot_currency
+
+    # If true, this Exchange will log information.
+    attr_accessor :verbose
+
+    attr_accessor :time_quantitizer
+
+
+    def initialize(opt = { })
+      @name = nil
+      @verbose = nil unless defined? @verbose
+      @pivot_currency ||= :USD
+
+      @rate = { }
+      @currencies = nil
+      opt.each_pair{|k,v| self.send("#{k}=", v)}
+    end 
+
+
+    # Converts Money m in Currency c1 to a new
+    # Money value in Currency c2.
+    def convert(m, c2, time = nil, c1 = nil)
+      c1 = m.currency if c1 == nil
+      time = m.time if time == nil
+      time = normalize_time(time)
+      if c1 == c2 && normalize_time(m.time) == time
+        m
+      else
+        rate = rate(c1, c2, time)
+        # raise ::Currency::Exception::UnknownRate, "#{c1} #{c2} #{time}" unless rate
+          
+        rate && ::Currency::Money(rate.convert(m, c1), c2, time)
+      end
+    end
+
+
+    # Flush all cached Rate.
+    def clear_rates
+      @rate.clear
+      @currencies = nil
+    end
+
+
+    # Flush any cached Rate between Currency c1 and c2.
+    def clear_rate(c1, c2, time, recip = true)
+      time = time && normalize_time(time)
+      @rate["#{c1}:#{c2}:#{time}"] = nil
+      @rate["#{c2}:#{c1}:#{time}"] = nil if recip
+      time
+    end
+
+
+    # Returns the cached Rate between Currency c1 and c2 at a given time.
+    #
+    # Time is normalized using #normalize_time(time)
+    #
+    # Subclasses can override this method to implement
+    # rate expiration rules.
+    #
+    def rate(c1, c2, time)
+      time = time && normalize_time(time)
+      @rate["#{c1}:#{c2}:#{time}"] ||= get_rate(c1, c2, time)
+    end
+
+
+    # Gets all rates available by this source.
+    #
+    def rates(time = nil)
+      raise ::Currency::Exception::SubclassResponsibility, "#{self.class}#rate"
+    end
+
+
+    # Returns a list of Currencies that the rate source provides.
+    #
+    # Subclasses can override this method.
+    def currencies
+      @currencies ||= rates.collect{| r | [ r.c1, r.c2 ]}.flatten.uniq
+    end
+
+
+    # Determines and creates the Rate between Currency c1 and c2.
+    #
+    # May attempt to use a pivot currency to bridge between
+    # rates.
+    #
+    def get_rate(c1, c2, time)
+      raise ::Currency::Exception::SubclassResponsibility, "#{self.class}#get_rate"
+    end
+
+    # Returns a base Rate.
+    #
+    # Subclasses are required to implement this method.
+    def get_rate_base(c1, c2, time)
+      raise ::Currency::Exception::SubclassResponsibility, "#{self.class}#get_rate_base"
+    end
+
+
+    # Returns a list of all available rates.
+    #
+    # Subclasses must override this method.
+    def get_rates(time = nil)
+      raise ::Currency::Exception::SubclassResponsibility, "#{self.class}#get_rate"
+    end
+
+
+    # Called by implementors to construct new Rate objects.
+    def new_rate(c1, c2, c1_to_c2_rate, time = nil, derived = nil)
+      c1 = ::Currency::Currency.get(c1)
+      c2 = ::Currency::Currency.get(c2)
+      rate = ::Currency::Exchange::Rate.new(c1, c2, c1_to_c2_rate, name, time, derived)
+      # $stderr.puts "new_rate = #{rate}"
+      rate
+    end
+
+
+    # Normalizes rate time to a quantitized value.
+    #
+    # Subclasses can override this method.
+    def normalize_time(time)
+      time && (time_quantitizer || ::Currency::Exchange::TimeQuantitizer.current).quantitize_time(time)
+    end
+  
+   
+    # Returns a simple string rep.
+    def to_s
+      "#<#{self.class.name} #{self.name && self.name.inspect}>"
+    end
+    alias :inspect :to_s
+
+end # class
+
+  

data/lib/currency/exchange/rate/source/failover.rb

@@ -0,0 +1,57 @@
+# Copyright (C) 2006-2007 Kurt Stephens <ruby-currency(at)umleta.com>
+# See LICENSE.txt for details.
+
+require 'currency/exchange/rate/source'
+
+
+# Gets Rates from primary source, if primary fails, attempts secondary source.
+#
+class Currency::Exchange::Rate::Source::Failover < ::Currency::Exchange::Base
+  # Primary rate source.
+  attr_accessor :primary
+
+  # Secondary rate source if primary fails.
+  attr_accessor :secondary
+
+  def name
+    "failover(#{primary.name}, #{secondary.name})"
+  end
+
+
+  def clear_rates
+    @primary.clear_rates
+    @secondary.clear_rates
+    super
+  end
+  
+
+  def get_rate(c1, c2, time)
+    rate = nil
+
+    # Try primary.
+    err = nil
+    begin
+      rate = @primary.get_rate(c1, c2, time)
+    rescue Object => e
+      err = e
+    end
+
+
+    if rate == nil || err
+      $stderr.put "Failover: primary failed for get_rate(#{c1}, #{c2}, #{time}) : #{err.inspect}"
+      rate = @secondary.get_rate(c1, c2, time)
+    end
+
+
+    unless rate
+      raise("Failover: secondary failed for get_rate(#{c1}, #{c2}, #{time})")
+    end
+
+    rate
+  end
+
+ 
+end # class
+
+
+

data/lib/currency/exchange/rate/source/historical.rb

@@ -0,0 +1,79 @@
+# Copyright (C) 2006-2007 Kurt Stephens <ruby-currency(at)umleta.com>
+# See LICENSE.txt for details.
+
+require 'currency/exchange/rate/source/base'
+
+# Gets historical rates from database using Active::Record.
+# Rates are retrieved using Currency::Exchange::Rate::Source::Historical::Rate as
+# a database proxy.
+#
+# See Currency::Exchange::Rate::Source::Historical::Writer for a rate archiver.
+#
+class Currency::Exchange::Rate::Source::Historical < Currency::Exchange::Rate::Source::Base
+
+    # Select specific rate source.
+    # Defaults to nil
+    attr_accessor :source
+
+    def initialize
+      @source = nil # any
+      super
+    end
+
+
+    def source_key
+      @source ? @source.join(',') : ''
+    end
+
+
+    # This Exchange's name is the same as its #uri.
+    def name
+      "historical #{source_key}"
+    end
+
+
+    def initialize(*opt)
+      super
+      @rates_cache = { }
+      @raw_rates_cache = { }
+    end
+
+
+    def clear_rates
+      @rates_cache.clear
+      @raw_rates_cache.clear
+      super
+    end
+
+
+    # Returns a Rate.
+    def get_rate(c1, c2, time)
+      # rate = 
+      get_rates(time).select{ | r | r.c1 == c1 && r.c2 == c2 }[0]
+      # $stderr.puts "#{self}.get_rate(#{c1}, #{c2}, #{time.inspect}) => #{rate.inspect}"
+      # rate
+    end
+
+
+    # Return a list of base Rates.
+    def get_rates(time = nil)
+      @rates_cache["#{source_key}:#{time}"] ||= 
+        get_raw_rates(time).collect do | rr |
+          rr.to_rate
+        end
+    end
+
+
+    # Return a list of raw rates.
+    def get_raw_rates(time = nil)
+      @raw_rates_cache["#{source_key}:#{time}"] ||= 
+        ::Currency::Exchange::Rate::Source::Historical::Rate.new(:c1 => nil, :c2 => nil, :date => time, :source => source).
+          find_matching_this(:all)
+    end
+
+end # class
+
+
+require 'currency/exchange/rate/source/historical/rate'
+
+

data/lib/currency/exchange/rate/source/historical/rate.rb

@@ -0,0 +1,181 @@
+require 'active_record/base'
+
+require 'currency/exchange/rate/source/historical'
+
+# This class represents a historical Rate in a database.
+# It requires ActiveRecord.
+#
+class Currency::Exchange::Rate::Source::Historical::Rate < ::ActiveRecord::Base
+   TABLE_NAME = 'currency_historical_rates'
+   set_table_name TABLE_NAME
+
+   # Can create a table and indices for this class
+   # when passed a Migration.
+   def self.__create_table(m, table_name = TABLE_NAME)
+     table_name = table_name.intern 
+     m.instance_eval do 
+       create_table table_name do |t|
+         t.column :created_on, :datetime, :null => false
+         t.column :updated_on, :datetime
+         
+         t.column :c1,       :string,     :limit => 3, :null => false
+         t.column :c2,       :string,     :limit => 3, :null => false
+         
+         t.column :source,   :string,     :limit => 32, :null => false
+         
+         t.column :rate,     :float,    :null => false
+         
+         t.column :rate_avg,      :float
+         t.column :rate_samples,  :integer
+         t.column :rate_lo,       :float
+         t.column :rate_hi,       :float
+         t.column :rate_date_0,   :float
+         t.column :rate_date_1,   :float
+         
+         t.column :date,     :datetime, :null => false
+         t.column :date_0,   :datetime
+         t.column :date_1,   :datetime
+
+         t.column :derived,  :string,   :limit => 64
+       end
+       
+       add_index table_name, :c1
+       add_index table_name, :c2
+       add_index table_name, :source
+       add_index table_name, :date
+       add_index table_name, :date_0
+       add_index table_name, :date_1
+       add_index table_name, [:c1, :c2, :source, :date_0, :date_1], :name => 'c1_c2_src_date_range', :unique => true
+     end
+   end
+
+
+   # Initializes this object from a Currency::Exchange::Rate object.
+   def from_rate(rate)
+     self.c1 = rate.c1.code.to_s
+     self.c2 = rate.c2.code.to_s
+     self.rate = rate.rate
+     self.rate_avg = rate.rate_avg
+     self.rate_lo  = rate.rate_lo
+     self.rate_hi  = rate.rate_hi
+     self.rate_date_0  = rate.rate_date_0
+     self.rate_date_1  = rate.rate_date_1
+     self.source = rate.source
+     self.derived = rate.derived
+     self.date = rate.date
+     self.date_0 = rate.date_0
+     self.date_1 = rate.date_1
+     self
+   end
+
+
+   # Convert all dates to localtime.
+   def dates_to_localtime!
+     self.date   = self.date   && self.date.clone.localtime
+     self.date_0 = self.date_0 && self.date_0.clone.localtime
+     self.date_1 = self.date_1 && self.date_1.clone.localtime
+   end
+
+
+   # Creates a new Currency::Exchange::Rate object.
+   def to_rate
+     Currency::Exchange::Rate.new(
+                                  ::Currency::Currency.get(self.c1), 
+                                  ::Currency::Currency.get(self.c2),
+                                  self.rate,
+                                  "historical #{self.source}",
+                                  self.date,
+                                  self.derived,
+                                  {
+                                    :rate_avg => self.rate_avg,
+                                    :rate_samples => self.rate_samples,
+                                    :rate_lo => self.rate_lo,
+                                    :rate_hi => self.rate_hi,
+                                    :rate_date_0 => self.rate_date_0,
+                                    :rate_date_1 => self.rate_date_1,
+                                    :date_0 => self.date_0,
+                                    :date_1 => self.date_1
+                                  })
+   end
+
+
+   # Various defaults.
+   def before_validation
+     self.rate_avg = self.rate unless self.rate_avg
+     self.rate_samples = 1 unless self.rate_samples
+     self.rate_lo = self.rate unless self.rate_lo
+     self.rate_hi = self.rate unless self.rate_hi
+     self.rate_date_0 = self.rate unless self.rate_date_0
+     self.rate_date_1 = self.rate unless self.rate_date_1
+
+     #self.date_0 = self.date unless self.date_0
+     #self.date_1 = self.date unless self.date_1
+     self.date = self.date_0 + (self.date_1 - self.date_0) * 0.5 if ! self.date && self.date_0 && self.date_1
+     self.date = self.date_0 unless self.date
+     self.date = self.date_1 unless self.date
+   end
+
+
+   # Returns a ActiveRecord::Base#find :conditions value
+   # to locate any rates that will match this one.
+   #
+   # source may be a list of sources.
+   # date will match inside date_0 ... date_1 or exactly.
+   #
+   def find_matching_this_conditions
+     sql = [ ]
+     values = [ ]
+
+     if self.c1
+       sql << 'c1 = ?'
+       values.push(self.c1.to_s)
+     end
+
+     if self.c2
+       sql << 'c2 = ?'
+       values.push(self.c2.to_s)
+     end
+
+     if self.source
+       if self.source.kind_of?(Array)
+         sql << 'source IN ?'
+       else
+         sql << 'source = ?'
+       end
+       values.push(self.source)
+     end
+
+     if self.date
+       sql << '(((date_0 IS NULL) OR (date_0 <= ?)) AND ((date_1 IS NULL) OR (date_1 > ?))) OR date = ?'
+       values.push(self.date, self.date, self.date)
+     end
+
+     if self.date_0
+       sql << 'date_0 = ?'
+       values.push(self.date_0)
+     end
+
+     if self.date_1
+       sql << 'date_1 = ?'
+       values.push(self.date_1)
+     end
+
+     sql << '1 = 1' if sql.empty?
+
+     values.unshift(sql.collect{|x| "(#{x})"}.join(' AND '))
+     
+     # $stderr.puts "values = #{values.inspect}"
+
+     values
+   end
+
+
+   # Shorthand.
+   def find_matching_this(opt1 = :all, *opts)
+     self.class.find(opt1, :conditions => find_matching_this_conditions, *opts)
+   end
+
+ end # class
+
+
+