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.