currency 0.3.3 → 0.4.0

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

@@ -0,0 +1,159 @@
+# Copyright (C) 2006-2007 Kurt Stephens <ruby-currency(at)umleta.com>
+# See LICENSE.txt for details.
+
+
+# This class formats a Money value as a String.
+# Each Currency has a default Formatter.
+class Currency::Formatter
+  # Defaults to ','
+  attr_accessor :thousands_separator
+
+  # Defaults to '.'
+  attr_accessor :decimal_separator
+
+  # If true, insert _thousands_separator_ between each 3 digits in the whole value.
+  attr_accessor :thousands
+
+  # If true, append _decimal_separator_ and decimal digits after whole value.
+  attr_accessor :cents
+  
+  # If true, prefix value with currency symbol.
+  attr_accessor :symbol
+
+  # If true, append currency code.
+  attr_accessor :code
+
+  # If true, use html formatting.
+  #
+  #   Currency::Money(12.45, :EUR).to_s(:html => true; :code => true)
+  #   => "&#8364;12.45 <span class=\"currency_code\">EUR</span>"
+
+  attr_accessor :html
+
+
+  # If passed true, formats for an input field (i.e.: as a number).
+  def as_input_value=(x)
+    if x
+      self.thousands_separator = ''
+      self.decimal_separator = '.'
+      self.thousands = false
+      self.cents = true
+      self.symbol = false
+      self.code = false
+      self.html = false
+    end
+  end
+
+
+  @@default = nil
+  # Get the default Formatter.
+  def self.default
+    @@default || self.new
+  end
+
+
+  # Set the default Formatter.
+  def self.default=(x)
+    @@default = x
+  end
+  
+
+  def initialize(opt = { })
+    @thousands_separator = ','
+    @decimal_separator = '.'
+    @thousands = true
+    @cents = true
+    @symbol = true
+    @code = false
+    @html = false
+
+    opt.each_pair{ | k, v | self.send("#{k}=", v) }
+  end
+
+
+  def currency=(x) # :nodoc:
+    # DO NOTHING!
+  end
+
+
+  def _format(m, currency = nil) # :nodoc:
+    # Get currency.
+    currency ||= m.currency
+
+    # Get scaled integer representation for this Currency.
+    # $stderr.puts "m.currency = #{m.currency}, currency => #{currency}"
+    x = m.Money_rep(currency)
+
+    # Remove sign.
+    x = - x if ( neg = x < 0 )
+    
+    # Convert to String.
+    x = x.to_s
+    
+    # Keep prefixing "0" until filled to scale.
+    while ( x.length <= currency.scale_exp )
+      x = "0" + x
+    end
+    
+    # Insert decimal place.
+    whole = x[0 .. currency.format_left] 
+    decimal = x[currency.format_right .. -1]
+ 
+    # Do commas
+    x = whole
+    if @thousands && (@thousands_separator && ! @thousands_separator.empty?)
+      x.reverse!
+      x.gsub!(/(\d\d\d)/) {|y| y + @thousands_separator}
+      x.sub!(/#{@thousands_separator}$/,'')
+      x.reverse!
+    end
+    
+    x << @decimal_separator + decimal if @cents && @decimal_separator
+    
+    # Put sign back.
+    x = '-' + x if neg
+    
+    # Add symbol?
+    x = ((@html && currency.symbol_html) || currency.symbol || '') + x if @symbol
+    
+    # Suffix with currency code.
+    if @code
+      x << (' ' + _format_Currency(currency))
+    end
+    
+    x
+  end
+
+
+  def _format_Currency(c) # :nodoc:
+    x = ''
+    x << '<span class="currency_code">' if @html
+    x << c.code.to_s
+    x << '</span>' if @html
+    x
+  end
+
+
+  @@empty_hash = { }
+  @@empty_hash.freeze
+
+  # Format a Money object as a String.
+  # 
+  #   m = Money.new("1234567.89")
+  #   m.to_s(:code => true, :symbol => false)
+  #     => "1,234,567.89 USD"
+  #
+  def format(m, opt = @@empty_hash)
+    fmt = self
+
+    unless opt.empty? 
+      fmt = fmt.clone
+      opt.each_pair{ | k, v | fmt.send("#{k}=", v) }
+    end
+
+    # $stderr.puts "format(opt = #{opt.inspect})"
+    fmt._format(m, opt[:currency]) # Allow override of current currency.
+  end
+
+end # class
+

data/lib/currency/macro.rb

@@ -0,0 +1,321 @@
+# Copyright (C) 2006-2007 Kurt Stephens <ruby-currency(at)umleta.com>
+# See LICENSE.txt for details.
+
+class Currency::Money
+    @@money_attributes = { }
+
+    # Called by money macro when a money attribute
+    # is created.
+    def self.register_money_attribute(attr_opts)
+      (@@money_attributes[attr_opts[:class]] ||= { })[attr_opts[:attr_name]] = attr_opts
+    end
+
+    # Returns an array of option hashes for all the money attributes of
+    # this class.
+    #
+    # Superclass attributes are not included.
+    def self.money_attributes_for_class(cls)
+      (@@money_atttributes[cls] || { }).values
+    end
+
+    # Iterates through all known money attributes in all classes.
+    #
+    # each_money_attribute { | money_opts |
+    #   ...
+    # }
+    def self.each_money_attribute(&blk)
+      @@money_attributes.each do | cls, hash |
+        hash.each do | attr_name, attr_opts |
+          yield attr_opts
+        end
+      end
+    end
+    
+end # class
+
+
+module Currency::Macro
+    def self.append_features(base) # :nodoc:
+      # $stderr.puts "  Currency::ActiveRecord#append_features(#{base})"
+      super
+      base.extend(ClassMethods)
+    end
+
+
+
+# == Macro Suppport
+#
+# Support for Money attributes.
+#
+#    require 'currency'
+#    require 'currency/macro'
+#    
+#    class SomeClass
+#      include ::Currency::Macro
+#      attr_accessor :amount
+#      attr_money :amount_money, :value => :amount, :currency_fixed => :USD, :rep => :float
+#    end
+# 
+#    x = SomeClass.new
+#    x.amount = 123.45
+#    x.amount
+#    # => 123.45
+#    x.amount_money
+#    # => $123.45 USD
+#    x.amount_money = x.amount_money + "12.45"
+#    # => $135.90 USD
+#    x.amount
+#    # => 135.9
+#    x.amount = 45.951
+#    x.amount_money
+#    # => $45.95 USD
+#    x.amount
+#    # => 45.951
+#
+    module ClassMethods
+
+      # Defines a Money object attribute that is bound
+      # to other attributes. 
+      #
+      # Options:
+      #
+      #    :value => undef
+      #
+      # Defines the value attribute to use for storing the money value.
+      # Defaults to the attribute name.
+      #
+      # If this attribute is different from the attribute name,
+      # the money object will intercept #{value}=(x) to flush
+      # any cached Money object.
+      #
+      #    :readonly => false
+      #
+      # If true, the underlying attribute is readonly.  Thus the Money object
+      # cannot be cached.  This is useful for computed money values.
+      #
+      #    :rep => :float
+      #
+      # This option specifies how the value attribute stores Money values.
+      # if :rep is :rep, then the value is stored as a scaled integer as
+      # defined by the Currency.  
+      # If :rep is :float, or :integer the corresponding #to_f or #to_i
+      # method is used.
+      # Defaults to :float.
+      #
+      #    :currency => undef
+      #
+      # Defines the attribute used to store and
+      # retrieve the Money's Currency 3-letter ISO code.
+      #
+      #    :currency_fixed => currency_code (e.g.: :USD)
+      #
+      # Defines the Currency to use for storing a normalized Money 
+      # value.
+      #
+      # All Money values will be converted to this Currency before
+      # storing.  This allows SQL summary operations, 
+      # like SUM(), MAX(), AVG(), etc., to produce meaningful results,
+      # regardless of the initial currency specified.  If this
+      # option is used, subsequent reads will be in the specified
+      # normalization :currency_fixed.
+      #
+      #    :currency_preferred => undef
+      #
+      # Defines the name of attribute used to store and
+      # retrieve the Money's Currency ISO code.  This option can be used
+      # with normalized Money values to retrieve the Money value 
+      # in its original Currency, while
+      # allowing SQL summary operations on the normalized Money values
+      # to still be valid.
+      #
+      #    :currency_update => undef
+      #
+      # If true, the currency attribute is updated upon setting the
+      # money attribute.  
+      # 
+      #    :time => undef
+      #
+      # Defines the attribute used to 
+      # retrieve the Money's time.  If this option is used, each
+      # Money value will use this attribute during historical Currency
+      # conversions.
+      #
+      # Money values can share a time value with other attributes
+      # (e.g. a created_on column in ActiveRecord::Base).
+      #
+      # If this option is true, the money time attribute will be named
+      # "#{attr_name}_time" and :time_update will be true.
+      #
+      #    :time_update => undef
+      #
+      # If true, the Money time value is updated upon setting the
+      # money attribute.  
+      #
+      def attr_money(attr_name, *opts)
+        opts = Hash[*opts]
+
+        attr_name = attr_name.to_s
+        opts[:class] = self
+        opts[:name] = attr_name.intern
+        ::Currency::Money.register_money_attribute(opts)
+
+        value = opts[:value] || opts[:name]
+        opts[:value] = value
+        write_value = opts[:write_value] ||= "self.#{value} = "
+
+        # Intercept value setter?
+        if ! opts[:readonly] && value.to_s != attr_name.to_s
+          alias_accessor = <<-"end_eval"
+alias :before_money_#{value}= :#{value}=
+
+def #{value}=(__value)
+  @#{attr_name} = nil # uncache
+  self.before_money_#{value} = __value
+end
+
+end_eval
+        end 
+
+        # How to convert between numeric representation and Money.
+        rep = opts[:rep] ||= :float
+        to_rep = opts[:to_rep]
+        from_rep = opts[:from_rep]
+        if rep == :rep
+          to_rep = 'rep'
+          from_rep = '::Currency::Money.new_rep'
+        else
+          case rep
+          when :float
+            to_rep = 'to_f'
+          when :integer
+            to_rep = 'to_i'
+          else
+            throw ::Currency::Exception::InvalidMoneyValue.new("Cannot use value representation: #{rep.inspect}")
+          end
+          from_rep = '::Currency::Money.new'
+        end
+        to_rep = to_rep.to_s
+        from_rep = from_rep.to_s
+
+        # Money time values.
+        time = opts[:time]
+        write_time = ''
+        if time
+          if time == true
+            time = "#{attr_name}_time"
+            opts[:time_update] = true
+          end
+          read_time = "self.#{time}"
+        end
+        opts[:time] = time
+        if opts[:time_update]
+          write_time = "self.#{time} = #{attr_name}_money && #{attr_name}_money.time"
+        end
+        time ||= 'nil'
+        read_time ||= time
+
+        currency_fixed = opts[:currency_fixed]
+        currency_fixed &&= ":#{currency_fixed}"
+
+        currency = opts[:currency]
+        if currency == true
+          currency = currency.to_s
+          currency = "self.#{attr_name}_currency"
+        end
+        if currency
+          read_currency = "self.#{currency}"
+          if opts[:currency_update]
+            write_currency = "self.#{currency} = #{attr_name}_money.nil? ? nil : #{attr_name}_money.currency.code"
+          else
+            convert_currency = "#{attr_name}_money = #{attr_name}_money.convert(#{read_currency}, #{read_time})"
+          end
+        end
+        opts[:currency] = currency
+        write_currency ||= ''
+        convert_currency ||= ''
+
+        currency_preferred = opts[:currency_preferred]
+        if currency_preferred
+          currency_preferred = currency_preferred.to_s
+          read_preferred_currency = "@#{attr_name} = @#{attr_name}.convert(#{currency_preferred}, #{read_time})"
+          write_preferred_currency = "self.#{currency_preferred} = @#{attr_name}_money.currency.code"
+        end
+
+        currency ||= currency_fixed
+        read_currency ||= currency
+
+        alias_accessor ||= ''
+
+        validate ||= ''
+
+        if opts[:readonly]
+          eval_opts = [ (opts[:module_eval] = x = <<-"end_eval"), __FILE__, __LINE__ ]
+#{validate}
+
+def #{attr_name}
+  #{attr_name}_rep = #{value}
+  if #{attr_name}_rep != nil
+    #{attr_name} = #{from_rep}(#{attr_name}_rep, #{read_currency} || #{currency}, #{read_time} || #{time})
+    #{read_preferred_currency}
+  else
+    #{attr_name} = nil
+  end
+  #{attr_name}
+end
+
+end_eval
+        else
+          eval_opts = [ (opts[:module_eval] = x = <<-"end_eval"), __FILE__, __LINE__ ]
+#{validate}
+
+#{alias_accessor}
+
+def #{attr_name}
+  unless @#{attr_name}
+    #{attr_name}_rep = #{value}
+    if #{attr_name}_rep != nil
+      @#{attr_name} = #{from_rep}(#{attr_name}_rep, #{read_currency} || #{currency}, #{read_time} || #{time})
+      #{read_preferred_currency}
+    end
+  end
+  @#{attr_name}
+end
+
+
+def #{attr_name}=(value)
+  if value == nil
+    #{attr_name}_money = nil
+  elsif value.kind_of?(Integer) || value.kind_of?(Float) || value.kind_of?(String)
+    #{attr_name}_money = ::Currency.Money(value, #{read_currency}, #{read_time})
+    #{write_preferred_currency}
+  elsif value.kind_of?(::Currency::Money)
+    #{attr_name}_money = value
+    #{write_preferred_currency}
+    #{convert_currency}
+  else
+    throw ::Currency::Exception::InvalidMoneyValue.new(value)
+  end
+
+  @#{attr_name} = #{attr_name}_money
+  #{write_value}(#{attr_name}_money.nil? ? nil : #{attr_name}_money.#{to_rep})
+  #{write_currency}
+  #{write_time}
+
+  value
+end
+
+end_eval
+      end
+
+      # $stderr.puts "   CODE = #{x}"
+      module_eval(*eval_opts)
+    end
+  end # module
+end # module
+
+
+# Use include ::Currency::Macro
+#::Object.class_eval do
+#  include Currency::Macro
+#end
+