NAME

POE::Component::Pastebin::Create - Non-blocking wrapper to the WWW::Pastebin::*::Create modules

VERSION

version 0.001

SYNOPSIS

        use strict;
        use warnings;

        use POE qw(Component::Pastebin::Create);

        my $poco = POE::Component::Pastebin::Create->spawn;

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

        $poe_kernel->run;
        
        sub _start {
                my %info = (text => 'Lorem ipsum', event => 'pasted');

                $poco->paste(\%info);
                # Alternative syntax:
                # $poe_kernel->post($poco->session_id, 'paste', \%info);
        }

        sub pasted {
                my $data = $_[ARG0];

                say "Pasted URL: ".$data->{uri};

                $poco->shutdown;
        }

DESCRIPTION

This module is a non-blocking POE wrapper around the various WWW::Pastebin::*::Create classes.

As of the time of writing, it should work with every one of those modules on CPAN except for WWW::Pastebin::PastebinCom::Create, due to a few API differences. This will be fixed later.

NAME

POE::Component::Pastebin::Create - non-blocking wrapper around the various WWW::Pastebin::*::Create classes

CONSTRUCTOR

spawn

        my $poco = POE::Component::Pastebin::Create->spawn;

        POE::Component::Pastebin::Create->spawn(
                alias => 'pastebin',
                pastebin_class => 'Sprunge',
                pastebin_args => {},
                options => {
                        debug => 1,
                        trace => 1,
                        # POE::Session arguments for the component
                },
                debug => 1, # output some debug info
        );

alias

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

Optional. Specifies a POE Kernel alias for the component.

pastebin_class

        ->spawn( pastebin_class => 'Sprunge' );
        ->spawn( pastebin_class => '+WWW::Pastebin::Sprunge::Create' );

Specifies the name of the class that will be used to create pastes. Normally, the class is interpolated like this: WWW::Pastebin::${name}::Create. If you prefix the name with +, it is used as an absolute module name. Defaults to: Sprunge.

pastebin_args

        ->spawn( pastebin_args => {} );

Optional. Options/arguments that will be passed into the "new" method of the pastebin class.

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

paste

        $poco->paste( {
                        event       => 'event_for_output',
                        text        => 'Lorem ipsum dolor sit amet, ...',
                        _blah       => 'pooh!',
                        session     => 'other',
                }
        );

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

paste

        $poe_kernel->post( pastebin => paste => {
                        event       => 'event_for_output',
                        text        => 'Lorem ipsum dolor sit amet ...',
                        _blah       => 'pooh!',
                        session     => 'other',
                }
        );

Instructs the component to create a new paste. Takes a hashref as an argument, the possible keys/value of that hashref are as follows:

event

        { event => 'pasted_event', }

Mandatory. Specifies the name of the event to emit when the paste has been created. See OUTPUT section for more information.

text

        { text => 'Lorem ipsum dolor sit amet ...' }

Mandatory. The text that will be pasted.

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.

extra parameters

        { nick => 'Treeki', lang => 'perl', }

Optional. These will be passed directly to the paste method of the pastebin object, and are specific to whichever class is used.

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

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

OUTPUT

        $VAR1 = {
                'uri' => URI->new("http://www.example.com/12345"),
                '_blah' => 'foos'
        };

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

uri

        Will be present if the paste creation completed. Contains a L<URI> object.

error

        Will be present if something went wrong during the paste creation. Contains
        an explanation of the failure.

user defined

        { '_blah' => 'foos' }

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

SEE ALSO

POE, WWW::Pastebin::Sprunge::Create

AUTHOR

Jan A. (Treeki) <treeki@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Jan A. (Treeki).

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm POE::Component::Pastebin::Create

perl -MCPAN -e shell
install POE::Component::Pastebin::Create