POE::Component::CPAN::LinksToDocs::No404s - non-blocking wrapper around CPAN::LinksToDocs::No404s

POE-Component-CPAN-LinksToDocs-No404s documentation Contained in the POE-Component-CPAN-LinksToDocs-No404s distribution.

Index

Code Index:

NAME

Top

POE::Component::CPAN::LinksToDocs::No404s - non-blocking wrapper around CPAN::LinksToDocs::No404s

SYNOPSIS

Top

SYNOPSIS

Top

    use strict;
    use warnings;

    use POE qw(Component::CPAN::LinksToDocs::No404s);

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

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

    $poe_kernel->run;

    sub _start {
        $poco->link_for( {
                tags => 'map,RE,Carp,Acme::Something,OtherModule',
                event => 'response',
            }
        );
    }

    sub response {
        print "$_\n" for @{ $_[ARG0]->{results} };

        $poco->shutdown;
    }

Using event based interface is also possible of course.

DESCRIPTION

The module is a non-blocking wrapper around CPAN::LinksToDocs::No404s which provides means to get documentation to http://search.cpan.org documentation by giving predefined "tags" or module names. To find out more about "tags" see TAGS section in CPAN::LinksToDocs::No404s module's documentation.

CONSTRUCTOR

Top

spawn

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

    POE::Component::CPAN::LinksToDocs::No404s->spawn(
        alias => 'docs',
        obj_args => {
            tags => {
                foos => 'http://bars.com/',
            },
            timeout => 20,
        },
        options => {
            debug => 1,
            trace => 1,
            # POE::Session arguments for the component
        },
        debug => 1, # output some debug info
    );

The spawn method returns a POE::Component::CPAN::LinksToDocs::No404s object. It takes a few arguments, all of which are optional. The possible arguments are as follows:

alias

    POE::Component::CPAN::LinksToDocs::No404s->spawn(
        alias => 'docs'
    );

Optional. Specifies a POE Kernel alias for the component.

obj_args

    my $poco = POE::ComponentCPAN::LinksToDocs::No404s->spawn(
        obj_args => {
            tags => {
                foos => 'http://bars.com/',
            },
            timeout => 20,
        }
    );

Optional. The obj_args argument takes a hashref as a value. The hashref must contain CPAN::LinksToDocs::No404s object's constructor arguments. See CPAN::LinksToDocs::No404s's constructor (new() method) documentation for more information.

options

    my $poco = POE::Component::CPAN::LinksToDocs::No404s->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::CPAN::LinksToDocs::No404s->spawn(
        debug => 1
    );

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

METHODS

Top

    $poco->link_for( {
            event => 'event_for_output',
            tags  => 'map,grep,Acme::Something,RE,OOP,SomeModule',
            _blah => 'pooh!',
            session => 'other',
        }
    );

Takes a hashref as an argument, does not return a sensible return value. See link_for 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

Top

    $poe_kernel->post( docs => link_for => {
            event => 'event_for_output',
            tags  => 'map,grep,Acme::Something,OOP,SomeModule',
            _blah => 'pooh!',
            session => 'other',
        }
    );

Instructs the component to make out the links (and check the ones that need checking) for "tags" given in the tags argument. 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.

tags

    { tags => 'map,grep,OOP,Acme::Something,SomeModule' }

Mandatory. Takes a scalar containing comma separated one or more "tags". See TAGS section in CPAN::LinksToDocs::No404s module's documentation for more information about possible "tags".

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

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

OUTPUT

Top

    $VAR1 = {
        'response' => [
            'http://perldoc.perl.org/functions/map.html',
            'http://perldoc.perl.org/functions/grep.html',
            'http://search.cpan.org/perldoc?Acme::BabyEater',
            'Not found'
        ],
        'tags' => 'map,grep,Acme::BabyEater,Zoffer',
        '_user' => 'foos',
    };

The event handler set up to handle the event which you've specified in the event argument to link_for() method/event will recieve input in the $_[ARG0] in a form of a hashref. The possible keys/value of that hashref are as follows:

response

    {
        'response' => [
            'http://perldoc.perl.org/functions/map.html',
            'http://perldoc.perl.org/functions/grep.html',
            'http://search.cpan.org/perldoc?Acme::BabyEater',
            'Not found'
        ],
    }

The response key will contain a (possibly empty) arrayref of links to documentation. This is the same arrayref that you would get from CPAN::LinksToDocs::No404s's link_for() method. See documentation for CPAN::LinksToDocs::No404s module for more information.

tags

    { 'tags' => 'map,grep,Acme::BabyEater,Zoffer', }

The tags key will contain whatever you've passed in tags argument to link_for() method/event.

user defined

    { '_blah' => 'foos' }

Any arguments beginning with _ (underscore) passed into the EXAMPLE() event/method will be present intact in the result.

SEE ALSO

Top

POE, CPAN::LinksToDocs::No404s

AUTHOR

Top

Zoffix Znet, <zoffix at cpan.org> (http://zoffix.com, http://haslayout.net)

BUGS

Top

Please report any bugs or feature requests to bug-poe-component-cpan-linkstodocs-no404s at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Component-CPAN-LinksToDocs-No404s. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

Top

You can find documentation for this module with the perldoc command.

    perldoc POE::Component::CPAN::LinksToDocs::No404s

You can also look for information at:

* RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=POE-Component-CPAN-LinksToDocs-No404s

* AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/POE-Component-CPAN-LinksToDocs-No404s

* CPAN Ratings

http://cpanratings.perl.org/d/POE-Component-CPAN-LinksToDocs-No404s

* Search CPAN

http://search.cpan.org/dist/POE-Component-CPAN-LinksToDocs-No404s

COPYRIGHT & LICENSE

Top

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.

POE-Component-CPAN-LinksToDocs-No404s documentation Contained in the POE-Component-CPAN-LinksToDocs-No404s distribution. 
package POE::Component::CPAN::LinksToDocs::No404s;

use warnings;
use strict;

our $VERSION = '0.001';


use Carp;
use CPAN::LinksToDocs::No404s;
use POE qw( Filter::Reference  Filter::Line  Wheel::Run );

sub spawn {
    my $package = shift;
    croak "$package requires an even number of arguments"
        if @_ & 1;

    my %params = @_;
    
    $params{ lc $_ } = delete $params{ $_ } for keys %params;

    delete $params{options}
        unless ref $params{options} eq 'HASH';

    my $self = bless \%params, $package;

    $self->{session_id} = POE::Session->create(
        object_states => [
            $self => {
                link_for => '_link_for',
                shutdown => '_shutdown',
            },
            $self => [
                qw(
                    _child_error
                    _child_closed
                    _child_stdout
                    _child_stderr
                    _sig_child
                    _start
                )
            ]
        ],
        ( defined $params{options} ? ( options => $params{options} ) : () ),
    )->ID();

    return $self;
}


sub _start {
    my ( $kernel, $self ) = @_[ KERNEL, OBJECT ];
    $self->{session_id} = $_[SESSION]->ID();

    if ( $self->{alias} ) {
        $kernel->alias_set( $self->{alias} );
    }
    else {
        $kernel->refcount_increment( $self->{session_id} => __PACKAGE__ );
    }

    $self->{wheel} = POE::Wheel::Run->new(
        Program    => sub{ _wheel( $self->{obj_args} ); },
        ErrorEvent => '_child_error',
        CloseEvent => '_child_close',
        StdoutEvent => '_child_stdout',
        StderrEvent => '_child_stderr',
        StdioFilter => POE::Filter::Reference->new,
        StderrFilter => POE::Filter::Line->new,
        ( $^O eq 'MSWin32' ? ( CloseOnCall => 0 ) : ( CloseOnCall => 1 ) )
    );

    $kernel->yield('shutdown')
        unless $self->{wheel};

    $kernel->sig_child( $self->{wheel}->PID(), '_sig_child' );

    undef;
}

sub _sig_child {
    $poe_kernel->sig_handled;
}

sub session_id {
    return $_[0]->{session_id};
}

sub link_for {
    my $self = shift;
    $poe_kernel->post( $self->{session_id} => 'link_for' => @_ );
}

sub _link_for {
    my ( $kernel, $self ) = @_[ KERNEL, OBJECT ];
    my $sender = $_[SENDER]->ID;
    
    return
        if $self->{shutdown};
        
    my $args;
    if ( ref $_[ARG0] eq 'HASH' ) {
        $args = { %{ $_[ARG0] } };
    }
    else {
        carp "First parameter must be a hashref, trying to adjust...";
        $args = { @_[ARG0 .. $#_] };
    }
    
    $args->{ lc $_ } = delete $args->{ $_ }
        for grep { !/^_/ } keys %$args;

    unless ( $args->{event} ) {
        carp "Missing 'event' parameter to link_for()";
        return;
    }

    unless ( defined $args->{tags} ) {
        carp "Missing 'tags' parameter to link_for()";
        return;
    }

    if ( $args->{session} ) {
        if ( my $ref = $kernel->alias_resolve( $args->{session} ) ) {
            $args->{sender} = $ref->ID;
        }
        else {
            carp "Could not resolve 'session' parameter to a valid"
                    . " POE session";
            return;
        }
    }
    else {
        $args->{sender} = $sender;
    }
    
    $kernel->refcount_increment( $args->{sender} => __PACKAGE__ );
    $self->{wheel}->put( $args );
    
    undef;
}

sub shutdown {
    my $self = shift;
    $poe_kernel->call( $self->{session_id} => 'shutdown' => @_ );
}

sub _shutdown {
    my ( $kernel, $self ) = @_[ KERNEL, OBJECT ];
    $kernel->alarm_remove_all;
    $kernel->alias_remove( $_ ) for $kernel->alias_list;
    $kernel->refcount_decrement( $self->{session_id} => __PACKAGE__ )
        unless $self->{alias};

    $self->{shutdown} = 1;
    
    $self->{wheel}->shutdown_stdin
        if $self->{wheel};
}

sub _child_closed {
    my ( $kernel, $self ) = @_[ KERNEL, OBJECT ];
    
    carp "_child_closed called (@_[ARG0..$#_])\n"
        if $self->{debug};

    delete $self->{wheel};
    $kernel->yield('shutdown')
        unless $self->{shutdown};

    undef;
}

sub _child_error {
    my ( $kernel, $self ) = @_[ KERNEL, OBJECT ];
    carp "_child_error called (@_[ARG0..$#_])\n"
        if $self->{debug};

    delete $self->{wheel};
    $kernel->yield('shutdown')
        unless $self->{shutdown};

    undef;
}

sub _child_stderr {
    my ( $kernel, $self ) = @_[ KERNEL, OBJECT ];
    carp "_child_stderr: $_[ARG0]\n"
        if $self->{debug};

    undef;
}

sub _child_stdout {
    my ( $kernel, $self, $input ) = @_[ KERNEL, OBJECT, ARG0 ];
    
    my $session = delete $input->{sender};
    my $event   = delete $input->{event};

    $kernel->post( $session, $event, $input );
    $kernel->refcount_decrement( $session => __PACKAGE__ );
    
    undef;
}

sub _wheel {
    my $obj_args = shift;

    if ( $^O eq 'MSWin32' ) {
        binmode STDIN;
        binmode STDOUT;
    }
    
    my $raw;
    my $size = 4096;
    my $filter = POE::Filter::Reference->new;

    my $obj = CPAN::LinksToDocs::No404s->new( %{ $obj_args || {} } );

    while ( sysread STDIN, $raw, $size ) {
        my $requests = $filter->get( [ $raw ] );
        foreach my $req_ref ( @$requests ) {

            _process_request( $obj, $req_ref ); # changes $req_ref

            my $response = $filter->put( [ $req_ref ] );
            print STDOUT @$response;
        }
    }
}

sub _process_request {
    my ( $obj, $req_ref ) = @_;

    $req_ref->{response} = $obj->link_for( $req_ref->{tags} );

    undef;
}

1;
__END__