Sawyer X > WWW-xkcd-0.005 > WWW::xkcd

Download:
WWW-xkcd-0.005.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.005   Source  

NAME ^

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

VERSION ^

version 0.005

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

    # 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'};

        ...
    } );

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 AnyEvent and AnyEvent::HTTP available. However, since it's just supported and not necessary, it is not declared as a prerequisite.

METHODS ^

new

Create a new WWW::xkcd 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',
    );

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 fetch_metadata method below.

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; ... } );

NAMING ^

Why would you call it WWW::xkcd with all lower cases? Simply because that's what Randall Munroe who writes xkcd prefers.

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.

DEPENDENCIES ^

OPTIONAL DEPENDENCIES ^

AUTHOR ^

Sawyer X <xsawyerx@cpan.org>

COPYRIGHT AND LICENSE ^

This software is copyright (c) 2012 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.

syntax highlighting: