currency 0.3.3 → 0.4.0

data/README.txt

@@ -35,6 +35,14 @@ Currency was developed by:
 
 * Kurt Stephens -- ruby-currency(at)umleta.com, sponsored by umleta.com
 
+== License
+
+* See LICENSE.txt
+
+== Copyright
+
+* Copyright (C) 2006-2007 Kurt Stephens <ruby-currency(at)umleta.com>
+
 == Contributors
 
 Maybe you?

data/Rakefile

@@ -1,6 +1,17 @@
 # Rakefile for currency      -*- ruby -*-
 # Adapted from RubyGems/Rakefile
-# upload_package NOT WORKING YET
+
+# For release
+"
+svn status
+rake make_manifest
+rake update_version
+rake package
+rake release VERSION=x.x.x
+rake svn_release
+rake publish_docs
+rake announce
+"
 
 #################################################################
 
@@ -8,10 +19,16 @@ require 'rubygems'
 require 'hoe'
 
 PKG_Name = 'Currency'
-PKG_DESCRIPTION = %{Currency models currencies, monetary values, foreign exchanges and rates.
+PKG_DESCRIPTION = %{Currency models currencies, monetary values, foreign exchanges and rates.  
+Pulls live rates from http://xe.com/.
 Supports ActiveRecord.
 
-See http://currency.rubyforge.org/files/lib/currency_rb.html for more details.
+For more details, see:
+
+http://currency.rubyforge.org/files/lib/currency_rb.html 
+http://currency.rubyforge.org/files/README.txt
+http://currency.rubyforge.org/
+
 }
 
 #################################################################
@@ -24,7 +41,7 @@ def get_release_notes(relfile = "Releases.txt")
   notes = [ ]
 
   File.open(relfile) do |f|
-    while line = f.readline
+    while ! f.eof && line = f.readline
       if md = /^== Release ([\d\.]+)/i.match(line)
         release = md[1]
         notes << line
@@ -32,7 +49,7 @@ def get_release_notes(relfile = "Releases.txt")
       end
     end
 
-    while line = f.readline
+    while ! f.eof && line = f.readline
       if md = /^== Release ([\d\.]+)/i.match(line)
         break
       end
@@ -47,6 +64,8 @@ end
 
 PKG_NAME = PKG_Name.gsub(/[a-z][A-Z]/) {|x| "#{x[0,1]}_#{x[1,1]}"}.downcase
 
+PKG_SVN_ROOT="svn+ssh://rubyforge.org/var/svn/#{PKG_NAME}/#{PKG_NAME}"
+
 release, release_notes = get_release_notes
 
 hoe = Hoe.new("currency", release) do |p|
@@ -75,12 +94,12 @@ version_rb = "lib/#{PKG_NAME}/#{PKG_NAME}_version.rb"
 task :update_version do
   announce "Updating #{PKG_Name} version to #{PKG_VERSION}: #{version_rb}"
   open(version_rb, "w") do |f|
-    f.puts "# DO NOT EDIT"
-    f.puts "# This file is auto-generated by build scripts."
-    f.puts "# See:  rake update_version"
     f.puts "module #{PKG_Name}"
     f.puts "  #{PKG_Name}Version = '#{PKG_VERSION}'"
     f.puts "end"
+    f.puts "# DO NOT EDIT"
+    f.puts "# This file is auto-generated by build scripts."
+    f.puts "# See:  rake update_version"
   end
   if ENV['RELTEST']
     announce "Release Task Testing, skipping commiting of new version"
@@ -91,6 +110,14 @@ end
 
 task version_rb => :update_version
 
+#################################################################
+# SVN
+#
+
+task :svn_release do
+  sh %{svn cp -m 'Release #{PKG_VERSION}' . #{PKG_SVN_ROOT}/release/#{PKG_VERSION}}
+end
+
 # task :test => :update_version
 
 
@@ -126,3 +153,10 @@ task :rubyfiles do
   puts Dir['bin/*'].reject { |fn| fn =~ /CVS|.svn|(~$)|(\.rb$)/ }
 end
 
+task :make_manifest do 
+  open("Manifest.txt", "w") do |f|
+    f.puts Dir['**/*'].reject { |fn| ! test(?f, fn) || fn =~ /CVS|.svn|([#~]$)|(.gem$)|(^pkg\/)|(^doc\/)/ }.sort.join("\n") + "\n"
+  end
+end
+
+

data/Releases.txt

@@ -1,5 +1,31 @@
 = Currency Release History
 
+== Release 0.4.0: 2007/02/21
+
+=== MAJOR CHANGES IN THIS RELEASE FOR HISTORICAL RATE DATA
+
+Some changes are not backwards-compatible
+
+* ActiveRecord::Base.money macro is deprecated, use ActiveRecord::Base.attr_money macro.
+* Currency::Exchange is now Currency::Exchange::Rate::Source
+  NOTE: Currency::Exchange::* is reserved for buying/selling currencies, not for providing rate data.
+* Refactored xe.com homepage rate source as a Currency::Exchange::Rate::Source::Xe.
+* Refactored Currency::Exchange::Test as Currency::Exchange::Rate::Source::Test.
+* Support for historical money values and rates using ActiveRecord.
+* Added Rate::Source::Historical::Writer.
+* Added newyorkfed.org XML rate source.
+* Added thefinancials.com XML rate source.
+* Refactored rate deriviation into Currency::Exchange::Rate::Deriver.
+* Refactored rate caching into Currency::Exchange::Rate::Source::TimedCache.
+* Added Money attribute macros for classes not using ActiveRecord.
+* Refactored time-based rate caching into Currency::Exchange::Rate::Source::TimedCache.
+* Refactored Currency::Currency#format into Currency::Formatter.  
+  NOTE: old formatting options as :no_* no longer supported.
+* Refactored Currency::Currency#parse into Currency::Parser.
+* Currency::CurrencyFactory is now Currency::Currency::Factory.
+* Preliminary Currency::Exchange::Rate::Source::Failover.
+* Added copyright notices: LICENSE.txt, COPYING.txt.
+
 == Release 0.3.3: 2006/10/31
 
 * Inclusion of README.txt and Releases.txt into documentation.

data/TODO.txt

@@ -0,0 +1 @@
+

data/examples/ex1.rb

@@ -1,13 +1,13 @@
 $:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 
 require 'currency'
-require 'currency/exchange/test'
+require 'currency/exchange/rate/source/test'
 
-x = Currency::Money.new("1,203.43", 'USD')
+x = Currency::Money.new("1,203.43", :USD)
 
 puts x.to_s
 puts (x * 10).to_s
-puts (x * 33333).to_s
+puts (x * 33333).inspect
 
 puts x.currency.code.inspect
 

data/examples/xe1.rb

@@ -1,9 +1,10 @@
 $:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 
 require 'currency'
-require 'currency/exchange/xe'
+require 'currency/exchange/rate/source/xe'
 
-ex = Currency::Exchange::Xe.new()
+ex = Currency::Exchange::Rate::Source::Xe.new()
+Currency::Exchange::Rate::Source.current = ex
 
 puts ex.inspect
 puts ex.parse_page_rates.inspect

data/lib/currency.rb

@@ -1,4 +1,6 @@
-# -*- ruby -*-
+# Copyright (C) 2006-2007 Kurt Stephens <ruby-currency(at)umleta.com>
+#
+# See LICENSE.txt for details.
 #
 # = Currency
 #
@@ -7,6 +9,7 @@
 # * currencies 
 # * exchanges
 # * exchange rates
+# * exchange rate sources
 # * monetary values
 #
 # The core classes are:
@@ -14,6 +17,8 @@
 # * Currency::Money - uses a scaled integer representation of a monetary value and performs accurate conversions to and from string values.
 # * Currency::Currency - provides an object-oriented representation of a currency.
 # * Currency::Exchange::Base - the base class for a currency exchange rate provider.
+# * Currency::Exchange::Rate::Source::Base - the base class for an on-demand currency exchange rate data provider.
+# * Currency::Exchange::Rate::Source::Provider - the base class for a bulk exchange rate data provider.
 # * Currency::Exchange::Rate - represents a exchange rate between two currencies.
 #
 # 
@@ -21,8 +26,14 @@
 # exchange rates from http://xe.com/ :
 #
 #    require 'currency'
-#    require 'currency/exchange/xe'
+#    require 'currency/exchange/rate/source/xe'
 #    
+#    # Rate source initialization
+#    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
+#
 #    usd = Currency::Money('6.78', :USD)
 #    puts "usd = #{usd.format}"
 #    cad = usd.convert(:CAD)
@@ -42,11 +53,35 @@
 # In the example above, the entries.amount database column is an INTEGER that represents US cents. 
 # The currency code of the money value can be stored in an additional database column or a default currency can be used.
 #
+# == Recent Enhancements
+#
+# === Storage and retrival of historical exchange rates
+#
+# * See Currency::Exchange::Rate::Source::Historical
+# * See Currency::Exchange::Rate::Source::Historical::Writer
+#
+# === Automatic derivation of rates from base rates.
+#
+# * See Currency::Exchange::Rate::Deriver
+#
+# === Rate caching
+#
+# * See Currency::Exchange::Rate::Source::TimedCache
+#
+# === Rate Providers
+#
+# * See Currency::Exchange::Rate::Source::Xe
+# * See Currency::Exchange::Rate::Source::NewYorkFed
+# * See Currency::Exchange::Rate::Source::TheFinancials
+#
+# === Customizable formatting and parsing
+#
+# * See Currency::Formatter
+# * See Currency::Parser
+#
 # == Future Enhancements
 #
-# * storage and retrival of historical exchange rates
-# * exchange rate polling for population of historical rates
-# * support for inflationary rates within a currency, e.g. $10 USD in the year 1955 in 2006 USD.
+# * Support for inflationary rates within a currency, e.g. $10 USD in the year 1955 converted to 2006 USD.
 # 
 # == SVN Repo
 #
@@ -62,17 +97,44 @@
 #
 # == Support
 #
-# ruby-currency(at)umleta.com
+# http://rubyforge.org/forum/forum.php?forum_id=7643
+#
+# == Copyright
+#
+# Copyright (C) 2006-2007 Kurt Stephens <ruby-currency(at)umleta.com>
+#
+# See LICENSE.txt for details.
 #
+module Currency
+  # Use this function instead of Money#new:
+  #
+  #    Currency::Money("12.34", :CAD)
+  #
+  # Do not do this:
+  #
+  #    Currency::Money.new("12.34", :CAD)
+  #
+  # See Money#new.
+  def self.Money(*opts)
+    Money.new(*opts)
+  end
+end
 
-$:.unshift(File.dirname(__FILE__)) unless
-  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+$:.unshift(File.expand_path(File.dirname(__FILE__))) unless $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
 
+require 'currency/currency_version'
 require 'currency/exception'
 require 'currency/money'
-require 'currency/currency_factory'
 require 'currency/currency'
+require 'currency/currency/factory'
 require 'currency/money'
+require 'currency/formatter'
+require 'currency/parser'
 require 'currency/exchange'
+require 'currency/exchange/rate'
+require 'currency/exchange/rate/deriver'
+require 'currency/exchange/rate/source'
+require 'currency/exchange/rate/source/test'
+require 'currency/exchange/time_quantitizer'
 require 'currency/core_extensions'
 

data/lib/currency/active_record.rb

@@ -1,14 +1,54 @@
+# Copyright (C) 2006-2007 Kurt Stephens <ruby-currency(at)umleta.com>
+# See LICENSE.txt for details.
+
 require 'active_record/base'
 require File.join(File.dirname(__FILE__), '..', 'currency')
 
-module Currency
-  module ActiveRecord
+# See Currency::ActiveRecord::ClassMethods
+class ActiveRecord::Base
+    @@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
+
+
+# See Currency::ActiveRecord::ClassMethods
+module Currency::ActiveRecord
+    
     def self.append_features(base) # :nodoc:
       # $stderr.puts "  Currency::ActiveRecord#append_features(#{base})"
       super
       base.extend(ClassMethods)
     end
-      
+
+
 
 # == ActiveRecord Suppport
 #
@@ -18,29 +58,45 @@ module Currency
 #    require 'currency/active_record'
 #    
 #    class Entry < ActiveRecord::Base
-#       money :amount
+#       attr_money :amount
 #    end
 # 
     module ClassMethods
 
+      # Deprecated: use attr_money.
+      def money(*args)
+        $stderr.puts "WARNING: money(#{args.inspect}) deprecated, use attr_money: in #{caller(1)[0]}"
+        attr_money(*args)
+      end
+
+
       # Defines a Money object attribute that is bound
       # to a database column.  The database column to store the
       # Money value representation is assumed to be
-      # INTEGER.
+      # INTEGER and will store Money#rep values.
       #
       # Options:
       #
-      #    :currency => :USD
+      #    :column => undef
+      #
+      # Defines the column to use for storing the money value.
+      # Defaults to the attribute name.
+      #
+      # If this column is different from the attribute name,
+      # the money object will intercept column=(x) to flush
+      # any cached Money object.
+      #
+      #    :currency => currency_code (e.g.: :USD)
       #
       # Defines the Currency to use for storing a normalized Money 
-      # value.  
+      # value.
       #
       # All Money values will be converted to this Currency before
-      # storing in the column.  This allows SQL summary operations, 
+      # 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.  Defaults to :USD.
+      # normalization :currency.
       #
       #    :currency_column => undef
       #
@@ -59,22 +115,60 @@ module Currency
       # allowing SQL summary operations on the normalized Money values
       # to still be valid.
       #
-      def money(attr_name, *opts)
+      #    :time => undef
+      #
+      # Defines the name of 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).
+      #
+      # 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[:table] = self.table_name
+        opts[:attr_name] = attr_name.intern
+        ::ActiveRecord::Base.register_money_attribute(opts)
+
+        column = opts[:column] || opts[:attr_name]
+        opts[:column] = column
+
+        if column.to_s != attr_name.to_s
+          alias_accessor = <<-"end_eval"
+alias :before_money_#{column}=, :#{column}=
+
+def #{column}=(__value)
+  @{attr_name} = nil # uncache
+  before_money#{column} = __value
+end
+
+end_eval
+        end
 
         currency = opts[:currency]
 
         currency_column = opts[:currency_column]
         if currency_column && ! currency_column.kind_of?(String)
           currency_column = currency_column.to_s
-          currency_column = "#{attr_name}_currency"
+          currency_column = "#{column}_currency"
         end
         if currency_column
           read_currency = "read_attribute(:#{currency_column.to_s})"
           write_currency = "write_attribute(:#{currency_column}, #{attr_name}_money.nil? ? nil : #{attr_name}_money.currency.code.to_s)"
         end
+        opts[:currency_column] = currency_column
 
         currency_preferred_column = opts[:currency_preferred_column]
         if currency_preferred_column
@@ -83,23 +177,46 @@ module Currency
           write_preferred_currency = "write_attribute(:#{currency_preferred_column}, @#{attr_name}_money.currency.code)"
         end
 
+        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
+
         currency ||= ':USD'
+        time ||= 'nil'
 
         read_currency ||= currency
+        read_time ||= time
+
+        money_rep ||= "#{attr_name}_money.rep"
 
         validate = "# Validation\n"
         validate << "\nvalidates_numericality_of :#{attr_name}\n" unless opts[:allow_nil]
         validate << "\nvalidates_format_of :#{currency_column}, :with => /^[A-Z][A-Z][A-Z]$/\n" if currency_column && ! opts[:allow_nil]
 
-        module_eval (x = <<-"end_eval"), __FILE__, __LINE__
+ 
+        alias_accessor ||= ''
+
+        module_eval (opts[:module_eval] = x = <<-"end_eval"), __FILE__, __LINE__
 #{validate}
 
+#{alias_accessor}
+
 def #{attr_name}
   # $stderr.puts "  \#{self.class.name}##{attr_name}"
   unless @#{attr_name}
-    #{attr_name}_rep = read_attribute(:#{attr_name})
+    #{attr_name}_rep = read_attribute(:#{column})
     unless #{attr_name}_rep.nil?
-      @#{attr_name} = Currency::Money.new_rep(#{attr_name}_rep, #{read_currency} || #{currency})
+      @#{attr_name} = ::Currency::Money.new_rep(#{attr_name}_rep, #{read_currency} || #{currency}, #{read_time} || #{time})
       #{read_preferred_currency}
     end
   end
@@ -108,21 +225,22 @@ end
 
 def #{attr_name}=(value)
   if value.nil?
-    ;
+    #{attr_name}_money = nil
   elsif value.kind_of?(Integer) || value.kind_of?(String) || value.kind_of?(Float)
-    #{attr_name}_money = Currency::Money.new(value, #{currency})
+    #{attr_name}_money = ::Currency::Money(value, #{currency})
     #{write_preferred_currency}
-  elsif value.kind_of?(Money)
+  elsif value.kind_of?(::Currency::Money)
     #{attr_name}_money = value
     #{write_preferred_currency}
     #{write_currency ? write_currency : "#{attr_name}_money = #{attr_name}_money.convert(#{currency})"}
   else
-    throw Currency::Exception::InvalidMoneyValue.new(value)
+    throw ::Currency::Exception::InvalidMoneyValue.new(value)
   end
 
   @#{attr_name} = #{attr_name}_money
   
-  write_attribute(:#{attr_name}, #{attr_name}_money.nil? ? nil : #{attr_name}_money.rep)
+  write_attribute(:#{column}, #{attr_name}_money.nil? ? nil : #{money_rep})
+  #{write_time}
 
   value
 end
@@ -130,7 +248,7 @@ end
 def #{attr_name}_before_type_cast
   # FIXME: User cannot specify Currency
   x = #{attr_name}
-  x &&= x.format(:no_symbol, :no_currency, :no_thousands)
+  x &&= x.format(:symbol => false, :currency => false, :thousands => false)
   x
 end
 
@@ -138,7 +256,6 @@ end_eval
         # $stderr.puts "   CODE = #{x}"
       end
     end
-  end
 end