Handel::Compat::Currency(3)

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

SYNOPSIS
    use Handel::Compat::Currency;

    MyStorage->currency_class('Handel::Compt::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 [, $code, $formatoptions]

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);

You can also pass in the default currency code and/or currency format to be used.

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.

  convert

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

If no "from" or "formatoptions" is specified, the options passed to "new" and then "HandelCurrencyCode" and "HandelCurrencyFormat" 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 "new" and then "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;

  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: $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 "new" and then "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.

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

  name

Arguments $code

Returns the currency name for the specified currency code. If no currency code is specified, the currency code for the current object will be used. If that too is not specified, the code set in "HandelCurrencyCode" will be used.

"name" 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, Locale::Currency::Format, Finance::Currency::Convert::WebserviceX

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