/ 
Geo-CountryFlags-1.01
River stage zero No dependents
/ Geo::CountryFlags

NAME

Geo::CountryFlags - dynamically fetch flag gif's from CIA

SYNOPSIS

use Geo::CountryFlags

$gcf = new Geo::CountryFlags;

return a local path to the flag file fetch the file from CIA if necessary and put it in the flag directory

$flag_path = $gcf->get_flag($country_code,[flag_dir])

default:
flag_dir = ./flags

retrieve the CIA country code

$cia_code	= $gcf->cc2cia($country_code)

retrieve the ISO country name

$gci = new Geo::CountryFlags::ISO;
$country_name	= $gci->value($country_code);

retrieve the CIA country name

$gcc = new Geo::CountryFlags::CIA;
$country_name = $gcc->value($cia_code);

DESCRIPTION

Provides methods to display / retrieve flag gifs dynamically from the web site of the Central Intelligence Agency. Permanently caches a local copy of the flag gif in your web site sub directory.

The flags for all country codes as of module publication are included in the ./flags directory should you wish to install them. However, If LWP::Simple is installed, Geo::CountryFlags will fetch them as needed and store them in ./flags [default] or the directory of you choice on your web site.

To fetch a single flag PATH the usage is simply:

my $cc = 'US';	# country code

my $flag_path = Geo::CountryFlags->new->get_flag($cc);

for multiple flags:

$gcf = new Geo::CountryFlags;
for (blah.... blah) {
  my $cc = function_of(blah...);
  my $flag_path = $gcf->get_flag($cc);
  ....
}

METHODS

$gcf = new Geo::CountryFlags;
input:	none
returns:	blessed package reference
$flag_path=$gf->get_flag($country_code,[flag_dir]);
  input:	country code,
		flag directory (optional)
		  default = ./flags

  output:	path_to/flag.image
		or undef if the country 
		flag is not available

  $@	:	clear on normal return
		set to error if unable to 
		connect or retrieve file
		from target flag server
		(only set on undef return)
$cia_code=$gf->cc2cia($country_code);
  input:	country code
  output:	cia code
		  or
		undef is cia code
		is known absent

MODULE UPDATES

This module has several extensions that are auto-created by the data directly from the CIA and ISO web sites. To force a rebuild follow this procedure:

perl Makefile.PL
make realclean
perl Makefile.PL
make
make test
make install

This modules has two files that allow you to keep it up to date.

Valid_Urls
Map_Exceptions

  • Valid_Urls

    This file contains the valid URL's for the CIA flags page, the CIA flags directory and the ISO flag code text files. If these change, you can updated the Valid_Urls file then remake the module as follows:

    perl Makefile.PL
make
make test
make install

  • Map_Exceptions

    During the 'perl Makefile.PL' process, the unmatched entries from both the ISO and CIA data bases are printed in the terminal window. The Map_Exceptions file should be updated so that the left hand side contains the exact text from the ISO data that does not match and the right hand side contains at least the minimum text from the related CIA data that will uniquely match the ISO data.

UTILITIES

The ./util directory contains two utility programs

get_flags.pl
make_htm.pl

get_flags.pl names

lists all flags by: [sorted by country name]
  country-code, CIA-code, ISO country-name

get_flags.pl

retrieves all flags from CIA and stores 
in locally created directory ./flags

If run from the build directory after module installation, this script will create/update the flags directory with all available ISO flags matching the CIA database. If the module is remade from scratch with a

make realclean

this process will update the MANIFEST with the new flag list as well.

make_htm.pl

prints the text for an html page containing all
the flags sorted by country name from a 
local ./flags directory

DEPENDENCIES

File::SafeDO
LWP::Simple	[optional]

LWP::Simple is required for dynamic operation. If you are simply going to server static gifs from the flags directory without EVER fetching a new one from the CIA, then LWP::Simple is not needed.

Likewise, if you intend to use this module in conjunction with showing flags for IP addresses, then you want to have a look at either;

	Geo::IP::PurePerl
    or
	Geo::IP

AUTHOR

Michael Robinton michael@bizsystems.com

COPYRIGHT and LICENSE

Copyright 2003 - 2006 Michael Robinton, michael@bizsystems.com

This module is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version,

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

SEE ALSO

Geo::IP::PurePerl