= Money $

This library aids one in handling money and different currencies. Features:

- Provides a Money class which encapsulates all information about an certain
  amount of money, such as its value and its currency.
- Represents monetary values as integers, in cents. This avoids floating point
  rounding errors.
- Provides APIs for exchanging money from one currency to another.
- Has the ability to parse a money string into a Money object.
- Provides ActiveRecord "has_money" method.

Resources:

- This fork: http://github.com/nofxx/money
- Website: http://money.rubyforge.org
- RDoc API: http://money.rubyforge.org
- Git repository: http://github.com/FooBarWidget/money/tree/master

== Download

Install stable releases with the following command:

  gem install nofxx-money

The development version (hosted on Github) can be installed with:

  gem sources -a http://gems.github.com
  gem install nofxx-money

== Usage

=== Synopsis

  require 'money'

  # 10.00 USD
  money = Money.new(1000, "USD")
  money.cents     # => 1000
  money.currency  # => "USD"

  Money.new(1000, "USD") == Money.new(1000, "USD")   # => true
  Money.new(1000, "USD") == Money.new(100, "USD")    # => false
  Money.new(1000, "USD") == Money.new(1000, "EUR")   # => false


=== Currency Exchange

Exchanging money is performed through an exchange bank object. The default
exchange bank object requires one to manually specify the exchange rate. Here's
an example of how it works:

  Money.add_rate("USD", "CAD", 1.24515)
  Money.add_rate("CAD", "USD", 0.803115)

  Money.us_dollar(100).exchange_to("CAD")  # => Money.new(124, "CAD")
  Money.ca_dollar(100).exchange_to("USD")  # => Money.new(80, "USD")

Comparison and arithmetic operations work as expected:

  Money.new(1000, "USD") <=> Money.new(900, "USD")   # => 1; 9.00 USD is smaller
  Money.new(1000, "EUR") + Money.new(10, "EUR") == Money.new(1010, "EUR")

  Money.add_rate("USD", "EUR", 0.5)
  Money.new(1000, "EUR") + Money.new(1000, "USD") == Money.new(1500, "EUR")

There is nothing stopping you from creating bank objects which scrapes
www.xe.com for the current rates or just returns <tt>rand(2)</tt>:

  Money.default_bank = ExchangeBankWhichScrapesXeDotCom.new


=== Ruby on Rails

Use the +has_many+ helper to embed the money object in your models.
The following example requires a +price_in_cents+ and a +price_currency+
fields.

config/enviroment.rb

  require.gem 'nofxx-money', :lib => 'money'

app/models/product.rb

  class Product < ActiveRecord::Base
    belongs_to :product
    has_money :price

    private
      validate :cents_not_zero

      def cents_not_zero
        errors.add("price_cents", "cannot be zero or less") unless cents > 0
      end

      validates_presence_of :sku, :currency
      validates_uniqueness_of :sku
  end

migration:

  create_table :products do |t|
    t.integer :price_cents
    t.string  :price_currency
  end


=== Default Currency

By default Money defaults to USD as its currency. This can be overwritten using

  Money.default_currency = "CAD"

If you use Rails, then environment.rb is a very good place to put this.


== TODO

* Better validation
* Interest (almost there..)