mumboe-currency 0.5

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'

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/time_quantitizer.rb

@@ -0,0 +1,111 @@
+# Copyright (C) 2006-2007 Kurt Stephens <ruby-currency(at)umleta.com>
+# See LICENSE.txt for details.
+
+# = Currency::Exchange::TimeQuantitizer
+#
+# The Currency::Exchange::TimeQuantitizer quantitizes time values
+# such that money values and rates at a given time
+# can be turned into a hash key, depending
+# on the rate source's temporal accuracy.
+#
+class Currency::Exchange::TimeQuantitizer
+
+  def self.current; @current ||= self.new; end
+  def self.current=(x); @current = x; end
+
+  # Time quantitization size.
+  # Defaults to 1 day.
+  attr_accessor :time_quant_size
+
+  # Time quantization offset in seconds.
+  # This is applied to epoch time before quantization.
+  # If nil, uses Time#utc_offset.
+  # Defaults to nil.
+  attr_accessor :time_quant_offset
+  
+  def initialize(*opt)
+    @time_quant_size   ||= 60 * 60 * 24
+    @time_quant_offset ||= nil
+    opt = Hash[*opt]
+    opt.each_pair{|k,v| self.send("#{k}=", v)}
+  end 
+  
+  
+  # Normalizes time to a quantitized value.
+  # For example: a time_quant_size of 60 * 60 * 24 will
+  # truncate a rate time to a particular day.
+  #
+  # Subclasses can override this method.
+  def quantitize_time(time)
+    # If nil, then nil.
+    return time unless time
+
+    # Get bucket parameters.
+    was_utc = time.utc?
+    quant_offset = time_quant_offset
+    quant_offset ||= time.utc_offset
+    # $stderr.puts "quant_offset = #{quant_offset}"
+    quant_size = time_quant_size.to_i
+    
+    # Get offset from epoch.
+    time = time.tv_sec
+    
+    # Remove offset (timezone)
+    time += quant_offset
+    
+    # Truncate to quantitize size.
+    time = (time.to_i / quant_size) * quant_size
+    
+    # Add offset (timezone)
+    time -= quant_offset
+    
+    # Convert back to Time object.
+    time = Time.at(time)
+    
+    # Quant to day?
+    # NOTE: is this due to a Ruby bug, or
+    # some wierd UTC time-flow issue, like leap-seconds.
+    if quant_size == 60 * 60 * 24 
+      time = time + 60 * 60
+      if was_utc
+        time = time.getutc
+        time = Time.utc(time.year, time.month, time.day, 0, 0, 0, 0)
+      else
+        time = Time.local(time.year, time.month, time.day, 0, 0, 0, 0)
+      end
+    end
+    
+    # Convert back to UTC?
+    time = time.getutc if was_utc
+    
+    time
+  end
+  
+  # Returns a Range of Time such that:
+  #
+  #   range.include?(time) 
+  #   ! range.include?(time + time_quant_size)
+  #   ! range.include?(time - time_quant_size)
+  #   range.exclude_end?
+  #
+  # The range.max is end-exclusive to avoid precision issues:
+  # 
+  #  t = Time.now
+  #   => Thu Feb 15 15:32:34 EST 2007
+  #  x.quantitize_time_range(t)
+  #   => Thu Feb 15 00:00:00 EST 2007...Fri Feb 16 00:00:00 EST 2007
+  #
+  def quantitize_time_range(time)
+    time_0 = quantitize_time(time)
+    time_1 = time_0 + time_quant_size.to_i
+    time_0 ... time_1
+  end
+  
+  # Returns a simple string rep.
+  def to_s
+    "#<#{self.class.name} #{quant_offset} #{quant_size}>"
+  end
+  
+end # class
+
+  

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'
+