POE::Component::WWW::XKCD::AsText - non-blocking wrapper around WWW::XKCD::AsText
use strict; use warnings; use POE qw(Component::WWW::XKCD::AsText); my $poco = POE::Component::WWW::XKCD::AsText->spawn; POE::Session->create( package_states => [ main => [qw(_start retrieved )] ], ); $poe_kernel->run; sub _start { $poco->retrieve( { id => 333, event => 'retrieved', } ); } sub retrieved { my $in = $_[ARG0]; if ( $in->{error} ) { print "Error: $in->{error}\n"; } else { printf "The comic on %s is:\n%s\n", @$in{ qw(uri text) }; } $poco->shutdown; }
Using event based interface is also possible of course.
The module is a non-blocking wrapper around WWW::XKCD::AsText which provides interface to retrieve comics on http://xkcd.com in text format (transcriptions)
my $poco = POE::Component::WWW::XKCD::AsText->spawn; POE::Component::WWW::XKCD::AsText->spawn( alias => 'xkcd', timeout => 10, # or: ua => LWP::UserAgent->new( timeout => 10, agent => 'blah), options => { debug => 1, trace => 1, # POE::Session arguments for the component }, debug => 1, # output some debug info );
The spawn method returns a POE::Component::WWW::XKCD::AsText object. It takes a few arguments, all of which are optional. The possible arguments are as follows:
spawn
POE::Component::WWW::XKCD::AsText->spawn( alias => 'xkcd' );
Optional. Specifies a POE Kernel alias for the component.
->spawn( timeout => 10 );
Optional. Specifies the timeout argument of LWP::UserAgent's constructor, which is used for retrieving. Defaults to: 30 seconds.
30
->spawn( ua => LWP::UserAgent->new( agent => 'Foos!' ) );
Optional. If the timeout argument is not enough for your needs of mutilating the LWP::UserAgent object used for retrieving, feel free to specify the ua argument which takes an LWP::UserAgent object as a value. Note: the timeout argument to the constructor will not do anything if you specify the ua argument as well. Defaults to: plain boring default LWP::UserAgent object with timeout argument set to whatever POE::Component::WWW::XKCD::AsText's timeout argument is set to as well as agent argument is set to mimic Firefox.
timeout
ua
agent
my $poco = POE::Component::WWW::XKCD::AsText->spawn( options => { trace => 1, default => 1, }, );
Optional. A hashref of POE Session options to pass to the component's session.
my $poco = POE::Component::WWW::XKCD::AsText->spawn( debug => 1 );
When set to a true value turns on output of debug messages. Defaults to: 0.
0
$poco->retrieve( { event => 'event_for_output', id => 333, _blah => 'pooh!', session => 'other', } );
Takes a hashref as an argument, does not return a sensible return value. See retrieve event's description for more information.
retrieve
my $poco_id = $poco->session_id;
Takes no arguments. Returns component's session ID.
$poco->shutdown;
Takes no arguments. Shuts down the component.
$poe_kernel->post( xkcd => retrieve => { event => 'event_for_output', id => 333, _blah => 'pooh!', session => 'other', } );
{ event => 'results_event', }
Mandatory. Specifies the name of the event to emit when results are ready. See OUTPUT section for more information.
{ id => 333 }
Mandatory. As a value takes an ID of the comic. In other words, if you want to read the comic on http://xkcd.com/333/ you would specify 333 as an id argument's value.
333
id
{ session => 'other' } { session => $other_session_reference } { session => $other_session_ID }
Optional. Takes either an alias, reference or an ID of an alternative session to send output to.
{ _user => 'random', _another => 'more', }
Optional. Any keys starting with _ (underscore) will not affect the component and will be passed back in the result intact.
_
$poe_kernel->post( xkcd => 'shutdown' );
Takes no arguments. Tells the component to shut itself down.
$VAR1 = { 'text' => 'comic\'s text here', 'uri' => bless( do{\(my $o = 'http://xkcd.com/333/')}, 'URI::http' ), };
The event handler set up to handle the event which you've specified in the event argument to retrieve() method/event will recieve input in the $_[ARG0] in a form of a hashref. The possible keys/value of that hashref are as follows:
event
retrieve()
$_[ARG0]
{ 'text' => 'comic\'s text here' }
The text key will contain the transcriptions of the comic.
text
{ 'error' => 'No text for comic' }
If there was some problem while retrieving text for the comic, or text for the comic does not exist yet (e.g. comic is very new and transcription has not been submitted yet) the error key will be present and will contain the description of the error.
error
{ 'uri' => bless( do{\(my $o = 'http://xkcd.com/333/')}, 'URI::http' ) }
The uri key will contain the URI object pointing to the page of the paste you've retrieved.
uri
{ '_blah' => 'foos' }
Any arguments beginning with _ (underscore) passed into the retrieve() event/method will be present intact in the result.
POE, LWP::UserAgent, WWW::XKCD::AsText
Zoffix Znet, <zoffix at cpan.org> (http://zoffix.com, http://haslayout.net)
<zoffix at cpan.org>
Please report any bugs or feature requests to bug-poe-component-www-xkcd-astext at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Component-WWW-XKCD-AsText. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-poe-component-www-xkcd-astext at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc POE::Component::WWW::XKCD::AsText
You can also look for information at:
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=POE-Component-WWW-XKCD-AsText
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/POE-Component-WWW-XKCD-AsText
CPAN Ratings
http://cpanratings.perl.org/d/POE-Component-WWW-XKCD-AsText
Search CPAN
http://search.cpan.org/dist/POE-Component-WWW-XKCD-AsText
Copyright 2008 Zoffix Znet, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install POE::Component::WWW::XKCD::AsText, copy and paste the appropriate command in to your terminal.
cpanm
cpanm POE::Component::WWW::XKCD::AsText
CPAN shell
perl -MCPAN -e shell install POE::Component::WWW::XKCD::AsText
For more information on module installation, please visit the detailed CPAN module installation guide.