/ 
Handel-0.99_16
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. 'USD');
print $curr->format;             # 1.20 USD
print $curr->format('FMT_SYMBOL'); # $1.20

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

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 [, $code, $format]

To creates a new Handel::Currency object, simply call new and pass in the price to be formatted:

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

You can also pass in the default currency code and/or currency format to be used. If not code or format are supplied, future calls to format and convert will use the HandelCurrencyCode and HandelCurrencyFormat environment variables.

METHODS

code

Arguments: $code

Gets/sets the three letter currency code for the current currency object.

code throws a Handel::Exception::Argument if code isn't a valid currency code. If no code was passed during object creation, no code will be return by this method.

convert

Arguments: $code

Returns a new Handel::Currency object containing the converted price value.

If no code is specified for the current currency object, the HandelCurrencyCode will be used as the currency code to convert from. If the currency you are converting to is the same as the currency objects currency code, convert will just return itself.

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

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

convert throws a Handel::Exception::Argument if code isn't valid currency code or isn't defined.

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

converter_class

Arguments: $converter_class

Gets/sets the converter class to be used when converting currency numbers.

__PACKAGE__->currency_class('MyCurrencyConverter');

The converter class can be any class that supports the following method signature:

sub convert {
    my ($self, $price, $from, $to) = @_;

    return $converted_price;
};

A Handel::Exception exception will be thrown if the specified class can not be loaded.

format

Arguments: $options

Returns the freshly formatted price in a format declared in Locale::Currency::Format. If no format options are specified, the defaults values from new and then HandelCurrencyFormat are used. Currently the default format is FMT_STANDARD.

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

name

Returns the currency name for the currency objects currency code. If no currency code is set, the code set in HandelCurrencyCode will be used.

name throws a Handel::Exception::Argument if code used 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.

get_component_class

Arguments: $name

Gets the current class for the specified component name.

my $class = $self->get_component_class('item_class');

There is no good reason to use this. Use the specific class accessors instead.

set_component_class

Arguments: $name, $value

Sets the current class for the specified component name.

$self->set_component_class('item_class', 'MyItemClass');

A Handel::Exception exception will be thrown if the specified class can not be loaded.

There is no good reason to use this. Use the specific class accessors instead.

CONFIGURATION

HandelCurrencyCode

This sets the default currency code used when no code is passed into new. 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, Locale::Currency::Format, Finance::Currency::Convert::WebserviceX

AUTHOR

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