package WebService::CIA;

require 5.005_62;
use strict;
use warnings;
use Carp;

our $VERSION = '1.4';

$WebService::CIA::base_url = "https://www.cia.gov/library/publications/the-world-factbook/";

sub new {

    my $proto = shift;
    my $opts = shift;
    my $class = ref($proto) || $proto;
    my $self = {};

    unless (exists $opts->{Source}) {
        croak("WebService::CIA: No source object specified");
    }
    $self->{SOURCE} = $opts->{Source};

    bless ($self, $class);
    return $self;

}

sub get {

    my $self = shift;
    my ($cc, $f) = @_;
    my $value = $self->source->value($cc, $f);
    return $value;

}

sub get_all_hashref {

    my $self = shift;
    my $country = shift;
    my $data = {};
    foreach my $cc (@$country) {
        $data->{$cc} = $self->source->all($cc);
    }
    return $data;

}

sub get_hashref {

    my $self = shift;
    my ($country, $field) = @_;
    my $data = {};
    foreach my $cc (@$country) {
         $data->{$cc} = {};
         foreach my $f (@$field) {
             $data->{$cc}->{$f} = $self->source->value($cc, $f);
         }
    }
    return $data;

}

sub source {

    my $self = shift;
    return $self->{SOURCE};

}

1;

__END__

=head1 NAME

WebService::CIA - Get information from the CIA World Factbook.


=head1 SYNOPSIS

  use WebService::CIA;
  use WebService::CIA::Source::DBM;
  use WebService::CIA::Source::Web;

  # Get data from a pre-compiled DBM file

  my $source = WebService::CIA::Source::DBM->new({ DBM => "factbook.dbm" });
  my $cia = WebService::CIA->new({ Source => $source });
  $fact = $cia->get("uk", "Population");
  print $fact;

  # Get data direct from the CIA World Factbook

  my $source = WebService::CIA::Source::Web->new();
  my $cia = WebService::CIA->new({ Source => $source });
  $fact = $cia->get("uk", "Population");
  print $fact;


=head1 DESCRIPTION

A module which gets information from the CIA World Factbook.


=head1 Crypt::SSLeay

The most recent version of the CIA World Factbook uses HTTPS to access its
web pages. As such, WebService::CIA requires Crypt::SSLeay which suffers from
the usual cryptographic export restriction mumbo jumbo. Sorry about that.

Users of ActiveState's ActivePerl should see L<http://aspn.activestate.com/ASPN/Downloads/ActivePerl/PPM/Repository>
for instructions on downloading a PPM of Crypt::SSLeay.


=head1 METHODS

=over 4

=item C<new(\%opts)>

Creates a new WebService::CIA object. Takes a hashref, which must contain a "Source"
key whose value is a WebService::CIA::Storage object.


=item C<get($country_code, $field)>

This method retrieves information from the store.

It takes two arguments: a country code (as defined in FIPS 10-4 on
L<https://www.cia.gov/library/publications/the-world-factbook/appendix/appendix-d.html>,
e.g. "uk", "us") and a field name (as defined in
L<https://www.cia.gov/library/publications/the-world-factbook/docs/notesanddefs.html>,
e.g. "Population", "Agriculture - products"). (WebService::CIA::Parser also
creates four extra fields: "URL", "URL - Print", "URL - Flag", and "URL -
Map" which are the URLs of the country's Factbook page, the printable
version of that page, a GIF map of the country, and a GIF flag of the
country respectively.)

The field name is very case and punctuation sensitive.

It returns the value of the field, or C<undef> if the field or country isn't
in the store.

Note that when using WebService::CIA::Store::Web, C<get> will also return C<undef> if
there is an error getting the page.


=item C<get_hashref(\@countries, \@fields)>

This method takes two arguments: an arrayref of country codes and an arrayref
of field names.

It returns a hashref of the form

  {
   'country1' => {
                  'field1' => 'value',
                  'field2' => 'value'
                 },
   'country2' => {
                  'field1' => 'value',
                  'field2' => 'value'
                 }
  }

=item C<get_all_hashref(\@countries)>

Get all the fields available for countries.

It takes one argument, an arrayref of country codes.

It returns a hashref similar to the one from C<get_hashref> above,
containing all the fields available for each country.

=item C<source()>

Get a reference to the WebService::CIA::Source object in use.

=back


=head1 CONFIGURATION VARIABLES

=over 4

=item C<$WebService::CIA::base_url>

Sets the base URL for the Factbook (currently 
"https://www.cia.gov/library/publications/the-world-factbook/"). If the
Factbook changes location, this can be changed to point to the new location
(assuming the relative structure of the Factbook is unchanged).

=back


=head1 AUTHOR

Ian Malpass (ian-cpan@indecorous.com)


=head1 COPYRIGHT

Copyright 2003-2007, Ian Malpass

This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.

The CIA World Factbook's copyright information page
(L<https://www.cia.gov/library/publications/the-world-factbook/docs/contributor_copyright.html>)
states:

  The Factbook is in the public domain. Accordingly, it may be copied
  freely without permission of the Central Intelligence Agency (CIA).


=head1 SEE ALSO

WebService::CIA::Parser, WebService::CIA::Source::DBM, WebService::CIA::Source::Web


=cut