File Coverage

blib/lib/Geo/CountryFlags.pm

Criterion	Covered	Total	%
statement	31	35	88.5
branch	13	18	72.2
condition	1	3	33.3
subroutine	6	6	100.0
pod	3	3	100.0
total	54	65	83.0

#!/usr/bin/perl
package Geo::CountryFlags;
use strict;
use Geo::CountryFlags::I2C;
use vars qw($VERSION);
$VERSION = do { my @r = (q$Revision: 1.01 $ =~ /\d+/g); sprintf "%d."."%02d" x $#r, @r };

my $i2c = subref Geo::CountryFlags::I2C;

=head1 NAME

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

=head1 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);

=head1 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);
    ....
  }

=head1 METHODS

=over 4

=item $gcf = new Geo::CountryFlags;

  input:	none
  returns:	blessed package reference

=cut

sub new {
  my $proto = shift;
  my $class = ref($proto) || $proto;
  my $self  = {};
  bless $self, $class;
}

=item $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)

=cut

my $gcu;

sub get_flag {
  my ($self,$cc,$fd) = @_;
  return undef unless $cc;
  $fd = './flags' unless $fd;
  unless ( -e $fd) {
    if (-d $fd) {
      eval {die "$fd is not a directory"};
      return undef;
    } else {
      mkdir $fd, 0755;
    }
  }
  undef $@;
  my $fp = $fd .'/'. $cc .'-flag.gif';
  return $fp if -e $fp;			# return flag if it exists

  my $cia = $i2c->($cc) or return undef;
  require LWP::Simple;
  unless ($gcu) {
    require Geo::CountryFlags::URLs;
    $gcu = new Geo::CountryFlags::URLs;
  }
  return undef unless eval {		# response must be 200, OK
	200 == ($_ = &LWP::Simple::getstore(
		$gcu->CIAFLAGS . $cia .'-flag.gif',
		$fp)) ||
		die $_
	};
  return $fp;
}

=item $cia_code=$gf->cc2cia($country_code);

  input:	country code
  output:	cia code
		  or
		undef is cia code
		is known absent

=cut

sub cc2cia {
  shift;
  goto &$i2c;
}

=pod

=back

=cut

1;
__END__