Why not adopt me?

This distribution is up for adoption! If you're interested then please contact the PAUSE module admins via email.

NAME

POE::Component::IRC::Plugin::FTP::EasyUpload - provide files to IRC users via FTP

SYNOPSIS

    use strict;
    use warnings;

    use POE qw(Component::IRC  Component::IRC::Plugin::FTP::EasyUpload);

    die "Usage: perl ftp_bot.pl <host> <login> <password>\n"
        unless @ARGV == 3;

    my ( $Host, $Login, $Password ) = @ARGV;

    my $irc = POE::Component::IRC->spawn(
        nick        => 'FTPBot',
        server      => 'irc.freenode.net',
        port        => 6667,
        ircname     => 'FTP uploading bot',
    );

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

    $poe_kernel->run;

    sub _start {
        $irc->yield( register => 'all' );

        $irc->plugin_add(
            'FTPEasyUpload' =>
                POE::Component::IRC::Plugin::FTP::EasyUpload->new(
                    host    => $Host,
                    login   => $Login,
                    pass    => $Password,
                    pub_uri => 'http://zoffix.com/',
                )
        );

        $irc->yield( connect => {} );
    }

    sub irc_001 {
        $irc->yield( join => '#zofbot' );
    }

    sub irc_public {
        $irc->yield( privmsg => '#zofbot' => 'See <irc_ftp:test.txt:public_html:>' );
    }

    <Zoffix> blargh
    <FTPBot> See http://zoffix.com/test.txt

DESCRIPTION

Being a bot herder as I am I often needed to upload some file there somewhere and post a link to IRC so other users could grab the file... So here it is, FTP uploading plugin which watches for special "tags" in the outgoing messages which tell it to upload certain file.

Note: uploading is done in a non-blocking way, keep that in mind in case you'd want to send some messages in a certain sequence.

HOW DOES IT WORK

Process is simple. Your "tag" is a regex with one to three capturing parentheses (see tag argument to constructor). Based on those captures the specified file will be uploaded to a specified directory and the "tag" will be replaced by the URI pointing to that file. After all that message will be sent where it was supposed to go.

The plugin watches for "tags" in privmsg and notice message.

CONSTRUCTOR

`new`

    # plain
    $irc->plugin_add(
        'FTPEasyUpload' =>
            POE::Component::IRC::Plugin::FTP::EasyUpload->new(
                host    => 'ftp.some-host.com',
                login   => 'zoffer',
                pass    => 'some-password',
            )
    );

    # juicy
    $irc->plugin_add(
        'FTPEasyUpload' =>
            POE::Component::IRC::Plugin::FTP::EasyUpload->new(
                host            => $Host,
                login           => $Login,
                pass            => $Password,
                pub_uri         => 'http://zoffix.com/',
                unique          => 1,
                port            => 21,
                timeout         => 30,
                retries         => 3,
                verbose_error   => 1,
                tag             => qr/<irc_ftp:(.+?):(.*?):(.*?)>/,
                obj_args        => [ Passive => 1, Debug => 1 ],
                debug           => 1,
        },
    );

Creates a new POE::Component::IRC::Plugin::FTP::EasyUpload object suitable to be fed to plugin_add() method of POE::Component::IRC object. Takes quite a few arguments but most of them are optional. Arguments are passed as key/value pairs. Note: most of these arguments can be changed dynamically by accessing them as keys in your plugin object. In other words, to change the retries argument you'd do it as $your_plugin_object->{retries} = 10;. Possible arguments are as follows:

`host`

    ->new( host => 'ftp.some.host.com' );

Mandatory. Takes a scalar as a value which must be the host of the FTP server to which you want to upload your files.

`login`

    ->new( login => $Login );

Mandatory. Takes a scalar as a value which must be the login (user name) with which to login into your FTP account.

`pass`

    ->new( pass => $Password );

Mandatory. Takes a scalar as a value which must be the password to use to login into your FTP account.

`port`

    ->new( port => 21, );

Optional. Takes a scalar as a value which specifies the port number of FTP server to which we shall connect. Defaults to: 21

`timeout`

    ->new( timeout => 30, );

Optional. Takes a scalar as a value which specifies the timeout in seconds for FTP operations. Defaults to: 30

`retries`

    ->new( retries => 5, );

Optional. The plugin is capable of retrying the upload if the previous attempt failed. Takes a scalar as a value which specifies the number of times to retry the upload. If after trying retries times upload still errored out the "tag" will be replaced with either [FTP Error] or the error message (see verbose_error argument below). Defaults to: 5

`obj_args`

    ->new( obj_args => [ Passive => 1, Debug => 1 ] );

Optional. Takes an arrayref as a value. If specifies it will be directly dereferenced into the constructor of Net::FTP object. See documentation for Net::FTP for possible arguments. By default not specified.

`verbose_error`

    ->new( verbose_error => 1 );

Optional. If upload fails (see retries argument above) the "tag" (see below) will be replaced by an error message. The verbose_error argument specifies whether the error should be a generic one or should it describe the problem. Takes either true or false value. When set to a true value the "tag" will be replaced by [FTP Error: error_message] where error_message will be the text describing why the error occured. When verbose_error argument is set to a false value the "tag" will be replaced by a generic message indicating that an error occured which looks like [FTP Error]. Defaults to: 1

`tag`

    ->new( tag => qr/<irc_ftp:(.+?):(.*?):(.*?)>/, );

Optional. Here is where you can specify for what plugin should look for when deciding what to upload. The tag argument takes a regex (qr//) as a value. The regex must contain at least one capturing group of parentheses but normally you'd want to have three there. The capturing parentheses capture the filename of the file to upload, directory to cd into (on the server) before uploading and the text to prepend to pub_uri (see below) before sending the message to IRC. In other words, if your tag argument is set to qr/<irc_ftp:(.+?):(.*?):(.*?)>/, your pub_uri argument (see below) is set to http://foo.com/ and you send an IRC message "See <irc_ftp:test.txt:public_html:stuff/>" then the plugin will connect to your FTP server, change into public_html directory, upload file test.txt and if everything went well will send message "See http://foo.com/stuff/test.txt" to IRC (providing unique argument (see below) is set to a false value).

Defaults to: qr/<irc_ftp:(.+?):(.*?):(.*?)>/

`pub_uri`

    ->new( pub_uri  => 'http://zoffix.com/', );

Optional. Takes a scalar as a value which will be prepended to the filename of the uploaded file. In other words, if you uploaded file named test.txt and your pub_uri argument is set to http://test.com/ then the "tag" (see above) will be replaced with text http://test.com/test.txt. Defaults to: empty string

`unique`

    ->new( unique => 1, );

Optional. Takes either a true or false value. When set to a true value will use put_unique to upload a file meaning the uploaded filename should be uniquely generated by the server. When set to a false value the uploaded file will have the same name as the original (the local one). Defaults to: 0

`debug`

    ->new( debug => 1, );

Optional. Takes either a true or false value. When set to a true value the plugin will carp() out some debuging info. Note: this does not affect the Debug argument of Net::FTP object. Defaults to: 0

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-irc-plugin-ftp-easyupload at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Component-IRC-Plugin-FTP-EasyUpload. 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::IRC::Plugin::FTP::EasyUpload

You can also look for information at:

RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=POE-Component-IRC-Plugin-FTP-EasyUpload
AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/POE-Component-IRC-Plugin-FTP-EasyUpload
CPAN Ratings

http://cpanratings.perl.org/d/POE-Component-IRC-Plugin-FTP-EasyUpload
Search CPAN

http://search.cpan.org/dist/POE-Component-IRC-Plugin-FTP-EasyUpload

COPYRIGHT & LICENSE

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

To install POE::Component::IRC::Plugin::FTP::EasyUpload, copy and paste the appropriate command in to your terminal.

cpanm

cpanm POE::Component::IRC::Plugin::FTP::EasyUpload

CPAN shell

perl -MCPAN -e shell
install POE::Component::IRC::Plugin::FTP::EasyUpload

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

Why not adopt me?

NAME

SYNOPSIS

DESCRIPTION

HOW DOES IT WORK

CONSTRUCTOR

new

host

login

pass

port

timeout

retries

obj_args

verbose_error

tag

pub_uri

unique

debug