Handel::Currency(3)

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

SYNOPSIS
    use Handel::Currency;

    my $price = Handel::Currency->new(1.2. 'USD');
    print $price;            # 1.20 USD
    print $price+1           # 2.2
    print $price->code;      # USD
    print $price->format;    # FMT_SYMBOL
    print $price->as_string; # 1.20 USD
    print $price->as_string('FMT_SYMBOL'); # $1.20

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

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

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

    print $currency->as_string;

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->as_string;   # 12.90 USD

Each Handel::Currency object will stringify to the original value except in string context, where it stringifies to the format specified in "format".

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 no code or format are supplied, future calls to "format", "code" and "convert" will use the "HandelCurrencyCode" and "HandelCurrencyFormat" environment variables.

METHODS

  as_string

Arguments: $format

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.

  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 unless "HandelCurrencyCode" is set.

  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 current currency code, convert will just return itself.

You can also chain the "convert" call into other method calls:

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

"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: $format

Gets/sets the format to be used when displaying this object as a formatted currency string.

If no format is defined, the defaults value "HandelCurrencyFormat" is 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 current 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
Sames as "as_string".

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

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