currency 0.1.2 → 0.2.0

data/Rakefile

@@ -12,7 +12,7 @@ require 'hoe'
 PKG_Name = 'Currency'
 PKG_NAME = PKG_Name.gsub(/[a-z][A-Z]/) {|x| "#{x[0,1]}_#{x[1,1]}"}.downcase
 
-hoe = Hoe.new("currency", '0.1.2') do |p|
+hoe = Hoe.new("currency", '0.2.0') do |p|
   p.author = 'Kurt Stephens'
   p.description = %{Currency models currencies, monetary values, foreign exchanges.}
   p.email = "ruby-#{PKG_NAME}@umleta.com"

data/lib/currency.rb

@@ -1,16 +1,7 @@
 # -*- ruby -*-
-
-$:.unshift(File.dirname(__FILE__)) unless
-  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
-
-require 'currency/exception'
-require 'currency/money'
-require 'currency/currency_factory'
-require 'currency/currency'
-require 'currency/money'
-require 'currency/exchange'
-require 'currency/core_extensions'
-
+#
+# = Currency
+#
 # The Currency package provides an object-oriented model of:
 #
 # * currencies 
@@ -22,10 +13,12 @@ require 'currency/core_extensions'
 #
 # * 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::Base - the base class for a currency exchange rate provider.
 # * Currency::Exchange::Rate - represents a exchange rate between two currencies.
 #
-# Below is a basic example:
+# 
+# The example below uses Currency::Exchange::Xe to automatically get 
+# exchange rates from http://xe.com/ :
 #
 #    require 'currency'
 #    require 'currency/exchange/xe'
@@ -35,8 +28,6 @@ require 'currency/core_extensions'
 #    cad = usd.convert(:CAD)
 #    puts "cad = #{cad.format}"
 #
-# The example above uses Currency::Exchange::Xe automatically get exchange rates from http://xe.com/.
-#
 # == ActiveRecord Suppport
 #
 # This package also contains ActiveRecord support for money values:
@@ -63,7 +54,25 @@ require 'currency/core_extensions'
 #
 # == Examples
 #
-# * The "test programs":http://rubyforge.org/cgi-bin/viewvc.cgi/currency/trunk/examples?root=currency
-# * The "test cases":http://rubyforge.org/cgi-bin/viewvc.cgi/currency/trunk/test/?root=currency
+# See the examples/ and test/ directorys
 #
+# == Author
+#
+# Kurt Stephens http://kurtstephens.com
+#
+# == Support
+#
+# ruby-currency(at)umleta.com
+#
+
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'currency/exception'
+require 'currency/money'
+require 'currency/currency_factory'
+require 'currency/currency'
+require 'currency/money'
+require 'currency/exchange'
+require 'currency/core_extensions'
 

data/lib/currency/active_record.rb

@@ -9,7 +9,53 @@ module Currency
       base.extend(ClassMethods)
     end
       
+
+# == ActiveRecord Suppport
+#
+# This package also contains ActiveRecord support for money values:
+#
+#    require 'currency'
+#    require 'currency/active_record'
+#    
+#    class Entry < ActiveRecord::Base
+#       money :amount
+#    end
+# 
     module ClassMethods
+
+      # 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.
+      #
+      # Options:
+      #
+      #    :currency => :USD
+      #
+      # Defines the Currency to use for storing a normalized Money 
+      # value.  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.
+      #
+      #    :currency_field => undef
+      #
+      # Defines the name of the CHAR(3) column that is used to store and
+      # retrieve the Money's Currency code.  If this option is used, each
+      # record may use a different Currency to store the result, such
+      # that SQL summary operations, like SUM(), MAX(), AVG(), 
+      # may return meaningless results.
+      #
+      #    :currency_preferred_field => undef
+      #
+      # Defines the name of a CHAR(3) column used to store and
+      # retrieve the Money's Currency code.  This option can be used
+      # with normalize Money values to retrieve the Money value 
+      # in its original Currency, while
+      # allowing SQL summary operations on a normalized Money value
+      # to still be valid.
+      #
       def money(attr_name, *opts)
         opts = Hash.[](*opts)
 
@@ -22,6 +68,12 @@ module Currency
           currency = "read_attribute(:#{currency_field})"
         end
 
+        currency_preferred_field = opts[:currency_preferred_field]
+        if currency_preferred_field
+          read_preferred_currency = "@#{attr_name} = @#{attr_name}.convert(read_attribute(:#{:currency_preferred_field}))"
+          write_preferred_currency = "write_attribute(:#{currency_preferred_field}, @#{attr_name}_money.currency.code)"
+        end
+
         currency ||= ':USD'
 
         validate = ''
@@ -33,7 +85,10 @@ def #{attr_name}
   # $stderr.puts "  \#{self.class.name}##{attr_name}"
   unless @#{attr_name}
     #{attr_name}_rep = read_attribute(:#{attr_name})
-    @#{attr_name} = Money.new_rep(#{attr_name}_rep, #{currency}) unless #{attr_name}_rep.nil?
+    unless #{attr_name}_rep.nil?
+      @#{attr_name} = Money.new_rep(#{attr_name}_rep, #{currency})
+      #{read_preferred_currency}
+    end
   end
   @#{attr_name}
 end
@@ -42,7 +97,9 @@ def #{attr_name}=(value)
     ;
   elsif value.kind_of?(Integer) || value.kind_of?(String) || value.kind_of?(Float)
     #{attr_name}_money = Money.new(value, #{currency})
+    #{write_preferred_currency}
   elsif value.kind_of?(Money)
+    #{write_preferred_currency}
     #{attr_name}_money = value.convert(#{currency})
   else
     throw "Bad money format \#{value.inspect}"
@@ -53,6 +110,7 @@ def #{attr_name}=(value)
   value
 end
 def #{attr_name}_before_type_cast
+  # FIX ME, User cannot specify Currency
   x = #{attr_name}
   x &&= x.format(:no_symbol, :no_currency, :no_thousands)
   x

data/lib/currency/core_extensions.rb

@@ -1,21 +1,24 @@
-#  
-# External representation mixins
-#
-class Integer # Exact
+# External representation mixin
+class Integer 
+  # Exact
   def Money_rep(currency)
     Integer(self * currency.scale)
   end
 end
 
 
-class Float # Inexact
+# External representation mixin
+class Float 
+  # Inexact
   def Money_rep(currency)  
     Integer(self * currency.scale) 
   end
 end
 
 
-class String # Exact
+# External representation mixin
+class String
+  # Exact
   def Money_rep(currency)
     x = currency.parse(self, :currency => currency)
     x.rep if x.kind_of?(Currency::Money)

data/lib/currency/currency.rb

@@ -1,49 +1,73 @@
+# -*- ruby -*-
+#
+# = Currency::Currency
+#
+# Represents a currency.
+#
+#
+
 module Currency
   #include Currency::Exceptions
 
   class Currency
-    # Create a new currency
+    # Create a new currency.
+    # This should only be called from Currency::CurrencyFactory.
     def initialize(code, symbol = nil, scale = 100)
       self.code = code
       self.symbol = symbol
       self.scale = scale
     end
 
+    # Returns the Currency object from the default CurrencyFactory
+    # by its 3-letter uppercase Symbol name, such as :USD, or :CAD.
     def self.get(code)
       CurrencyFactory.default.get_by_code(code)
     end
 
+    # Internal method for converting currency codes to internal
+    # Symbol format.
     def self.cast_code(x)
      x = x.upcase.intern if x.kind_of?(String)
-     raise InvalidCurrencyCode.new(x) unless x.kind_of?(Symbol)
+     raise Exception::InvalidCurrencyCode.new(x) unless x.kind_of?(Symbol)
+     raise Exception::InvalidCurrencyCode.new(x) unless x.to_s.length == 3
      x
     end
 
+    # Returns the hash of the Currency's code.
     def hash
       @code.hash
     end
 
+    # Returns true if the Currency's are equal.
     def eql?(x)
       self.class == x.class && @code == x.code
     end
 
+    # Returns true if the Currency's are equal.
     def ==(x)
       self.class == x.class && @code == x.code
     end
 
-    # Accessors
+    # Get the Currency's code.
     def code
       @code
     end
+
+
+    # Client should never call this directly.
     def code=(x)
       x = self.class.cast_code(x) unless x.nil?
       @code = x
       #$stderr.puts "#{self}.code = #{@code}"; x
     end
 
+    # Get the Currency's scale factor.  
+    # E.g: the :USD scale factor is 100.
     def scale
       @scale
     end
+
+    # Client should never call this directly.
     def scale=(x)
       @scale = x
       return x if x.nil?
@@ -53,21 +77,32 @@ module Currency
       x
     end
 
+    # Get the Currency's scale factor.  
+    # E.g: the :USD scale factor is 2, where 10 ^ 2 == 100.
     def scale_exp
       @scale_exp
     end
 
+    # Get the Currency's symbol. 
+    # E.g. :USD, :CAD, etc.
     def symbol
       @symbol
     end
+
+    # Client should never call this directly.
     def symbol=(x)
       @symbol = x
     end
 
-    # Parse a Money string
+    # Parse a Money string.
+    # Options:
+    #   :currency => Currency object.
+    # Look for a matching currency code at the beginning or end of the string.
+    # If the currency does not match IncompatibleCurrency is raised.
+    #
     def parse(str, *opt)
       x = str
-      opt = Hash.[](*opt)
+      opt = Hash[*opt]
 
       md = nil # match data
 
@@ -79,7 +114,7 @@ module Currency
         x = md[2]
         if curr != self
           if opt[:currency] && opt[:currency] != curr
-            raise IncompatibleCurrency.new("#{str} #{opt[:currency].code}")
+            raise Exception::IncompatibleCurrency.new("#{str} #{opt[:currency].code}")
           end
           return Money.new(x, curr);
         end
@@ -89,7 +124,7 @@ module Currency
         x = md[1]
         if curr != self
           if opt[:currency] && opt[:currency] != curr
-            raise IncompatibleCurrency.new("#{str} #{opt[:currency].code}")
+            raise Exception::IncompatibleCurrency.new("#{str} #{opt[:currency].code}")
           end
           return Money.new(x, curr);
         end
@@ -136,7 +171,7 @@ module Currency
       else
         # $stderr.puts "'#{self}'.parse(#{str}) => ??? '#{x}'"
         #x.to_f.Money_rep(self)
-        raise InvalidMoneyString.new("#{str} #{self}")
+        raise Exception::InvalidMoneyString.new("#{str} #{self}")
       end
     end
 
@@ -194,22 +229,22 @@ module Currency
     #  @code.to_s
     #end
 
-    # Convience
-    # Default currency
+    # Returns the default CurrencyFactory's currency.
     def self.default
       CurrencyFactory.default.currency
     end
 
+    # Returns the USD Currency.
     def self.USD
       CurrencyFactory.default.USD
     end
 
+    # Returns the CAD Currency.
     def self.CAD
       CurrencyFactory.default.CAD
     end
-  end
-
 
-  # END MODULE
-end
+  end # class
+  
+end # module
 

data/lib/currency/currency_version.rb

@@ -2,5 +2,5 @@
 # This file is auto-generated by build scripts.
 # See:  rake update_version
 module Currency
-  CurrencyVersion = '0.1.2'
+  CurrencyVersion = '0.2.0'
 end

data/lib/currency/exception.rb

@@ -1,15 +1,41 @@
 module Currency
-  class Error < Exception; end
-
-  class InvalidMoneyString < Error
+  module Exception
   end
+end
   
-  class InvalidCurrencyCode < Error
-  end
+# Base class for all Currency::Exception.
+class Currency::Exception::Base < Exception
+end
+
+module Currency
+  module Exception
+    # Error during string parsing.
+    class InvalidMoneyString < Base
+    end
   
-  class IncompatibleCurrency < Error
-  end
+    # Error in Currency code formeat.
+    class InvalidCurrencyCode < Base
+    end
+    
+    # Error during conversion between currencies.
+    class IncompatibleCurrency < Base
+    end
+
+    # Error if an Exchange is not defined.
+    class UndefinedExchange < Base
+    end
+
+    # Error if a Currency is unknown.
+    class UnknownCurrency < Base
+    end
+
+    # Error if an Exchange cannot provide an Exchange::Rate.
+    class UnknownRate < Base
+    end
+
+    # Error if an Exchange::Rate is not valid.
+    class InvalidRate < Base
+    end
 
-  class UndefinedExchange < Error
   end
 end

data/lib/currency/exchange.rb

@@ -1,22 +1,44 @@
+# -*- ruby -*-
+#
+# = Currency::Exchange
+#
+# The Currency::Exchange package is responsible for
+# the conversion between currencies.
+#
+
 module Currency
 module 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 ||= Base.new
     end
+
+    # Sets the default Currency::Exchange object.
     def self.default=(x)
       @@default = x
     end
 
-    @@current = nil
+    # 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 UndefinedExchange, "Currency::Exchange.current not defined")
+      @@current || self.default || (raise 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
 end
 

data/lib/currency/exchange/base.rb

@@ -1,3 +1,14 @@
+# -*- ruby -*-
+#
+# = Currency::Exchange::Base
+#
+# The Currency::Exchange::Base class is the base class for
+# currency exchange rate providers.
+#
+# Currency::Exchange::Base subclasses are Currency::Exchange::Rate
+# factories.
+#
+
 module Currency
 module Exchange
 
@@ -7,42 +18,54 @@ module Exchange
 
     def initialize(*opt)
       @name = nil
-      @exchange_rate = { }
+      @rate = { }
     end 
 
+    # Converts Money m in Currency c1 to a new
+    # Money value in Currency c2.
     def convert(m, c2, c1 = nil)
       c1 = m.currency if c1 == nil
       if ( c1 == c2 )
         m
       else
-        Money.new(exchange_rate(c1, c2).convert(m, c1), c2)
+        Money.new(rate(c1, c2).convert(m, c1), c2)
       end
     end
 
-    def clear_exchange_rates
-      @exchange_rate.empty!
+    # Flush all cached Rate.
+    def clear_rates
+      @rate.empty!
     end
 
-    def clear_exchange_rate(c1, c2, recip = true)
-      @exchange_rate[c1.code.to_s + c2.code.to_s] = nil
-      @exchange_rate[c2.code.to_s + c1.code.to_s] = nil if recip
+    # Flush any cached Rate between Currency c1 and c2.
+    def clear_rate(c1, c2, recip = true)
+      @rate[c1.code.to_s + c2.code.to_s] = nil
+      @rate[c2.code.to_s + c1.code.to_s] = nil if recip
     end
 
-    def exchange_rate(c1, c2)
-      (@exchange_rate[c1.code.to_s + c2.code.to_s] ||= load_exchange_rate(c1, c2)) ||
-      (@exchange_rate[c2.code.to_s + c1.code.to_s] ||= load_exchange_rate(c2, c1))
+    # Returns the Rate between Currency c1 and c2.
+    #
+    # This will call #get_rate(c1, c2) if the
+    # Rate has not already been cached.
+    def rate(c1, c2)
+      (@rate[c1.code.to_s + c2.code.to_s] ||= get_rate(c1, c2)) ||
+      (@rate[c2.code.to_s + c1.code.to_s] ||= get_rate(c2, c1))
     end
 
     
-    def load_exchange_rate(c1, c2)
-      raise "Subclass responsibility: load_exchange_rate"
+    # Determines and creates the Rate between Currency c1 and c2.
+    #
+    # Subclasses are required to implement this method.
+    def get_rate(c1, c2)
+      raise Exception::UnknownRate.new("Subclass responsibility: get_rate")
     end
 
+    # Returns a simple string rep of an Exchange object.
     def to_s
       "#<#{self.class.name} #{self.name && self.name.inspect}>"
     end
 
-  end
+  end # class
 
   
 end # module

data/lib/currency/exchange/rate.rb

@@ -6,6 +6,7 @@ module Exchange
       @c1 = c1
       @c2 = c2
       @rate = c1_to_c2_rate
+      raise Exception::InvalidRate.new(@rate) unless @rate > 0.0
       @source = source
       @date = date || Time.now
       @reciprocal = recip

data/lib/currency/exchange/test.rb

@@ -1,10 +1,13 @@
+# This class is a test Exchange.
+# It can convert only between USD and CAD.
+
 module Currency
 module Exchange
 
-  # This class is a text Exchange.
-  # It can convert only between USD and CAD
   class Test < Base
     @@instance = nil
+
+    # Returns a singleton instance.
     def self.instance(*opts)
       @@instance ||= self.new(*opts)
     end
@@ -13,10 +16,11 @@ module Exchange
       super(*opts)
     end
 
-    # Sample constant.
+    # Test rate from :USD to :CAD.
     def self.USD_CAD; 1.1708; end
 
-    def load_exchange_rate(c1, c2)
+    # Returns test Rate for USD and CAD pairs. 
+    def get_rate(c1, c2)
       # $stderr.puts "load_exchange_rate(#{c1}, #{c2})"
       rate = 0.0
       if ( c1.code == :USD && c2.code == :CAD )
@@ -24,11 +28,12 @@ module Exchange
       end
       rate > 0 ? Rate.new(c1, c2, rate, self) : nil
     end
-  end
+
+  end # class
 
 end # module
 end # module
 
-# Install as current
+# Install as default.
 Currency::Exchange.default = Currency::Exchange::Test.instance
 

data/lib/currency/exchange/xe.rb

@@ -1,17 +1,24 @@
+# Connects to http://xe.com and parses "XE.com Quick Cross Rates"
+# from home page HTML.
+
 require 'net/http'
 require 'open-uri'
 
 module Currency
 module Exchange
-  # Represents connects to http://xe.com and groks "XE.com Quick Cross Rates"
 
   class Xe < Base
     @@instance = nil
+
+    # Returns a singleton instance.
     def self.instance(*opts)
       @@instance ||= self.new(*opts)
     end
 
+    # Defaults to "http://xe.com/"
     attr_accessor :uri
+
+    # This Exchange's name is the same as its #uri.
     def name
       uri
     end
@@ -22,6 +29,10 @@ module Exchange
       @rates = nil
     end
 
+    # Returns a cached Hash of rates:
+    #
+    #    xe.rates[:USD][:CAD] => 1.01
+    #
     def rates
       return @rates if @rates
 
@@ -34,6 +45,7 @@ module Exchange
       @rates
     end
 
+    # Returns the URI content.
     def get_page
       data = open(uri) { |data| data.read }
       
@@ -42,6 +54,8 @@ module Exchange
       data
     end
 
+    # Parses http://xe.com homepage HTML for
+    # quick rates of 10 currencies.
     def parse_page_rates(data = nil)
       data = get_page unless data
       
@@ -114,7 +128,9 @@ module Exchange
       rate
     end
 
-    def load_exchange_rate(c1, c2)
+    # Loads cached rates from xe.com and creates Rate objects
+    # for 10 currencies.
+    def get_rate(c1, c2)
       rates # Load rates
 
       # $stderr.puts "load_exchange_rate(#{c1}, #{c2})"
@@ -134,12 +150,13 @@ module Exchange
 
       rate > 0 ? Rate.new(c1, c2, rate, self, @rate_timestamp) : nil
     end
-  end
+
+  end # class
 
 end # module
 end # module
 
 
-# Install as current
+# Install as default.
 Currency::Exchange.default = Currency::Exchange::Xe.instance
 

data/lib/currency/money.rb

@@ -1,17 +1,54 @@
+# -*- ruby -*-
+#
+# = Currency::Money
+#
+# Represents an amount of money in a particular currency.
+#
+# A Money object stores its value using a scaled Integer representation
+# and a Currency object.
+#
+# TODO:
+# * Need to store a time, so we can use historical FX rates.
+#
+
 module Currency
 
-  # Represents an amount of money in a particular currency.
+  # Use this function instead of Money#new:
+  #
+  #    Currency::Money("12.34", :CAD)
   #
-  # NOTE: do we need to store a time, so we can use
-  # historical FX rates to convert?
+  # not
   #
+  #    Currency::Money.new("12.34", :CAD)
+  #
+  # See Money#new.
+  def self.Money(*opts)
+    Money.new(*opts)
+  end
+
   class Money
     include Comparable
 
-
-    # Construct from a pre-scaled external representation:
-    # Float, Integer, String, etc.
+    #
+    # Construct a Money value object 
+    # from a pre-scaled external representation:
+    # where x is a Float, Integer, String, etc.
+    #
+    # If a currency is not specified, Currency#default is used.
+    #
+    #    x.Money_rep(currency) 
+    #
+    # is invoked to coerce x into a Money representation value.
+    #
+    # For example:
+    #
+    #    123.Money_rep(:USD) => 12300
+    #
+    # Because the USD Currency object has a #scale of 100
+    #
     # See #Money_rep(currency) mixin.
+    # See Currency#Money() function.
+    #
     def initialize(x, currency = nil)
       # Xform currency
       currency = Currency.default if currency.nil?
@@ -32,6 +69,7 @@ module Currency
     def self.us_dollar(x)
       self.new(x, :USD)
     end
+    # Compatibility with Money package.
     def cents
       @rep
     end
@@ -43,33 +81,42 @@ module Currency
       x.set_rep(r)
       x
     end
+    # Construct from post-scaled internal representation
+    # using the same currency.
+    #    x = Currency::Money.new("1.98", :USD)
+    #    x.new_rep(100) => "$1.00 USD"
+    #
     def new_rep(r)
       x = self.class.new(0, @currency)
       x.set_rep(r)
       x
     end
 
-    # CLIENTS SHOULD NEVER CALL set_rep DIRECTLY!
+    # Do not call this method directly
+    # CLIENTS SHOULD NEVER CALL set_rep DIRECTLY.
+    # You have been warned in ALL CAPS.
     def set_rep(r)
       r = r.to_i unless r.kind_of?(Integer)
       @rep = r
     end
 
+    # Returns the money representation for the requested currency.
     def Money_rep(currency)
       $stderr.puts "@currency != currency (#{@currency.inspect} != #{currency.inspect}" unless @currency == currency
       @rep
     end
 
+    # Returns the money representation (usually an Integer).
     def rep
       @rep
     end
 
-    # Get the money's Currency
+    # Get the money's Currency.
     def currency
       @currency
     end
 
-    # Convert Money to another Currency
+    # Convert Money to another Currency.
     def convert(currency)
       currency = Currency.default if currency.nil?
       currency = Currency.get(currency) unless currency.kind_of?(Currency)
@@ -80,17 +127,24 @@ module Currency
       end
     end
 
-    # Relational operations on Money values.
+    # Hash for hash table: both value and currency.
+    # See #eql? below.
     def hash
       @rep.hash ^ @currency.hash
     end
 
+    # True if money values have the same value and currency.
     def eql?(x)
-      @rep == x.rep && @currency == x.currency
+      self.class == x.class && 
+        @rep == x.rep && 
+        @currency == x.currency
     end
 
+    # True if money values have the same value and currency.
     def ==(x)
-      @rep == x.rep && @currency == x.currency
+       self.class == x.class && 
+        @rep == x.rep && 
+        @currency == x.currency
     end
 
     def <=>(x)
@@ -104,70 +158,85 @@ module Currency
     # Operations on Money values.
 
 
+    #   - Money => Money
+    # Negates a Money value.
     def -@
-      # - Money => Money
       new_rep(- @rep)
     end
 
+    #    Money + (Number|Money) => Money
+    #
     # Right side maybe coerced to Money.
     def +(x)
-      # Money + (Number|Money) => Money
       new_rep(@rep + x.Money_rep(@currency))
     end
 
+    #    Money - (Number|Money) => Money
+    #
     # Right side maybe coerced to Money.
     def -(x)
-      # Money - (Number|Money) => Money
       new_rep(@rep - x.Money_rep(@currency))
     end
 
-    # Right side must be number
+    #    Money * Number => Money
+    #
+    # Right side must be number.
     def *(x)
-      # Money * Number => Money
-      new_rep(@rep * x)
+       new_rep(@rep * x)
     end
 
-    # Right side must be number or Money
+    #    Money / Money => Number (ratio)
+    #    Money / Number => Money
+    #
+    # Right side must be a number or Money.
+    # Right side Integers are not coerced to Float before
+    # division.
     def /(x)
       if x.kind_of?(self.class)
-        # Money / Money => ratio
         (@rep.to_f) / (x.Money_rep(@currency).to_f)
       else
-        # Money / Number => Money
         new_rep(@rep / x)
       end
     end
 
+    # Formats the Money value as a String.
     def format(*opt)
       @currency.format(self, *opt)
     end
 
-    # Coercions
+    # Formats the Money value as a String.
     def to_s(*opt)
       @currency.format(self, *opt)
     end
 
+    # Coerces the Money's value to a Float.
+    # May cause loss of precision.
     def to_f
       Float(@rep) / @currency.scale
     end
 
+    # Coerces the Money's value to an Integer.
+    # May cause loss of precision.
     def to_i
       @rep / @currency.scale
     end
 
+    # True if the Money's value is zero.
     def zero?
       @rep == 0
     end
 
+    # True if the Money's value is greater than zero.
     def positive?
       @rep > 0
     end
     
+    # True if the Money's value is less than zero.
     def negative?
       @rep < 0
     end
 
-    # Implicit currency conversions?
+    # Returns the Money's value representation in another currency.
     def Money_rep(currency)
       # Attempt conversion?
       if @currency != currency
@@ -178,6 +247,8 @@ module Currency
       end
     end
 
+    # Basic inspection, with symbol and currency code.
+    # The standard #inspect method is available as #inspect_deep.
     def inspect(*opts)
       self.format(:with_symbol, :with_currency).inspect
     end
@@ -185,9 +256,9 @@ module Currency
     # How to alias a method defined in an object superclass in a different class:
     define_method(:inspect_deep, Object.instance_method(:inspect))
     # How call a method defined in a superclass from a method with a different name:
-    #def inspect_deep(*opts)
-    #  self.class.superclass.instance_method(:inspect).bind(self).call 
-    #end
+    #    def inspect_deep(*opts)
+    #      self.class.superclass.instance_method(:inspect).bind(self).call 
+    #    end
 
   end # class
 

data/test/money_test.rb

@@ -1,8 +1,8 @@
-# REAL
+
 #require File.dirname(__FILE__) + '/../test_helper'
 
 require 'test/test_base'
-require 'currency' # For :type => :money
+require 'currency'
 
 module Currency
 
@@ -105,7 +105,7 @@ class MoneyTest < TestBase
   end
 
   def test_op
-    # Using default load_exchange_rate
+    # Using default get_rate
     assert_not_nil usd = Money.new(123.45, :USD)
     assert_not_nil cad = Money.new(123.45, :CAD)
 
@@ -160,6 +160,14 @@ class MoneyTest < TestBase
     assert_equal_float Exchange::Test.USD_CAD, m, 0.0001
   end
 
+  def test_invalid_currency_code
+    assert_raise Exception::InvalidCurrencyCode do
+      Money.new(123, :asdf)
+    end
+    assert_raise Exception::InvalidCurrencyCode do
+      Money.new(123, 5)
+    end
+  end
 end
 
 end # module

data/test/xe_test.rb

@@ -1,6 +1,3 @@
-# REAL
-#require File.dirname(__FILE__) + '/../test_helper'
-
 require 'test/test_base'
 require 'currency' # For :type => :money
 require 'currency/exchange/xe'

metadata

@@ -1,10 +1,10 @@
 --- !ruby/object:Gem::Specification 
-rubygems_version: 0.8.11
+rubygems_version: 0.9.0
 specification_version: 1
 name: currency
 version: !ruby/object:Gem::Version 
-  version: 0.1.2
-date: 2006-10-30 00:00:00 -05:00
+  version: 0.2.0
+date: 2006-10-31 00:00:00 -05:00
 summary: Currency models currencies, monetary values, foreign exchanges.
 require_paths: 
 - lib
@@ -26,6 +26,7 @@ required_ruby_version: !ruby/object:Gem::Version::Requirement
 platform: ruby
 signing_key: 
 cert_chain: 
+post_install_message: 
 authors: 
 - Kurt Stephens
 files: