acvwilson-acvwilson-currency 0.5.0

data/lib/currency/exchange.rb

@@ -0,0 +1,50 @@
+# Copyright (C) 2006-2007 Kurt Stephens <ruby-currency(at)umleta.com>
+# See LICENSE.txt for details.
+
+require 'currency'
+
+# The Currency::Exchange package is responsible for
+# the buying and selling of currencies.
+#
+# This feature is currently unimplemented.
+#
+# Exchange rate sources are configured via Currency::Exchange::Rate::Source.
+#
+module Currency::Exchange
+    @@default = nil
+    @@current = nil
+
+    # Returns the default Currency::Exchange object.
+    #
+    # If one is not specfied an instance of Currency::Exchange::Base is
+    # created.  Currency::Exchange::Base cannot service any
+    # conversion rate requests.
+    def self.default 
+      @@default ||= raise :Currency::Exception::Unimplemented, :default
+    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 trading.
+    # 
+    # 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, "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 # module
+
+require 'currency/exchange/rate'
+require 'currency/exchange/rate/source'
+

data/lib/currency/exchange/rate.rb

@@ -0,0 +1,214 @@
+# Copyright (C) 2006-2007 Kurt Stephens <ruby-currency(at)umleta.com>
+# See LICENSE.txt for details.
+
+require 'currency/exchange'
+
+# Represents a convertion rate between two currencies at a given period of time.
+class Currency::Exchange::Rate
+    # The first Currency.
+    attr_reader :c1
+
+    # The second Currency.
+    attr_reader :c2
+
+    # The rate between c1 and c2.
+    #
+    # To convert between m1 in c1 and m2 in c2:
+    #
+    #   m2 = m1 * rate.
+    attr_reader :rate
+
+    # The source of the rate.
+    attr_reader :source
+
+    # The Time of the rate.
+    attr_reader :date
+
+    # If the rate is derived from other rates, this describes from where it was derived.
+    attr_reader :derived
+
+    # Average rate over rate samples in a time range.
+    attr_reader :rate_avg
+    
+    # Number of rate samples used to calcuate _rate_avg_.
+    attr_reader :rate_samples
+
+    # The rate low between date_0 and date_1.
+    attr_reader :rate_lo
+
+    # The rate high between date_0 and date_1.
+    attr_reader :rate_hi
+
+    # The rate at date_0.
+    attr_reader :rate_date_0
+ 
+    # The rate at date_1.
+    attr_reader :rate_date_1
+    
+    # The lowest date of sampled rates.
+    attr_reader :date_0
+    
+    # The highest date of sampled rates.
+    # This is non-inclusive during searches to allow seamless tileings of 
+    # time with rate buckets.
+    attr_reader :date_1
+
+    def initialize(c1, c2, c1_to_c2_rate, source = "UNKNOWN", date = nil, derived = nil, reciprocal = nil, opts = nil)
+      @c1 = c1
+      @c2 = c2
+      @rate = c1_to_c2_rate
+      raise ::Currency::Exception::InvalidRate, 
+      [ 
+       "rate is not positive",
+       :rate, @rate,
+       :c1, c1,
+       :c2, c2,
+      ] unless @rate && @rate >= 0.0
+      @source = source
+      @date = date
+      @derived = derived
+      @reciprocal = reciprocal
+      
+      #
+      @rate_avg =
+        @rate_samples =
+        @rate_lo =
+        @rate_hi =
+        @rate_date_0 =
+        @rate_date_1 =
+        @date_0 =
+        @date_1 =
+        nil
+
+      if opts
+        opts.each_pair do | k, v |
+          self.instance_variable_set("@#{k}", v)
+        end
+      end
+    end
+
+
+    # Returns a cached reciprocal Rate object from c2 to c1.
+    def reciprocal
+      @reciprocal ||= @rate == 1.0 ? self :
+        self.class.new(@c2, @c1, 
+                       1.0 / @rate, 
+                       @source, 
+                       @date, 
+                       "reciprocal(#{derived || "#{c1.code}#{c2.code}"})", self,
+                       { 
+                         :rate_avg     => @rate_avg    && 1.0 / @rate_avg,
+                         :rate_samples => @rate_samples,                            
+                         :rate_lo      => @rate_lo     && 1.0 / @rate_lo,
+                         :rate_hi      => @rate_hi     && 1.0 / @rate_hi,
+                         :rate_date_0  => @rate_date_0 && 1.0 / @rate_date_0,
+                         :rate_date_1  => @rate_date_1 && 1.0 / @rate_date_1,
+                         :date_0       => @date_0,
+                         :date_1       => @date_1,
+                       }
+                       )
+    end
+
+
+    # Converts from _m_ in Currency _c1_ to the opposite currency.
+    def convert(m, c1)
+      m = m.to_f	
+      if @c1 == c1
+        # $stderr.puts "Converting #{@c1} #{m} to #{@c2} #{m * @rate} using #{@rate}"
+        m * @rate
+      else
+        # $stderr.puts "Converting #{@c2} #{m} to #{@c1} #{m / @rate} using #{1.0 / @rate}; recip"
+        m / @rate
+      end
+    end
+
+
+    # Collect rate samples into rate_avg, rate_hi, rate_lo, rate_date_0, rate_date_1, date_0, date_1.
+    def collect_rates(rates)
+      rates = [ rates ] unless rates.kind_of?(Enumerable)
+      rates.each do | r |
+        collect_rate(r)
+      end
+      self
+    end
+
+    # Collect rates samples in to this Rate.
+    def collect_rate(rate)
+      # Initial.
+      @rate_samples ||= 0
+      @rate_sum ||= 0
+      @source ||= rate.source
+      @c1 ||= rate.c1
+      @c2 ||= rate.c2
+ 
+      # Reciprocal?
+      if @c1 == rate.c2 && @c2 == rate.c1
+        collect_rate(rate.reciprocal)
+      elsif ! (@c1 == rate.c1 && @c2 == rate.c2)
+        raise ::Currency::Exception::InvalidRate,
+        [ 
+         "Cannot collect rates between different currency pairs",
+          :rate1, self,
+          :rate2, rate,
+        ]
+      else
+        # Multisource?
+        @source = "<<multiple-sources>>" unless @source == rate.source
+
+        # Calculate rate average.
+        @rate_samples += 1
+        @rate_sum += rate.rate || (rate.rate_lo + rate.rate_hi) * 0.5
+        @rate_avg = @rate_sum / @rate_samples
+
+        # Calculate rates ranges.
+        r = rate.rate_lo || rate.rate
+        unless @rate_lo && @rate_lo < r
+          @rate_lo = r
+        end
+        r = rate.rate_hi || rate.rate
+        unless @rate_hi && @rate_hi > r
+          @rate_hi = r
+        end
+
+        # Calculate rates on date range boundaries
+        r = rate.rate_date_0 || rate.rate
+        d = rate.date_0 || rate.date
+        unless @date_0 && @date_0 < d
+          @date_0 = d
+          @rate_date_0 = r
+        end
+
+        r = rate.rate_date_1 || rate.rate
+        d = rate.date_1 || rate.date
+        unless @date_1 && @date_1 > d
+          @date_1 = d 
+          @rate_date_1 = r
+        end
+
+        @date ||= rate.date || rate.date0 || rate.date1
+      end
+      self
+    end
+
+
+    def to_s(extended = false)
+      extended = "#{date_0} #{rate_date_0} |< #{rate_lo} #{rate} #{rate_hi} >| #{rate_date_1} #{date_1}" if extended
+      extended ||= ''
+      "#<#{self.class.name} #{c1.code} #{c2.code} #{rate} #{source.inspect} #{date ? date.strftime('%Y/%m/%d-%H:%M:%S') : 'nil'} #{derived && derived.inspect} #{extended}>"
+    end
+
+    def inspect; to_s; end
+
+end # class
+
+
+class Currency::Exchange::Rate::Writable < Currency::Exchange::Rate
+  attr_writer :source
+  attr_writer :derived
+  attr_writer :rate
+  def initialize(c1 = nil, c2 = nil, rate = nil, *opts)
+    super(c1, c2, 0.0, *opts)
+    @rate = rate
+  end
+end # class
+

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

@@ -0,0 +1,157 @@
+# Copyright (C) 2006-2007 Kurt Stephens <ruby-currency(at)umleta.com>
+# See LICENSE.txt for details.
+
+require 'currency/exchange/rate'
+require 'currency/exchange/rate/source/base'
+
+# The Currency::Exchange::Rate::Deriver class calculates derived rates
+# from base Rates from a rate Source by pivoting against a pivot currency or by
+# generating reciprocals.
+#
+class Currency::Exchange::Rate::Deriver < Currency::Exchange::Rate::Source::Base
+
+  # The source for base rates.
+  attr_accessor :source
+  
+
+  def name
+    source.name
+  end
+
+
+  def initialize(opt = { })
+    @source = nil
+    @pivot_currency = nil
+    @derived_rates = { }
+    @all_rates = { }
+    super
+  end 
+
+
+  def pivot_currency
+    @pivot_currency || @source.pivot_currency || :USD
+  end
+
+
+  # Return all currencies.
+  def currencies
+    @source.currencies
+  end
+
+
+  # Flush all cached Rates.
+  def clear_rates
+    @derived_rates.clear
+    @all_rates.clear
+    @source.clear_rates
+    super
+  end
+ 
+
+  # Returns all combinations of rates except identity rates.
+  def rates(time = nil)
+    time = time && normalize_time(time)
+    all_rates(time)
+  end
+
+
+  # Computes all rates.
+  # time is assumed to be normalized.
+  def all_rates(time = nil)
+    if x = @all_rates["#{time}"]
+      return x 
+    end
+
+    x = @all_rates["#{time}"] = [ ]
+    
+    currencies = self.currencies
+
+    currencies.each do | c1 |
+      currencies.each do | c2 |
+        next if c1 == c2 
+        c1 = ::Currency::Currency.get(c1)
+        c2 = ::Currency::Currency.get(c2)
+        rate = rate(c1, c2, time)
+        x << rate
+      end
+    end
+
+    x
+  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)
+    rate = get_rate_reciprocal(c1, c2, time)
+    
+    # Attempt to use pivot_currency to bridge
+    # between Rates.
+    unless rate
+      pc = ::Currency::Currency.get(pivot_currency)
+      
+      if pc &&
+          (rate_1 = get_rate_reciprocal(c1, pc, time)) && 
+          (rate_2 = get_rate_reciprocal(pc, c2, time))
+        c1_to_c2_rate = rate_1.rate * rate_2.rate
+        rate = new_rate(c1, c2, 
+                        c1_to_c2_rate, 
+                        rate_1.date || rate_2.date || time, 
+                        "pivot(#{pc.code},#{rate_1.derived || "#{rate_1.c1.code}#{rate_1.c2.code}"},#{rate_2.derived || "#{rate_2.c1}#{rate_2.c2}"})")
+      end
+    end
+    
+    rate
+  end
+
+
+  # Get a matching base rate or its reciprocal.
+  def get_rate_reciprocal(c1, c2, time)
+    rate = get_rate_base_cached(c1, c2, time)
+    unless rate
+      if rate = get_rate_base_cached(c2, c1, time)
+        rate = (@rate["#{c1}:#{c2}:#{time}"] ||= rate.reciprocal)
+      end
+    end
+    
+    rate
+  end
+
+
+  # Returns a cached base Rate.
+  #
+  def get_rate_base_cached(c1, c2, time)
+    rate = (@rate["#{c1}:#{c2}:#{time}"] ||= get_rate_base(c1, c2, time))
+    rate
+  end
+
+
+  # Returns a base Rate from the Source.
+  def get_rate_base(c1, c2, time)
+    if c1 == c2
+      # Identity rates are timeless.
+      new_rate(c1, c2, 1.0, nil, "identity")
+    else
+      source.rate(c1, c2, time)
+    end
+  end
+
+
+  def load_rates(time = nil)
+    all_rates(time)
+  end
+
+
+  # Returns true if the underlying rate provider is available.
+  def available?(time = nil)
+    source.available?(time)
+  end
+
+
+end # class
+
+  
+

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

@@ -0,0 +1,89 @@
+# 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:
+#
+#    require 'currency'
+#    require 'currency/exchange/rate/deriver'
+#    require 'currency/exchange/rate/source/xe'
+#    require 'currency/exchange/rate/source/timed_cache'
+# 
+#    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, "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'