The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
WWW-OhNoRobotCom-Search-0.003
River stage one • 1 direct dependent • 3 total dependents
++
/ WWW::OhNoRobotCom::Search

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

    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

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:

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.