WWW::xkcd(3)

🦋 WWW::xkcd — the manual page, but make it cute 🦋

okay so bestie, you're looking at the manual page for WWW::xkcd, which is a Perl module that gives you synchronous AND asynchronous interfaces to xkcd comics. Yes. Both. We contain multitudes. 💅

---

✨ NAME ✨

WWW::xkcd — Synchronous and asynchronous interfaces to xkcd comics 🎀

---

🌸 VERSION 🌸

version 0.009 ✨

---

💖 SYNOPSIS 💖

use WWW::xkcd;
my $xkcd  = WWW::xkcd->new;
my ( $img, $comic ) = $xkcd->fetch; # provides latest comic
say "Today's comic is titled: ", $comic->{'title'};

# random comic
my ( $img, $comic ) = $xkcd->fetch_random;

# and now to write it to file
use IO::All;
use File::Basename;
$img > io( basename $comic->{'img'} );

# or in async mode
$xkcd->fetch( sub {
    my ( $img, $comic ) = @_;
    say "Today's comic is titled: ", $comic->{'title'};

    ...
} );

like literally that's the whole vibe in one code block. grab a comic, grab a random comic, save it to a file, or do the whole thing async with a callback and go live your life. 🫶

---

🧚 DESCRIPTION 🧚

This module lets you access xkcd comics (http://www.xkcd.com/) using the official API — either in synchronous mode (which is, no shade, what everyone is used to) or in asynchronous mode. 👑

The asynchronous mode requires that you have AnyEvent and AnyEvent::HTTP available. But — and this is important — since it's just supported and not necessary, it is not declared as a prerequisite. So like, it's invited to the party but it's not on the guest list, iykyk. 💀

---

💅 METHODS 💅

⭐ new

Create a new WWW::xkcd object. main character energy fr fr. 🌟

# typical usage
my $xkcd = WWW::xkcd->new;

# it would be pointless to change these, but it's possible
my $xkcd = WWW::xkcd->new(
    base_url => 'http://www.xkcd.com',
    infopath => 'info.0.json',
);

ngl the original says changing those is pointless, but it's your life and your constructor args, so do what you want. 🎀

⭐ fetch

Fetch both the metadata and the image of a comic. the full meal. 🍓

# fetching the latest
my ( $comic, $meta ) = $xkcd->fetch;

# fetching a specific one
my ( $comic, $meta ) = $xkcd->fetch(20);

# using callbacks for async mode
$xkcd->fetch( sub { my ( $comic, $meta ) = @_; ... } );

# using callbacks for a specific one
$xkcd->fetch( 20, sub { my ( $comic, $meta ) = @_; ... } );

okay so real talk: this runs two requests — one to get the metadata using the API, and the second to get the image itself. So if you don't actually need the image, it would be better (and faster) for you to use the fetch_metadata method right below instead. consider this your friendly lil heads-up. 🙈

⭐ fetch_metadata

Fetch just the metadata of the comic. the snack, not the meal. 🧁

my $meta = $xkcd->fetch_metadata;

# using callbacks for async mode
$xkcd->fetch_metadata( sub { my $meta = shift; ... } );

⭐ fetch_random

Works just like fetch, except that instead of retrieving the latest comic, or the one you specified, it just gets a random comic. 🎲 It can also receive a callback for retrieving the comic. surprise me bestie ✨

---

🌈 NAMING 🌈

okay so why would anyone call it WWW::xkcd with all lowercase letters? 😭 Simply because that's what Randall Munroe, who writes xkcd, prefers. and honestly? we respect it. 👑

Taken verbatim from http://www.xkcd.com/about:

How do I write "xkcd"? There's nothing in Strunk and White about this.

For those of us pedantic enough to want a rule, here it is: The preferred
form is "xkcd", all lower-case. In formal contexts where a lowercase word
shouldn't start a sentence, "XKCD" is an okay alternative. "Xkcd" is
frowned upon.

frowned upon. 😭 not the "Xkcd" slander. we don't do that here. 💅

---

🎀 DEPENDENCIES 🎀

• Try::Tiny
• HTTP::Tiny
• JSON
• Carp

---

🦋 OPTIONAL DEPENDENCIES 🦋

• AnyEvent
• AnyEvent::HTTP

---

👑 AUTHOR 👑

Sawyer X <xsawyerx@cpan.org> 💜

---

💖 COPYRIGHT AND LICENSE 💖

This software is copyright (c) 2018 by Sawyer X.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. 🌈

---

and that's the whole page bestie — this was perl v5.42.0, dated 2025-07-25, and you just read WWW::xkcd(3). slay, ate, no crumbs. 💅✨🦋