ConvertibleCurrencies
=====================

This plugin allows easy conversion between currencies.


Automatic output conversion of currencies
=========================================

The ConvertibleCurrency#to_s method when called without parameters, checks the class attribute
output_currency for the currency to use. If the output_currency should not match it's own, it will
convert it before returning the string.

This can be exceptionally useful when used in an around_filter of your application.
The following example allows you to simply add ?currency=EUR to your query parameters and have
all currencies on the page in EUR, no matter what their original currency was:

def output_currency
	MultiCurrency.output_currency = params[:currency]
	yield
	MultiCurrency.output_currency = nil
end

Usage
=====

## Currency fields that come back from the database
# In most models you will find an expression like this:
currency_columns :payments_q1, :payments_q2, :payments_q3, :payments_q4,
    :payments_forecast, :commitments, :commitments_forecast, 
    :payments_up_to_end_of, :commitments_up_to_end_of,
	:year => lambda { |m| m.year }, :currency => lambda { |m| m.donor.currency }

# That line makes all listed columns of the model automatically return objects of the class ConvertibleCurrency, 
# so that you don't have to worry about about conversions later.
# The attributes +year+ and +currency+ take Proc objects that are used to determine the base year and 
# currency that is used in e.g. conversions.

## Converting other objects to currencies
# You can easily convert strings and numbers to currencies by using the .to_currency method.
# to_currency takes two arguments, the first is the actual currency second is the year which 
# defaults to the current year and on whose exchange rates further conversions will be based.

# Examples:
>> 1000.to_currency
=> #<Currency:0x112a8a8 @year=2008, @currency=nil, @base_value=1000.0>

>> "100,323,21".to_currency("EUR", 2007)
=> #<Currency:0x1129278 @year=2007, @currency="EUR", @base_value=100323.21>

 
## Working with currencies
# The ConvertibleCurrency class supports many powerful methods which are best explained by examples:

# The in method allows you to convert an object from one currency to another, based on the exchange rates
# from our database. Please note that you can't use it on "anonymous currencies" with no unit given, 
# as demonstrated below:

# Examples:
>> 1000.to_currency("EUR").in("GBP")
=> #<MultiCurrency::ConvertibleCurrency:0x297fd68 @year=2008, @currency="GBP", @base_value=670.0>

>> 1000.to_currency.in("GBP")
=> #MultiCurrency::ConversionOfAnonymousCurrency: Can't convert anonymous currency to GBP


# The most powerful method of the Currency class is definitely to_s which is called by Rails automatically whenever you
# try to output a Currency object in a template file. It will automatically add separators and a unit indicator to
# the amount.

# Examples:
>> 100.to_currency("SEK").to_s
=> "100 SEK"
>> 100000000.to_currency("SEK").in("EUR").to_s
=> "10,845,987 EUR"


# Usually .to_s will output the amount in the currency specified before.
# However, you can set MultiCurrency.output_currency to make it always return a certain currency, regardless of the 
# object's actual unit.
# This method is used in the output filter that allows you to add ?currency= to the URL
>> MultiCurrency.output_currency = "SEK"
=> "SEK"

>> 100.to_currency("GBP").to_s
=> "1,376 SEK"

>> 1000.to_currency("EUR").to_s
=> "9,220 SEK"


## Performing calculations on currencies
# The most important thing of course is to use currencies for calculations.
# The Currency class is smart enough to convert its objects to a common currency before it adds or subtracts them.
# It will always convert them to the currency of the element on the left side of the operator (e.g. + or -)

# Examples:
>> f = 1000.to_currency("EUR") + 200.to_currency("SEK")
=> #<Currency:0x295c264 @year=2008, @currency="EUR", @base_value=1021.69197396963>
>> f.to_s
=> "1,022 EUR"

>> f = 1000.to_currency("GBP") + 2000.to_currency("SEK")
=> #<Currency:0x2950720 @year=2008, @currency="GBP", @base_value=1145.33622559653>
>> f.to_s
=> "1,145 GBP"


## Don't try to add currency objects to ordinary numbers!
# The above examples make clear how calculations are handled internally.
# That's also the reason why you experienced errors like "Currency can't be coerced into Fixnum".
# If you would do e.g. 

>> 10 + 20.to_currency("EUR")

# Ruby can't be sure about the currency of the object on the left side, so that a calculation doesn't make sense.
# This can be circumvented in two ways. Either you convert the left side argument to a Currency object first,
# (e.g. 10.to_currency("EUR")) or you just exchange the operands to that the above examples becomes:

>> 20.to_currency("EUR") + 10

# In that case Ruby assumes that the currency of the right side operand equals the left side operand's unit and automatically
# converts it for you:
>> f = 20.to_currency("EUR") + 10
=> #<Currency:0x294d188 @year=2008, @currency="EUR", @base_value=30.0>
>> f.to_s
=> "30 EUR"



Copyright (c) 2008 Pascal Ehlert, ODAdata, released under the MIT license