WebService::CIA(3pm)

💖 WebService::CIA 💖

okay bestie, welcome to the WebService::CIA(3pm) page — yes it's a Perl module, yes it's from the User Contributed Perl Documentation corner of the world, and yes it's about to serve you facts about literally every country on earth. no cap. 🌍✨

---

✨ NAME ✨

WebService::CIA — gets you info from the CIA World Factbook. that's the whole job. it does it and it does it well. 💅

---

🦋 SYNOPSIS 🦋

like, here's the vibe. two ways to do the thing:

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;

see? either you pull from a pre-compiled DBM file (fast, chill, offline girl) or you go straight to the Factbook itself (main character energy, needs the internet). both valid. both iconic. 🫶

---

🌸 DESCRIPTION 🌸

it's a module. it gets information from the CIA World Factbook. that's it, that's the description, and honestly? slay. 🎀

---

🔐 Crypt::SSLeay 🔐

okay so important tea: the most recent version of the CIA World Factbook uses HTTPS to access its web pages. so because of that, WebService::CIA requires Crypt::SSLeay, which — and I cannot stress this enough — suffers from the usual cryptographic export restriction mumbo jumbo. 😭 sorry about that. it's not us, it's the laws.

ActivePerl besties: if you're on ActiveState's ActivePerl, go look at <https://aspn.activestate.com/ASPN/Downloads/ActivePerl/PPM/Repository> for instructions on downloading a PPM of Crypt::SSLeay. it's giving "here's your map, go get it" 🗺️

---

💅 METHODS 💅

🧚 new(\%opts)

creates a brand new WebService::CIA object. it takes a hashref, and that hashref must contain a Source key whose value is a WebService::CIA::Storage object. no Source, no vibes. periodt.

⭐ get($country_code, $field)

this one retrieves information from the store. the workhorse. the moment. 🔥

it takes two arguments:

1. a country code — as defined in FIPS 10-4 on <https://www.cia.gov/library/publications/the-world-factbook/appendix/appendix-d.html>, e.g. "uk", "us".
2. a field name — as defined in <https://www.cia.gov/library/publications/the-world-factbook/docs/notesanddefs.html>, e.g. "Population", "Agriculture - products".

(also! WebService::CIA::Parser creates four extra fields for you: "URL", "URL - Print", "URL - Flag", and "URL - Map" — which are, respectively, 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. bonus content, we love to see it. 🗺️🇺🇳)

heads up: the field name is very case and punctuation sensitive. like, do not freestyle it. it will not forgive you.

it returns the value of the field, or undef if the field or the country isn't in the store. 😶

and ngl, one more thing: when you're using WebService::CIA::Store::Web, get will also return undef if there's an error getting the page. so undef can mean two things. keep that in mind. 💀

🌈 get_hashref(\@countries, \@fields)

this one takes two arguments: an arrayref of country codes, and an arrayref of field names.

it returns a hashref that looks like this:

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

bulk facts. organized facts. aesthetic facts. 💖

👑 get_all_hashref(\@countries)

get all the fields available for countries. go big or go home.

it takes one argument: an arrayref of country codes.

it returns a hashref similar to the one from get_hashref above, except it's got all the fields available for each country. everything. the whole dossier. 🗂️✨

🎀 source()

gets you a reference to the WebService::CIA::Source object that's currently in use. just so you know who's doing the work. 🫶

---

🧚 CONFIGURATION VARIABLES 🧚

💜 $WebService::CIA::base_url

sets the base URL for the Factbook — currently "https://www.cia.gov/library/publications/the-world-factbook/". so if the Factbook ever moves house (rude of it, honestly), you can point this at the new location. that works assuming the relative structure of the Factbook is unchanged. if they reorganize everything too? then it's giving "we'll cross that bridge" 🌉😭

---

🌸 AUTHOR 🌸

Ian Malpass (<ian-cpan@indecorous.com>) — the icon who built this. 👑

---

⭐ 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. 💖

and the CIA World Factbook's copyright information page (<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).

public domain!! copy it freely!! no permission slip needed from the CIA!! we love a permissive queen 💅✨

---

🦋 SEE ALSO 🦋

• WebService::CIA::Parser
• WebService::CIA::Source::DBM
• WebService::CIA::Source::Web

---

and that's the whole page, bestie!! this was perl v5.34.0, dated 2022-06-28, brought to you by WebService::CIA(3pm) — stay curious, go look up a country, and remember: case and punctuation sensitive. always. 😭💖