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-OhNoRo
    botCom-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-OhNoRobo
        tCom-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.