Why not adopt me?
NAME
POE::Component::WWW::OhNoRobotCom::Search - non-blocking POE based wrapper around WWW::OhNoRobotCom::Search module
SYNOPSIS
use strict;
use warnings;
use POE qw(Component::WWW::OhNoRobotCom::Search);
my $poco = POE::Component::WWW::OhNoRobotCom::Search->spawn;
POE::Session->create(
package_states => [ main => [qw(_start results )] ],
);
$poe_kernel->run;
sub _start {
$poco->search( {
term => 'foo',
comic_id => 56, # XKCD comics
event => 'results',
}
);
}
sub results {
my $in_ref = $_[ARG0];
exists $in_ref->{error}
and die "ZOMG! ERROR!: $in_ref->{error}";
print "Results for XKCD comic search are as follows:\n";
keys %{ $in_ref->{results} };
while ( my ( $uri, $title ) = each %{ $in_ref->{results} } ) {
print "$title [ $uri ]\n";
}
$poco->shutdown;
}
Using event based interface is also possible of course.
DESCRIPTION
The module is a non-blocking wrapper around WWW::OhNoRobotCom::Search which provides interface to http://www.ohnorobot.com/ search
CONSTRUCTOR
spawn
my $poco = POE::Component::WWW::OhNoRobotCom::Search->spawn;
POE::Component::WWW::OhNoRobotCom::Search->spawn(
alias => 'robo',
obj_args => {
timeout => 10,
},
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::OhNoRobotCom::Search object. It takes a few arguments, all of which are optional. The possible arguments are as follows:
alias
POE::Component::WWW::OhNoRobotCom::Search->spawn(
alias => 'robo'
);
Optional. Specifies a POE Kernel alias for the component.
obj_args
POE::Component::WWW::OhNoRobotCom::Search->spawn(
obj_args => {
timeout => 10,
}
);
Optional. The obj_args
argument takes a hashref as a value which will be dereferenced directly into WWW::OhNoRobotCom::Search constructor. See documentation for WWW::OhNoRobotCom::Search for more details. Defaults to: empty (default WWW::OhNoRobotCom::Search constructor)
options
my $poco = POE::Component::WWW::OhNoRobotCom::Search->spawn(
options => {
trace => 1,
default => 1,
},
);
Optional. A hashref of POE Session options to pass to the component's session.
debug
my $poco = POE::Component::WWW::OhNoRobotCom::Search->spawn(
debug => 1
);
When set to a true value turns on output of debug messages. Defaults to: 0
.
METHODS
search
$poco->search( {
event => 'event_for_output',
term => 'foo',
comic_id => 56,
include => [ qw(all_text meta) ],
max_results => 20,
lucky => 1,
_blah => 'pooh!',
session => 'other',
}
);
Takes a hashref as an argument, does not return a sensible return value. See search
event's description for more information.
session_id
my $poco_id = $poco->session_id;
Takes no arguments. Returns component's session ID.
shutdown
$poco->shutdown;
Takes no arguments. Shuts down the component.
ACCEPTED EVENTS
search
$poe_kernel->post( robo => search => {
event => 'event_for_output',
term => 'foo',
comic_id => 56,
include => [ qw(all_text meta) ],
max_results => 20,
lucky => 1,
_blah => 'pooh!',
session => 'other',
}
);
Instructs the component to perform the search. Takes a hashref as an argument, the possible keys/value of that hashref are as follows:
event
{ event => 'results_event', }
Mandatory. Specifies the name of the event to emit when results are ready. See OUTPUT section for more information.
term
{ term => 'foo' }
Mandatory. Specifies the term to search for.
The first argument (mandatory) is the term you want to search. The other, optional, arguments are given in a key/value fashion and are as follows:
comic_id
{ comic_id => 56 }
Optional. The comic_id
argument takes a scalar as a value which should be a comic ID number or an empty string which indicates that search should be done on all comics. To obtain the comic ID number go to http://www.ohnorobot.com/index.pl?show=advanced, "View Source" and search for the name of the comic, when you'll find an <option> the value=""
attribute of that option will be the number you are looking for. Idealy, it would make sense to make the search()
method/event accepts names instead of those numbers, but there are just too many (500+) different comics sites and new are being added, blah blah. Defaults to: empty string, meaning search through all the comics.
include
{ include => [ qw(all_text meta) ] }
Optional. Specifies what kind of "things" to include into consideration when performing the search. Takes an arrayref as an argument. Defaults to: all possible elements included which are as follows:
- all_text
-
Include All comic text.
- scene
-
Include Scene descriptions.
- sound
-
Include Sound effects.
- speakers
-
Include Speakers' names
- link
-
Include Link text.
- meta
-
Include Meta information
max_results
{ max_results => 30 }
Optional. The number of results displayed on http://www.ohnorobot.com is 10, the object will send out several requests if needed to obtain the number of results specified in the max_results
argument. Don't use extremely large values here, as the amount of requests will NOT be max_results / 10
because results are often repeating and the object will count only unique URIs on the results page. Defaults to: 10
(this does not necessarily mean that the object will send only one request).
lucky
{ lucky => 1 }
ARE YOU FEELING LUCKY?!!? If so, the lucky
argument, when set to a true value, will "press" the Let the robot decide button on http://www.ohnorobot.com and the search
method/event will fetch a poiting to the comic which the *ahem* "robot" thinks is what you want. Note: when using the lucky
argument the search()
method will error out (see "OUTPUT" section below) if nothing was found. Defaults to: a false value (no feelin' lucky :( )
session
{ 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 defined
{
_user => 'random',
_another => 'more',
}
Optional. Any keys starting with _
(underscore) will not affect the component and will be passed back in the result intact.
shutdown
$poe_kernel->post( robo => 'shutdown' );
Takes no arguments. Tells the component to shut itself down.
OUTPUT
$VAR1 = {
'comic_id' => 56,
'term' => 'foo',
'results' => {
'http://xkcd.com/240/' => 'Dream Girl',
'http://xkcd.com/351/' => 'Trolling',
'http://xkcd.com/261/' => 'Regarding Mussolini',
'http://xkcd.com/319/' => 'Engineering Hubris',
'http://xkcd.com/389/' => 'Keeping Time',
'http://xkcd.com/356/' => 'Nerd Sniping',
'http://xkcd.com/233/' => 'A New CAPTCHA Approach'
},
_foo => 'blah'
};
The event handler set up to handle the event which you've specified in the event
argument to search()
method/event will recieve input in the $_[ARG0]
in a form of a hashref. The possible keys/value of that hashref are as follows:
results
'results' => {
'http://xkcd.com/240/' => 'Dream Girl',
'http://xkcd.com/351/' => 'Trolling',
'http://xkcd.com/261/' => 'Regarding Mussolini',
'http://xkcd.com/319/' => 'Engineering Hubris',
'http://xkcd.com/389/' => 'Keeping Time',
'http://xkcd.com/356/' => 'Nerd Sniping',
'http://xkcd.com/233/' => 'A New CAPTCHA Approach'
},
The results
key will contain a (possibly empty) hashref with keys being links to the comics found in the search and values being their titles.
error
{ error => 'Some error' }
If an error occured during the search (or nothing was found for "lucky" search) results
key will not be present and instead error
key will be present containing an error message explaining the reason for failure.
arguments passed to search
{
'comic_id' => 56,
'term' => 'foo',
}
Valid arguments (comic_id
, term
, etc) will also be present in the response hashref.
user defined
{ '_blah' => 'foos' }
Any arguments beginning with _
(underscore) passed into the search()
event/method will be present intact in the result.
SEE ALSO
POE, WWW::OhNoRobotCom::Search
AUTHOR
Zoffix Znet, <zoffix at cpan.org>
(http://zoffix.com, http://haslayout.net)
BUGS
Please report any bugs or feature requests to bug-poe-component-www-ohnorobotcom-search at rt.cpan.org
, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Component-WWW-OhNoRobotCom-Search. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc POE::Component::WWW::OhNoRobotCom::Search
You can also look for information at:
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=POE-Component-WWW-OhNoRobotCom-Search
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/POE-Component-WWW-OhNoRobotCom-Search
CPAN Ratings
http://cpanratings.perl.org/d/POE-Component-WWW-OhNoRobotCom-Search
Search CPAN
http://search.cpan.org/dist/POE-Component-WWW-OhNoRobotCom-Search
COPYRIGHT & LICENSE
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.