mumboe-currency 0.5

data/lib/currency/money.rb

@@ -0,0 +1,295 @@
+# Copyright (C) 2006-2007 Kurt Stephens <ruby-currency(at)umleta.com>
+# See LICENSE.txt for details.
+
+#
+# Represents an amount of money in a particular currency.
+#
+# A Money object stores its value using a scaled Integer representation
+# and a Currency object.
+#
+# A Money object also has a time, which is used in conversions
+# against historical exchange rates.
+#
+class Currency::Money
+    include Comparable
+
+    @@default_time = nil
+    def self.default_time
+      @@default_time
+    end
+    def self.default_time=(x)
+      @@default_time = x
+    end
+
+    @@empty_hash = { }
+    @@empty_hash.freeze
+
+    #
+    # DO NOT CALL THIS DIRECTLY:
+    #
+    # See Currency.Money() function.
+    #
+    # 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.
+    #
+    def initialize(x, currency = nil, time = nil)
+      opts ||= @@empty_hash
+
+      # Set ivars.
+      currency = ::Currency::Currency.get(currency)
+      @currency = currency
+      @time = time || ::Currency::Money.default_time
+      @time = ::Currency::Money.now if @time == :now
+      if x.kind_of?(String)
+        if currency
+          m = currency.parser_or_default.parse(x, :currency => currency)
+        else
+          m = ::Currency::Parser.default.parse(x)
+        end
+        @currency = m.currency unless @currency
+        @time = m.time if m.time
+        @rep = m.rep
+      else
+        @currency = ::Currency::Currency.default unless @currency
+        @rep = x.Money_rep(@currency)
+      end
+
+    end
+
+    # Returns a Time.new
+    # Can be modifed for special purposes.
+    def self.now
+      Time.new
+    end
+
+    # Compatibility with Money package.
+    def self.us_dollar(x)
+      self.new(x, :USD)
+    end
+
+
+    # Compatibility with Money package.
+    def cents
+      @rep
+    end
+
+
+    # Construct from post-scaled internal representation.
+    def self.new_rep(r, currency = nil, time = nil)
+      x = self.new(0, currency, time)
+      x.set_rep(r)
+      x
+    end
+
+
+    # Construct from post-scaled internal representation.
+    # using the same currency.
+    #
+    #    x = Currency.Money("1.98", :USD)
+    #    x.new_rep(123) => USD $1.23
+    #
+    # time defaults to self.time.
+    def new_rep(r, time = nil)
+      time ||= @time
+      x = self.class.new(0, @currency, time)
+      x.set_rep(r)
+      x
+    end
+
+    # Do not call this method directly.
+    # CLIENTS SHOULD NEVER CALL set_rep DIRECTLY.
+    # You have been warned in ALL CAPS.
+    def set_rep(r) # :nodoc:
+      r = r.to_i unless r.kind_of?(Integer)
+      @rep = r
+    end
+
+    # Do not call this method directly.
+    # CLIENTS SHOULD NEVER CALL set_time DIRECTLY.
+    # You have been warned in ALL CAPS.
+    def set_time(time) # :nodoc:
+      @time = time
+    end
+
+    # Returns the Money representation (usually an Integer).
+    def rep
+      @rep
+    end
+
+    # Get the Money's Currency.
+    def currency
+      @currency
+    end
+
+    # Get the Money's time.
+    def time
+      @time
+    end
+
+    # Convert Money to another Currency.
+    # currency can be a Symbol or a Currency object.
+    # If currency is nil, the Currency.default is used.
+    def convert(currency, time = nil)
+      currency = ::Currency::Currency.default if currency.nil?
+      currency = ::Currency::Currency.get(currency) unless currency.kind_of?(Currency)
+      if @currency == currency
+        self
+      else
+        time = self.time if time == :money
+        ::Currency::Exchange::Rate::Source.current.convert(self, currency, time)
+      end
+    end
+
+
+    # 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)
+      self.class == x.class && 
+        @rep == x.rep && 
+        @currency == x.currency
+    end
+
+    # True if money values have the same value and currency.
+    def ==(x)
+       self.class == x.class && 
+        @rep == x.rep && 
+        @currency == x.currency
+    end
+
+    # Compares Money values.
+    # Will convert x to self.currency before comparision.
+    def <=>(x)
+      if @currency == x.currency
+        @rep <=> x.rep
+      else
+        @rep <=> convert(@currency, @time).rep
+      end
+    end
+
+
+    #   - Money => Money
+    #
+    # Negates a Money value.
+    def -@
+      new_rep(- @rep)
+    end
+
+    #    Money + (Money | Number) => Money
+    #
+    # Right side may be coerced to left side's Currency.
+    def +(x)
+      new_rep(@rep + x.Money_rep(@currency))
+    end
+
+    #    Money - (Money | Number) => Money
+    #
+    # Right side may be coerced to left side's Currency.
+    def -(x)
+      new_rep(@rep - x.Money_rep(@currency))
+    end
+
+    #    Money * Number => Money
+    #
+    # Right side must be Number.
+    def *(x)
+       new_rep(@rep * x)
+    end
+
+    #    Money / Money => Float (ratio)
+    #    Money / Number => Money
+    #
+    # Right side must be Money or Number.
+    # Right side Integers are not coerced to Float before
+    # division.
+    def /(x)
+      if x.kind_of?(self.class)
+        (@rep.to_f) / (x.Money_rep(@currency).to_f)
+      else
+        new_rep(@rep / x)
+      end
+    end
+
+    # Formats the Money value as a String using the Currency's Formatter.
+    def format(*opt)
+      @currency.format(self, *opt)
+    end
+
+    # 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
+
+    # Returns the Money's value representation in another currency.
+    def Money_rep(currency, time = nil)
+      # Attempt conversion?
+      if @currency != currency || (time && @time != time)
+	self.convert(currency, time).rep
+        # raise ::Currency::Exception::Generic, "Incompatible Currency: #{@currency} != #{currency}"
+      else
+        @rep
+      end
+    end
+
+    # Basic inspection, with symbol, currency code and time.
+    # The standard #inspect method is available as #inspect_deep.
+    def inspect(*opts)
+      self.format(:symbol => true, :code => true, :time => true)
+    end
+
+    # 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
+
+end # class
+

data/lib/currency/money_helper.rb

@@ -0,0 +1,13 @@
+# Copyright (C) 2006-2007 Kurt Stephens <ruby-currency(at)umleta.com>
+# See LICENSE.txt for details.
+
+module ActionView::Helpers::MoneyHelper
+     # Creates a suitable HTML element for a Money value field.
+     def money_field(object, method, options = {})
+       InstanceTag.new(object, method, self).to_input_field_tag("text", options)
+     end
+end
+
+
+ActionView::Base.load_helper(File.dirname(__FILE__))
+

data/lib/currency/parser.rb

@@ -0,0 +1,151 @@
+# Copyright (C) 2006-2007 Kurt Stephens <ruby-currency(at)umleta.com>
+# See LICENSE.txt for details.
+
+
+require 'rss/rss' # Time#xmlschema
+
+
+# This class parses a Money value from a String.
+# Each Currency has a default Parser.
+class Currency::Parser
+
+  SYMBOLS_FOR_PATTERN = Currency::Currency::Factory::UNIQUE_SYMBOLS.collect {|symbol| symbol.split("").collect {|c| c =~ /[a-z]/i ? c : '\\'+c }.join }.join("|")
+  VALID_MONEY_PATTERN = /^(([a-zA-z][a-zA-z][a-zA-z])|(#{SYMBOLS_FOR_PATTERN}))?\s*([\-\+\d,\.]+)\s*(([a-zA-z][a-zA-z][a-zA-z])|(#{SYMBOLS_FOR_PATTERN}))?(\d\d\d\d-\d\d-\d\dT\d\d:\d\d:\d\d(\.\d+)?Z)?$/
+
+  # The default Currency to use if no Currency is specified.
+  attr_accessor :currency
+
+  # If true and a parsed string contains a ISO currency code
+  # that is not the same as currency,
+  # #parse() will raise IncompatibleCurrency.
+  # Defaults to false.
+  attr_accessor :enforce_currency
+
+  # The default Time to use if no Time is specified in the string.
+  # If :now, time is set to Time.new.
+  attr_accessor :time
+
+  @@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 = { })
+    @time =
+      @enforce_currency =
+      @currency =
+      nil
+    opt.each_pair{ | k, v | self.send("#{k}=", v) }
+  end
+
+  def _parse(str) # :nodoc:
+    x = str
+    md = nil
+    time = nil
+    
+    convert_currency = nil
+    md = VALID_MONEY_PATTERN.match(x)
+    if md && !@currency
+      symbol = md[3] || md[7]
+      code = md[2] || md[6]
+      curr = Currency::Currency.get(code ? code.upcase : nil) || (symbol ? Currency::Currency::Factory.get_currency_from_symbol(symbol) : Currency::Currency.default)
+      x = md[4]
+      time = Time.xmlschema(md[8]) if md[8]
+      time ||= @time
+      time = Time.new if time == :now
+      currency = curr
+    else
+      currency = @currency || ::Currency::Currency.default
+      currency = ::Currency::Currency.get(currency)
+    end
+
+    # Remove placeholders and symbol.
+    x.gsub!(/[, ]/, '')
+    symbol = currency.symbol if symbol.nil?
+    x.gsub!(symbol, '') if symbol
+    
+    # Match: whole Currency value.
+    if md = /^([-+]?\d+)\.?$/.match(x)
+      x = ::Currency::Money.new_rep(md[1].to_i * currency.scale, currency, @time)
+      
+    # Match: fractional Currency value.
+    elsif md = /^([-+]?)(\d*)\.(\d+)$/.match(x)
+      sign = md[1]
+      whole = md[2]
+      part = md[3]
+      
+      if part.length != currency.scale
+        currency.scale = 10**part.length if part.length > 1
+        
+        # Pad decimal places with additional '0'
+        while part.length < currency.scale_exp
+          part << '0'
+        end
+        
+        # Truncate to Currency's decimal size. 
+        part = part[0 ... currency.scale_exp]        
+      end
+      
+      # Put the string back together:
+      whole = sign + whole + part
+      
+      x = whole.to_i
+      x = ::Currency::Money.new_rep(x, currency, time)
+    else
+      raise ::Currency::Exception::InvalidMoneyString, 
+      [
+       "#{str.inspect} #{currency} #{x.inspect}",
+       :string, str,
+       :currency, currency,
+       :state, x,
+      ]
+    end
+
+    # Do conversion.
+    if convert_currency
+      x = x.convert(convert_currency)
+    end
+
+    x
+  end
+  
+  @@empty_hash = { }
+  @@empty_hash.freeze
+
+  # Parse a Money string in this Currency.
+  #
+  #   "123.45".money       # Using default Currency.
+  #   => USD $123.45
+  #
+  #   "$123.45 USD".money   # Explicit Currency.
+  #   => USD $123.45
+  #
+  #   "CAD 123.45".money
+  #   => CAD $123.45
+  #  
+  #   "123.45 CAD".money(:USD)  # Incompatible explicit Currency.
+  #     !!! "123.45 CAD" USD (Currency::Exception::IncompatibleCurrency)
+  #
+  def parse(str, opt = @@empty_hash)
+    prs = self
+
+    unless opt.empty? 
+      prs = prs.clone
+      opt.each_pair{ | k, v | prs.send("#{k}=", v) }
+    end
+    
+    prs._parse(str)
+  end
+
+end # class
+
+

data/lib/currency.rb

@@ -0,0 +1,143 @@
+# Copyright (C) 2006-2007 Kurt Stephens <ruby-currency(at)umleta.com>
+#
+# See LICENSE.txt for details.
+#
+# = Currency
+#
+# The Currency package provides an object-oriented model of:
+#
+# * currencies 
+# * exchanges
+# * exchange rates
+# * exchange rate sources
+# * monetary values
+#
+# The core classes are:
+#
+# * 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.
+#
+# 
+# The example below uses Currency::Exchange::Xe to automatically get 
+# exchange rates from http://xe.com/ :
+#
+#    require 'currency'
+#    require 'currency/exchange/rate/deriver'
+#    require 'currency/exchange/rate/source/xe'
+#    require 'currency/exchange/rate/source/timed_cache'
+#    
+#    # 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)
+#    puts "cad = #{cad.format}"
+#
+# == ActiveRecord Suppport
+#
+# This package also contains ActiveRecord support for money values:
+#
+#    require 'currency'
+#    require 'currency/active_record'
+#    
+#    class Entry < ActiveRecord::Base
+#       money :amount
+#    end
+# 
+# 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
+#
+# * Support for inflationary rates within a currency, e.g. $10 USD in the year 1955 converted to 2006 USD.
+# 
+# == SVN Repo
+#
+#    svn checkout svn://rubyforge.org/var/svn/currency/currency/trunk
+#
+# == Examples
+#
+# See the examples/ and test/ directorys
+#
+# == Author
+#
+# Kurt Stephens http://kurtstephens.com
+#
+# == Support
+#
+# 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.expand_path(File.dirname(__FILE__))) unless $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'currency/currency_version'
+require 'currency/config'
+require 'currency/exception'
+require 'currency/money'
+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/test/string_test.rb

@@ -0,0 +1,54 @@
+# various tests to verify latest revisions
+require "test/test_base"
+require 'currency'
+
+module Currency
+
+  class StringTest < TestBase
+    def setup
+      super
+    end
+  
+    def test_beginning_with_code
+      assert_equal "¥424,535,953.00", "CNY424,535,953".money.to_s
+    end
+  
+    def test_beginning_with_symbol
+      assert_equal "₡42,525,924.87", "₡ 42525924.87".money.to_s
+    end
+  
+    def test_ending_with_code
+      assert_equal "₱324,402,482.00", "324402482 CUP".money.to_s
+    end
+  
+    def test_ending_with_symbol
+      assert_equal "IRR 2,445.00", "2445﷼".money.to_s(:symbol => false, :code => true)
+    end
+  
+    def test_unknown_code
+      assert_equal "CFA 15,000.00", "15000CFA".money.to_s(:symbol => true, :code => true)
+    end
+  
+    def test_invalid_symbol
+      assert_raise ::Currency::Exception::InvalidMoneyString do
+        "Σ424,000".money
+      end
+    end
+  
+    def test_invalid_format
+      assert_raise ::Currency::Exception::InvalidMoneyString do
+        "17 dollars".money
+      end
+    end
+  
+    def test_does_not_truncate_precision
+      assert_equal "$425.002", "425.002".money.to_s
+    end
+  
+    def test_pads_precision
+      assert_equal "$0.50", "0.5".money.to_s
+    end
+  
+  end
+
+end

data/test/test_base.rb

@@ -0,0 +1,44 @@
+# Copyright (C) 2006-2007 Kurt Stephens <ruby-currency(at)umleta.com>
+# See LICENSE.txt for details.
+
+# Base Test class
+
+require 'test/unit'
+require 'currency'
+require 'currency/exchange/rate/source/test'
+
+module Currency
+
+class TestBase < Test::Unit::TestCase
+  def setup
+    super
+    @rate_source ||= get_rate_source
+    Exchange::Rate::Source.default = @rate_source
+
+    # Force non-historical money values.
+    Money.default_time = nil
+  end
+
+
+  def get_rate_source
+    source = Exchange::Rate::Source::Test.instance
+    deriver = Exchange::Rate::Deriver.new(:source => source)
+  end
+
+  # Avoid "No test were specified" error.
+  def test_foo
+    assert true
+  end
+
+
+  # Helpers.
+  def assert_equal_float(x, y, eps = 1.0e-8)
+    d = (x * eps).abs
+    assert((x - d) <= y)
+    assert(y <= (x + d))
+  end
+
+end # class
+
+end # module
+