/ 
POE-Component-WWW-CPAN-0.0101
/ POE::Component::WWW::CPAN

NAME

POE::Component::WWW::CPAN - non-blocking wrapper around WWW::CPAN

SYNOPSIS

use strict;
use warnings;

use POE qw/Component::WWW::CPAN/;

my $poco = POE::Component::WWW::CPAN->spawn;

POE::Session->create(
    package_states => [
        main => [ qw/_start results/ ],
    ],
);

$poe_kernel->run;

sub _start {
    $poco->search({
            event => 'results',
            query => 'App::ZofCMS::Plugin',
            n => 100
        }
    );
}

sub results {
    use Data::Dumper;
    print Dumper $_[ARG0]->{result};
    $poco->shutdown;
}

Using event based interface is also possible of course.

DESCRIPTION

The module is a non-blocking wrapper around WWW::CPAN which provides interface to http://search.cpan.org/ searching capabilities.

CONSTRUCTOR

spawn

my $poco = POE::Component::WWW::CPAN->spawn;

POE::Component::WWW::CPAN->spawn(
    alias => 'cpan',
    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::CPAN object. It takes a few arguments, all of which are optional. The possible arguments are as follows:

alias

->spawn( alias => 'cpan' );

Optional. Specifies a POE Kernel alias for the component.

options

->spawn(
    options => {
        trace => 1,
        default => 1,
    },
);

Optional. A hashref of POE Session options to pass to the component's session.

debug

->spawn(
    debug => 1
);

When set to a true value turns on output of debug messages. Defaults to: 0.

METHODS

$poco->search( {
        event       => 'event_for_output',
        query       => 'WWW::CPAN',
        _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( cpan => search => {
        event       => 'event_for_output',
        query       => 'WWW::CPAN',
        _blah       => 'pooh!',
        session     => 'other',
    }
);

Instructs the component to make a search on Lhttp://search.cpan.org/>. 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.

method

{ method => 'fetch_distmeta' }

{ method => 'search' }

Optional. Specifies which method to call on WWW::CPAN object. Possible values are fetch_distmeta, search and query where query is just an alias to search. Defaults to: search.

query

{ query => 'WWW::CPAN' }

Mandatory unless method argument (see above) is set to fetch_distmeta in which case argument query is not used. Specifies the term for which you are searching.

mode

{ query => 'WWW::CPAN', mode => 'all' }

{ query => 'WWW::CPAN', mode => 'module' }

{ query => 'WWW::CPAN', mode => 'dist' }

{ query => 'WWW::CPAN', mode => 'author' }

Optional. Valid when method argument it set to either query or search (the default). Takes a scalar as an argument which can be either one of all, dist, module or author. Specifies what should your query search - same as on http://search.cpan.org/. Defaults to: all

n

{ query => 'WWW::CPAN', n => 50 }

Optional. Takes an integer between 1 and 100. Specifies how many results you wish to have per "page" (see s option below). Values larger than 100 will get reset to 100. Defaults to: 10

s

{ query => 'WWW::CPAN', s => 10 }

Optional. Takes a positive integer as a value. Specifies the page number you wish to access - same as on http://search.cpan.org. In other words, if your n (see above) is set to 10, and your s argument is set to 2, you will get results 10 to 20. Defaults to: 1

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( cpan => 'shutdown' );

Takes no arguments. Tells the component to shut itself down.

OUTPUT

$VAR1 = {
    'result' => {
        'matches' => '12',
        'start' => '1',
        'module' => [
            {
                'link' => 'http://search.cpan.org/author/ZOFFIX/App-ZofCMS-0.0103/lib/App/ZofCMS.pm',
                'version' => '0.0103',
                'name' => 'App::ZofCMS',
                'released' => '27th July 2008',
                'author' => {
                    'link' => 'http://search.cpan.org/~zoffix/'
                 },
                 'description' => 'web framework and templating system for small-medium sites. '
            },
            {
                'link' => 'http://search.cpan.org/author/ZOFFIX/App-ZofCMS-Plugin-Tagged-0.0201/lib/App/ZofCMS/Plugin/Tagged.pm',
                'name' => 'App::ZofCMS::Plugin::Tagged',
                'released' => '28th July 2008',
                'author' => {
                    'link' => 'http://search.cpan.org/~zoffix/'
                },
                'description' => 'ZofCMS plugin to fill templates with data from query, template variables and configuration using <TAGS> '
            }
        ]
    },
    '_blah' => 'foo',
};

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:

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::CPAN

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-cpan at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Component-WWW-CPAN. 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::CPAN

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.