/ 
Handel-0.99_07
River stage one • 2 direct dependents • 2 total dependents
/ Handel::Currency

NAME

Handel::Currency - Price container to do currency conversion/formatting

SYNOPSIS

use Handel::Currency;

my $curr = Handel::Currency->new(1.2);
print $curr->format();          # 1.20 USD
print $curr->format('CAD');     # 1.20 CAD
print $curr->format(undef, 'FMT_SYMBOL');   # $1.20

print 'Your price in Canadian Dollars is: ';
print $curr->convert('USD', 'CAD');

DESCRIPTION

The Handel::Currency module provides basic currency formatting within Handel. It can be used separately to format any number into a more friendly format:

my $price = 1.23;
my $currency = Handel::Currency->new($price);

print $currency->format;

A new Handel::Currency object is automatically returned within the shopping cart when calling subtotal, total, and price as an lvalue:

my $cart = Handel::Cart->search({id => '11111111-1111-1111-1111-111111111111'});

print $cart->subtotal;              # 12.9
print $cart->subtotal->format();    # 12.90 USD

By default, a Handel::Currency object will stringify to the original decimal based price.

CONSTRUCTOR

new

Arguments: $price

The create a new Handel::Currency instance, simply call new and pass in the price to be formatted:

my $currency = Handel::Currency->new(10.23);

METHODS

convert

Arguments: $from, $to [, $format, $options]

The convert method converts the given price from one currency to another using Finance::Currency::Convert::WebserviceX and returns a new currency object with the converted value.

In situations where Finance::Currency::Convert::WebserviceX isn't installed, convert simply returns 0.

If no from is specified, HandelCurrencyCode will be used instead.

convert throws a Handel::Exception::Argument if from or to aren't valid currency codes.

If format is true, the result of the conversion will also be formatted using the formatting options given or the default in HandelCurrencyFormat.

You can also simply chain the convert call into a format call.

my $price = Handel::Currency->new(1.25);
print $price->convert('USD', 'CAD')->format;

format

Arguments: $code [, $options]

Returns the freshly formatted price in a currency and format declared in Locale::Currency::Format. If no currency code or format are specified, the defaults values from Handel::ConfigReader are used. Currently those defaults are USD and FMT_STANDARD.

It is also acceptable to specify different default values. See "CONFIGURATION" and Handel::ConfigReader for further details.

In situations where Locale::Currency::Format isn't installed, format simply returns the price in its original format no harm no foul.

format throws a Handel::Exception::Argument if code isn't a valid currency code.

stringify

Returns value in scalar context. For now, this returns the same thing that was passed to new. This maybe change in the future.

value

Returns the original price value given to new. Always use this instead of relying on stringification when deflating currency objects in DBIx::Class schemas.

CONFIGURATION

HandelCurrencyCode

This sets the default currency code used when no code is passed into format. See Locale::Currency::Format for all available currency codes. The default code is USD.

HandelCurrencyFormat

This sets the default options used to format the price. See Locale::Currency::Format for all available currency codes. The default format used is FMT_STANDARD. Just like in Locale::Currency::Format, you can combine options using |.

SEE ALSO

Locale::Currency::Format, Finance::Currency::Convert::WebserviceX

AUTHOR

Christopher H. Laco
CPAN ID: CLACO
claco@chrislaco.com
http://today.icantfocus.com/blog/