/ 
Locale-Object-0.81_02
River stage one • 2 direct dependents • 5 total dependents
/ Locale::Object

NAME

Locale::Object - An object-oriented representation of locale information.

DESCRIPTION

The Locale::Object group of modules attempts to provide locale-related information in an object-oriented fashion. The information is collated from several sources and provided in an accompanying DBD::SQLite database.

At present, the modules are:

For more information, see the documentation for those modules. The database is documented in Locale::Object::Database. Locale::Object itself can be used to create compound objects containing country, currency and language objects.

SYNOPSIS

use Locale::Object;

my $obj = Locale::Object->new(
                              country_code_alpha2  => 'gb',
                              currency_code        => 'GBP',
                              language_code_alpha2 => 'en'
                             );

$obj->country_code_alpha2('af');
$obj->country_code_alpha3('afg');

$obj->currency_code('AFA');
$obj->currency_code_numeric('004');

$obj->language_code_alpha2('ps');
$obj->language_code_alpha3('pus');
$obj->language_name('Pushto');

my $country  = $obj->country;
my $currency = $obj->currency;
my $language = $obj->language;

$obj->empty('language');

print $obj->sane('country');

$obj->make_sane(
                attribute => 'country'
                populate  => 1
               );

METHODS

new()

my $obj = Locale::Object->new(
                              country_code_alpha2  => 'gb',
                              currency_code        => 'GBP',
                              language_code_alpha2 => 'en'
                             );

Creates a new object. With no parameters, the object will be blank. Valid parameters match the method names that follow.

country_code_alpha2(), country_code_alpha3()

$obj->country_code_alpha2('af');
$obj->country_code_alpha3('afg');

Sets the country attribute in the object by alpha2 and alpha3 codes. Will create a new Locale::Object::Country object and set that as the attribute. Because Locale::Object::Country objects all have single instances, if one has already been created by that code, it will be reused when you do this.

country_code(), currency_code_numeric()

$obj->currency_code('AFA');
$obj->currency_code_numeric('004');

Serves the same purpose as the previous methods, only for the currency attribute, a Locale::Object::Currency object.

language_code_alpha2(), language_code_alpha3(), language_name()

$obj->language_code_alpha2('ps');
$obj->language_code_alpha3('pus');
$obj->language_name('Pushto');

Serves the same purpose as the previous methods, only for the language attribute, a Locale::Object::Language object.

Retrieving and Removing Attributes

country(), language(), currency()

While the foregoing methods can be used to set attribute objects, to retrieve those objects' own attributes you will have to use their own methods. The country(), language() and currency() methods return the objects stored as those attributes, if they exist.

my $country_tzone = $country->timezone->name;
my $language_name = $obj->language->name;
my $currency_code = $obj->currency->code;

See Locale::Object::Country, Locale::Object::Language and Locale::Object::Currency for more details on the subordinate methods.

empty()

$obj->empty('language');

Remove an attribute from the object. Can be one of country, currency, language.

Object Sanity

sane()

There will be occasions you want to know whether all the attributes in your object make sense with each other - questions such as "is the currency of the object used in the country?" or "Do they speak the language of the object in that country?" For that, use sane().

print $obj->sane('country');

Returns 1 if the two remaining attributes in the object make sense compared against the attribute name you specify (if not specified, country is the default); otherwise, 0. The following table explains what's needed for a result of 1. Note: if an attribute doesn't exist, it's not *not* sane, so checking sanity against an attribute in an object with no other attributes will give a result of 1.

If sane against | country must          | language must          | currency must
-----------------------------------------------------------------------------------------
country         | n/a                   | be used in the country | be used in the country
-----------------------------------------------------------------------------------------
language        | be using the language | n/a                    | be used in a country
                |                       |                        | speaking the language
-----------------------------------------------------------------------------------------
currency        | use the currency      | be spoken in a country | n/a
                |                       | using the currency     |

make_sane()

$obj->make_sane(
                attribute => 'country'
                populate  => 1
               );

This method will do its best to make the attributes of the object correspond with each other. The attribute you specify as a parameter will be taken to align against (default is country if none specified). If you specify populate as 1, any empty attributes in the object will be filled. Provisos:

1) Languages can be used in multiple countries. If you make_sane against language, to pick a country the module will choose the first country it finds that uses the language officially.
2) A similar situation exists for currencies. If a language attribute already exists, the module will pick the first country it finds that speaks the language and uses the currency. Otherwise, it will select the first country in its list of countries using the currency.

AUTHOR

Originally by Earle Martin

COPYRIGHT AND LICENSE

Originally by Earle Martin. To the extent possible under law, the author has dedicated all copyright and related and neighboring rights to this software to the public domain worldwide. This software is distributed without any warranty. You should have received a copy of the CC0 Public Domain Dedication along with this software. If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.

SEE ALSO

Locale::Codes, for simple conversions between names and ISO codes.