Michael Robinton > Geo-CountryFlags-1.01 > Geo::CountryFlags

Download:
Geo-CountryFlags-1.01.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 1.01   Source  

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

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

syntax highlighting: