NAME

Locale::Country::SubCountry - Country names in English, and subcountry names in native scripts

Synopsis

#!/usr/bin/env perl

use strict;
use warnings;

use Locale::Country::SubCountry;

# ------------------------------

my($obj)             = Locale::Country::SubCountry -> new;
my($country)         = $obj -> all_countries;
my($country_id2name) = {map{($$_{id} => $$_{name})} @$country};
my($sub_country)     = $obj -> all_sub_countries;
$sub_country         = [map{ {%$_, country_name => $$country_id2name{$$_{country_id} } } } @$sub_country];

print map{"$$_{country_name} => $$_{name} => $$_{code}\n"} @$sub_country;

See scripts/demo.pl.

Description

Locale::Country::SubCountry provides subcountry names in their native scripts.

It also provides:

o ISO 3166-1 2 letter codes for countries

o ISO 3166-1 3 letter codes for countries

o ISO 3166-2 1 .. 5 letter codes for subcountries

o All this in an SQLite database

This module is light-weight, in that it uses neither DBIx::Class nor Moose.

Distributions

This module is available as a Unix-style distro (*.tgz).

See http://savage.net.au/Perl-modules/html/installing-a-module.html for help on unpacking and installing distros.

Installation

The Module Itself

Install Locale::Country::SubCountry as you would for any Perl module:

Run:

cpanm Locale::Country::SubCountry

or run:

sudo cpan Locale::Country::SubCountry

or unpack the distro, and then either:

perl Build.PL
./Build
./Build test
sudo ./Build install

or:

perl Makefile.PL
make (or dmake or nmake)
make test
make install

The Configuration File

All that remains is to tell Locale::Country::SubCountry your values for some options.

For that, see config/.htlocale.country.subcountry.conf.

But wait! Before editing that config file, run scripts/copy.config.pl. It will copy the config file using File::HomeDir, to a directory where the run-time code in Locale::Country::SubCountry will look for it.

shell>cd Locale-Country-SubCountry-1.00
shell>perl scripts/copy.config.pl

Under Debian, this directory will be $HOME/.perl/Locale-Country-SubCountry/. When you run copy.config.pl, it will report where it has copied the config file to.

Also, it will copy config/country.sqlite to the same directory, since this is where the code looks for that file too at run time.

Check the docs for File::HomeDir to see what your operating system returns for a call to my_dist_config().

The point of this is that after the module is installed, the config file will be easily accessible and editable without needing permission to write to the directory structure in which modules are stored.

That's why File::HomeDir and Path::Class are pre-requisites for this module.

All modules which ship with their own config file are advised to use the same mechanism for storing such files.

Constructor and Initialization

new() is called as my($builder) = Locale::Country::SubCountry -> new(k1 => v1, k2 => v2, ...).

It returns a new object of type Locale::Country::SubCountry.

Key-value pairs in accepted in the parameter list (see corresponding methods for details):

o (None as yet)

Methods

Methods

all_countries()

Read the whole 'countries' table.

Returns an arrayref, 1 element per country, where each element is a hashref with these keys:

o id

Unique identifier for the country. Actually the database's primary key.

o address_format

A string showing how to format an address in this country. Only set for some countries.

Split the string on '#' characters, to produce a format of N lines.

Replace the tokens ':X' with the corresponding data (if available).

o code2

The ISO3166-1 2-letter code for the country.

o code3

The ISO3166-1 3-letter code for the country.

o name

The name of the country, in English.

all_subcountries()

Read the whole 'sub_countries' table.

Returns an arrayref, 1 element per subcountry, where each element is a hashref with these keys:

o id

Unique identifier for the subcountry. Actually the database's primary key.

o country_id

The primary key into the 'countries' table.

o code

The ISO3166-2 1 .. 5-letter code for the country.

o name

The name of the subcountry, in the country's native script.

init()

For use by subclasses.

Sets default values for object attributes.

new()

For use by subclasses.

Machine-Readable Change Log

The file CHANGES was converted into Changelog.ini by Module::Metadata::Changes.

Version Numbers

Version numbers < 1.00 represent development versions. From 1.00 up, they are production versions.

Thanks

Many thanks are due to the people who chose to make osCommerce, PrestaShop, Zen Cart, etc, Open Source.

Support

Email the author, or log a bug on RT:

https://rt.cpan.org/Public/Dist/Display.html?Name=Locale::Country::SubCountry.

Author

Locale::Country::SubCountry was written by Ron Savage <ron@savage.net.au> in 2011.

Home page: http://savage.net.au/index.html.

Copyright

Australian copyright (c) 2011, Ron Savage.

All Programs of mine are 'OSI Certified Open Source Software';
you can redistribute them and/or modify them under the terms of
The Artistic License, a copy of which is available at:
http://www.opensource.org/licenses/index.html

cpanm Locale::Country::SubCountry

perl -MCPAN -e shell
install Locale::Country::SubCountry