1WWW::xkcd(3)          User Contributed Perl Documentation         WWW::xkcd(3)
2
3
4

NAME

6       WWW::xkcd - Synchronous and asynchronous interfaces to xkcd comics
7

VERSION

9       version 0.009
10

SYNOPSIS

12           use WWW::xkcd;
13           my $xkcd  = WWW::xkcd->new;
14           my ( $img, $comic ) = $xkcd->fetch; # provides latest comic
15           say "Today's comic is titled: ", $comic->{'title'};
16
17           # random comic
18           my ( $img, $comic ) = $xkcd->fetch_random;
19
20           # and now to write it to file
21           use IO::All;
22           use File::Basename;
23           $img > io( basename $comic->{'img'} );
24
25           # or in async mode
26           $xkcd->fetch( sub {
27               my ( $img, $comic ) = @_;
28               say "Today's comic is titled: ", $comic->{'title'};
29
30               ...
31           } );
32

DESCRIPTION

34       This module allows you to access xkcd comics (http://www.xkcd.com/)
35       using the official API in synchronous mode (what people are used to) or
36       in asynchronous mode.
37
38       The asynchronous mode requires you have AnyEvent and AnyEvent::HTTP
39       available. However, since it's just supported and not necessary, it is
40       not declared as a prerequisite.
41

METHODS

43   new
44       Create a new WWW::xkcd object.
45
46           # typical usage
47           my $xkcd = WWW::xkcd->new;
48
49           # it would be pointless to change these, but it's possible
50           my $xkcd = WWW::xkcd->new(
51               base_url => 'http://www.xkcd.com',
52               infopath => 'info.0.json',
53           );
54
55   fetch
56       Fetch both the metadata and image of a comic.
57
58           # fetching the latest
59           my ( $comic, $meta ) = $xkcd->fetch;
60
61           # fetching a specific one
62           my ( $comic, $meta ) = $xkcd->fetch(20);
63
64           # using callbacks for async mode
65           $xkcd->fetch( sub { my ( $comic, $meta ) = @_; ... } );
66
67           # using callbacks for a specific one
68           $xkcd->fetch( 20, sub { my ( $comic, $meta ) = @_; ... } );
69
70       This runs two requests: one to get the metadata using the API and the
71       second to get the image itself. If you don't need the image, it would
72       be better (and faster) for you to use the "fetch_metadata" method
73       below.
74
75   fetch_metadata
76       Fetch just the metadata of the comic.
77
78           my $meta = $xkcd->fetch_metadata;
79
80           # using callbacks for async mode
81           $xkcd->fetch_metadata( sub { my $meta = shift; ... } );
82
83   fetch_random
84       Works just like "fetch", but instead of retrieving the latest comic, or
85       the one specified, just gets a random comic. It can also receive a
86       callback for retrieving the comic.
87

NAMING

89       Why would you call it WWW::xkcd with all lower cases? Simply because
90       that's what Randall Munroe who writes xkcd prefers.
91
92       Taken verbatim from <http://www.xkcd.com/about>:
93
94           How do I write "xkcd"? There's nothing in Strunk and White about this.
95
96           For those of us pedantic enough to want a rule, here it is: The preferred
97           form is "xkcd", all lower-case. In formal contexts where a lowercase word
98           shouldn't start a sentence, "XKCD" is an okay alternative. "Xkcd" is
99           frowned upon.
100

DEPENDENCIES

102       •   Try::Tiny
103
104       •   HTTP::Tiny
105
106       •   JSON
107
108       •   Carp
109

OPTIONAL DEPENDENCIES

111       •   AnyEvent
112
113       •   AnyEvent::HTTP
114

AUTHOR

116       Sawyer X <xsawyerx@cpan.org>
117

119       This software is copyright (c) 2018 by Sawyer X.
120
121       This is free software; you can redistribute it and/or modify it under
122       the same terms as the Perl 5 programming language system itself.
123
124
125
126perl v5.36.0                      2023-01-20                      WWW::xkcd(3)
Impressum