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