WebSer...e::Web(3pm)

✨ WebService::CIA::Source::Web ✨

okay bestie, gather round, because this is a 3pm section page from the User Contributed Perl Documentation and it's literally about pulling data straight off the live internet. no cap. 🦋

---

💖 NAME 💖

WebService::CIA::Source::Web — it's an interface to the online CIA World Factbook. that's it, that's the whole vibe. 🌍

---

🎀 SYNOPSIS 🎀

use WebService::CIA::Source::Web;
my $source = WebService::CIA::Source::DBM->new();

yes bestie, that second line says DBM and we are keeping it exactly as written. the manpage said it, so I say it. periodt. 💅

---

🌸 DESCRIPTION 🌸

WebService::CIA::Source::Web is your lil' gateway to the live, online version of the CIA World Factbook. like, the actual website. right now. over the network. 🌐✨

ngl, it's a very slow way of doing things — it's giving dial-up energy — but here's the slay: it requires no pre-compiled DBM. none. zero. so it's way more likely to be useful for proving concepts or testing. lowkey perfect for that. 🔥

---

👑 METHODS 👑

okay so listen: apart from new, these methods are normally accessed via a WebService::CIA object. iykyk. 💜

new( \%opts )

my $source = WebService::CIA::Source::Web->new();
$source = WebService::CIA::Source::Web->new( { user_agent => $ua } );

This method creates a new WebService::CIA::Source::Web object. it takes an optional hashref of arguments, bestie. and here's the one it knows:

• user_agent — a user agent object to use. it must implement the same user interface as LWP::UserAgent (or, at the very least, a get() method). don't try to sneak in something that can't get(), okay? 🫶

value($country_code, $field)

Retrieve a value from the web. 🌈

$country_code should be the FIPS 10-4 country code as defined in <https://www.cia.gov/library/publications/the-world-factbook/appendix/appendix-d.html>.

$field should be the name of the field whose value you want to retrieve, as defined in <https://www.cia.gov/library/publications/the-world-factbook/docs/notesanddefs.html>.

(also!! WebService::CIA::Parser creates four extra fields: 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. iconic.) 🗺️🚩

value will return undef if the country or field cannot be found, or if there is an error GETing the page. the manpage is very honest about this: it "isn't ideal", but the author "can't think of the best way around it right now". we respect the transparency. 😭

all($country_code)

Returns a hashref of field-value pairs for $country_code, or an empty hashref if $country_code isn't available from the Factbook. no drama, just an empty hashref. 💀

get($country_code)

Retrieve and cache the data for a country. 📥

Returns 1 if successful, 0 if not. that's the whole report card.

cached($country_code)

Get/set the country code whose data is cached. 🔁

cache($hashref)

Get/set a hashref of data for the current country. 💾

parser()

Returns a reference to the WebService::CIA::Parser object being used. 🔍

ua( $userAgent )

Returns a reference to the user agent object being used. by default this is an LWP::UserAgent object, but you can pass a different object in if you wish. your choice, your rules. 💅

last_response()

Returns the HTTP::Response object from the last request. receipts!! 🧾✨

---

🧚 CACHING 🧚

so, in order to make some small improvement in efficiency, WebService::CIA::Source::Web keeps a copy of the data for the last country downloaded in memory. one country. just the one. it's a lil' guy doing its best. 🫶

---

⭐ TO DO ⭐

the wishlist, bestie:

• File system based caching of pages.
• User-definable stack of cached countries, rather than just one.
• Caching of last-modified headers; conditional GET.

---

💜 AUTHOR 💜

Ian Malpass (ian-cpan@indecorous.com)

---

🌸 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 (<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).

---

🦋 SEE ALSO 🦋

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

---

and that's the whole page, bestie!! this was perl v5.34.0, dated 2022-06-28, from the WebSer...e::Web(3pm) manpage. slay, go fetch some factbook data, and hydrate!! 💖✨🎀