https://github.com/xsawyerx/www-xkcd

Synchronous and asynchronous interfaces to xkcd comics
https://github.com/xsawyerx/www-xkcd

Last synced: 28 days ago
JSON representation

Synchronous and asynchronous interfaces to xkcd comics

• Host: GitHub
• URL: https://github.com/xsawyerx/www-xkcd
• Owner: xsawyerx
• Created: 2012-02-14T00:29:39.000Z (almost 13 years ago)
• Default Branch: master
• Last Pushed: 2018-07-21T12:15:20.000Z (over 6 years ago)
• Last Synced: 2024-10-13T11:37:30.827Z (about 1 month ago)
• Language: Perl
• Homepage:
• Size: 32.2 KB
• Stars: 7
• Watchers: 2
• Forks: 2
• Open Issues: 1
• Metadata Files:
  • Readme: README.pod
  • Changelog: Changes

Awesome Lists containing this project

README

        
=pod

=encoding UTF-8

=head1 NAME

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

=head1 VERSION

version 0.009

=head1 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'};

        ...

    } );

=head1 DESCRIPTION

This module allows you to access xkcd comics (http://www.xkcd.com/) using

the official API in synchronous mode (what people are used to) or in

asynchronous mode.

The asynchronous mode requires you have L and L

available. However, since it's just I and not I, it is not

declared as a prerequisite.

=head1 METHODS

=head2 new

Create a new L object.

    # 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',

    );

=head2 fetch

Fetch both the metadata and image of a comic.

    # 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 ) = @_; ... } );

This runs two requests: one to get the metadata using the API and the second

to get the image itself. If you don't need the image, it would be better (and

faster) for you to use the C method below.

=head2 fetch_metadata

Fetch just the metadata of the comic.

    my $meta = $xkcd->fetch_metadata;

    # using callbacks for async mode

    $xkcd->fetch_metadata( sub { my $meta = shift; ... } );

=head2 fetch_random

Works just like C, but instead of retrieving the latest comic, or the

one specified, just gets a random comic. It can also receive a callback for

retrieving the comic.

=head1 NAMING

Why would you call it WWW::I with all lower cases? Simply because that's

what Randall Munroe who writes xkcd prefers.

Taken verbatim from L:

    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.

=head1 DEPENDENCIES

=over 4

=item * Try::Tiny

=item * HTTP::Tiny

=item * JSON

=item * Carp

=back

=head1 OPTIONAL DEPENDENCIES

=over 4

=item * AnyEvent

=item * AnyEvent::HTTP

=back

=head1 AUTHOR

Sawyer X 

=head1 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.

=cut