NAME
WWW::OhNoRobotCom::Search - search comic transcriptions on
http://ohnorobot.com
SYNOPSIS
use strict;
use warnings;
use WWW::OhNoRobotCom::Search;
my $site = WWW::OhNoRobotCom::Search->new;
# search XKCD comics
my $results_ref = $site->search( 'foo', comic_id => 56 )
or die $site->error;
print "Results:\n",
map { "$results_ref->{$_} ( $_ )\n" } keys %$results_ref;
DESCRIPTION
The module provides interface to perform searches on
<http://www.ohnorobot.com> comic transcriptions website.
CONSTRUCTOR
new
my $site = WWW::OhNoRobotCom::Search->new;
my $site = WWW::OhNoRobotCom::Search->new(
timeout => 10,
);
my $site = WWW::OhNoRobotCom::Search->new(
ua => LWP::UserAgent->new(
timeout => 10,
agent => 'robotos',
),
);
Constructs and returns a brand new yummy juicy WWW::OhNoRobotCom::Search
object. Takes two arguments, both are *optional*. Possible arguments are
as follows:
timeout
->new( timeout => 10 );
Optional. Specifies the "timeout" argument of LWP::UserAgent's
constructor, which is used for searching. Defaults to: 30 seconds.
ua
->new( 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 searching, 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 "WWW::OhNoRobotCom::Search"'s "timeout" argument is set to as
well as "agent" argument is set to mimic Firefox.
METHODS
search
my $results_ref = $site->search('foo')
or die $site->error;
my $xkcd_results_ref = $site->search(
'foo',
comic_id => 56,
include => [ qw(all_text meta) ],
max_results => 20,
) or die $site->error;
my $uri = $site->search( 'foo', lucky => 1 )
or die "No lucky :(" . $site->error;
Instructs the object to perform a search. If an error occured returns
either "undef" or an empty list depending on the context and the
description of the error will be available via "error()" method. On
success, returns a (possibly empty) hashref where keys are URI's poiting
to comics and values are titles presented in search results unless the
"lucky" (see below) argument is set, in which case it will return a URI
object pointing to the *Let the robot decide* URI or will "error out"
with the "Nothing was found" in the "error()" message. Takes one
mandatory argument and several optional arguments.
Note: the "search()" can make several requests, (see "max_results"'s
argument) but it will tell you about only the *first* network error, any
network errors occuring later during the search will not be reported,
will be silently skipped and the internal "results found" counter will
be increased by 10 to prevent any infinite loops.
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
$site->search( 'term', comic_id => 56 );
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 accepts
names instead of those numbers, but there are just too many (500+)
different comics sites and new are being added, blah blah (me is lazy
too :) ). Defaults to: empty string, meaning search through all the
comics.
include
$site->search( 'term', include => [ qw(all_text meta) ] );
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
$site->search( 'term', max_results => 30 );
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
$site->search( 'term', 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 will return a URI
object poiting to the comic which the *ahem* "robot" thinks is what you
want. Note: when using the "lucky" argument the "search()" method will
return either "undef" or an empty list (depending on the context) if
nothing was found. Defaults to: a false value (no feelin' lucky :( )
error
$site->search('term')
or die $site->error;
If "search()" method failed, be it due to a network error or nothing
found for "lucky" search it will return either "undef" or an empty list
depending on the context and the error will be available via "error()"
method. Takes no arguments, returns a human parsable message describing
why "search()" failed.
results
my $results = $site->results;
Must be called after a successfull call to "search()". Takes no
arguments, returns the exact same thing last "search()" returned. See
"search()" method's description for more information.
ua
my $old_ua = $site->ua;
$site->ua( LWP::UserAgent->new( timeout => 10, agent => 'agent007' );
Returns an LWP::UserAgent object used for searching. When called with an
optional argument which should be an LWP::UserAgent object the
WWW::OhNoRobotCom::Search will use the argument in any subsequent
"search()"es.
AUTHOR
Zoffix Znet, "<zoffix at cpan.org>" (<http://zoffix.com>,
<http://haslayout.net>)
BUGS
Please report any bugs or feature requests to
"bug-www-ohnorobotcom-search at rt.cpan.org", or through the web
interface at
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=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 WWW::OhNoRobotCom::Search
You can also look for information at:
* RT: CPAN's request tracker
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=WWW-OhNoRobotCom-Search>
* AnnoCPAN: Annotated CPAN documentation
<http://annocpan.org/dist/WWW-OhNoRobotCom-Search>
* CPAN Ratings
<http://cpanratings.perl.org/d/WWW-OhNoRobotCom-Search>
* Search CPAN
<http://search.cpan.org/dist/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.