view release on metacpan or  search on metacpan

lib/Weather/GHCN/CountryCodes.pm  view on Meta::CPAN

  use Weather::GHCN::CountryCodes qw(:all);


=head1 DESCRIPTION

The B<CountryCodes> module provides functions to search a table of country
codes and country names using various search criteria.  It can also do a
direct lookup of a country entry using the 2-character GEC (formerly FIPS)
code.

The source for the mapping table is taken from the CIA World Factbook.  See
https://www.cia.gov/library/publications/the-world-factbook/appendix/appendix-d.html

The module is primarily for use by modules Weather::GHCN::Options, and 
Weather::GHCN::StationTable.

=cut

## no critic [ValuesAndExpressions::ProhibitVersionStrings]
## no critic [TestingAndDebugging::RequireUseWarnings]
## no critic [ProhibitSubroutinePrototypes]

use v5.18;  # minimum for Object::Pad

use feature 'signatures';
no warnings 'experimental::signatures';


package Weather::GHCN::CountryCodes;

our $VERSION = 'v0.0.011';

use Carp        qw(carp croak cluck confess);
use English     qw(-no_match_vars);
use Const::Fast;

use Exporter;
use parent 'Exporter';

# Items to export into callers namespace by default.
## no critic [Modules::ProhibitAutomaticExportation]
our @EXPORT = ( qw/ get_country_by_gec search_country  / );


my %Country;

# Preloaded methods go here.

# Constants

const my $EMPTY  => q();    # empty string
const my $SPACE  => q( );   # space character
const my $TAB    => qq(\t); # tab character
const my $TRUE   => 1;      # perl's usual TRUE
const my $FALSE  => not $TRUE; # a dual-var consisting of '' and 0


#############################################################################

# Load the %Country hash during the UNITCHECK phase, before any of the
# regular runtime code needs it.

UNITCHECK {
    my @lines = split m{ \n }xms, country_table();

    foreach my $line (@lines) {
        my ($entity, $gec, $iso2, $iso3, $isonum, $nato, $internet, $comment) = split m{ [|] }xms, $line;

        # skip table entries with no GEC
        next if $gec eq q(-);

        # check for duplicates, though there shouldn't be any
        croak "*W* country $entity with GEC $gec already exists"
            if $Country{$gec};

        $Country{$gec} = {
            'name'      => $entity,
            'gec'       => $gec,
            'iso2'      => $iso2,
            'iso3'      => $iso3,
            'isonum'    => $isonum,
            'nato'      => $nato,
            'internet'  => $internet,
            'comment'   => $comment
        };
    }
}

#############################################################################

=head1 FUNCTIONS

=head2 get_country_by_gec($code)

For a given GEC (FIPS) country code, return a hash containing the country
name and other country codes.  Returns empty if the code was not found.

=cut

sub get_country_by_gec ($code) {
    # uncoverable condition right
    return $Country{$code} // $EMPTY;
}

=head2 search_country( $search [, $type] )

Search the country table and return the entries which match the
search criteria.  The optional $type argument allows you to designate
which field the search criteria is to be matched against, as follows:

    name      does an unanchored pattern match on the country name
    gec       matches the GEC (formerly FIPS) country code
    iso2      matches the ISO 3166 2-character country code
    iso3      matches the ISO 3166 3-character country code
    isonum    matches the ISO 3166 country numeric code
    nato      matches the STANAG 1059 country code used by NATO
    internet  matches the internet country code (such as .ca)

If the search criteria is only two-characters long, then the type
defaults to gec.  To match a name, the search criteria must be longer
than three characters, otherwise you'll get results from matches against
gec or iso3.