The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Net-FTP-Simple-0.0007
River stage zero No dependents
++
/ Net::FTP::Simple

NAME

Net::FTP::Simple - Simplified interface to a few common FTP tasks with Net::FTP.

VERSION

This document describes Net::FTP::Simple version 0.0005.

SYNOPSIS

    use Net::FTP::Simple;

    my @remote_files = Net::FTP::Simple->list_files({
            username        => $username,
            password        => $password,
            server          => $server,
            remote_dir      => 'path/to/dir',
            debug_ftp       => 1,
            file_filter     => qr/foo/,
        });

    print "List:\n\t", join("\n\t", @remote_files), "\n")
        if @remote_files;

    my @sent_files = Net::FTP::Simple->send_files({
            username        => $username,
            password        => $password,
            server          => $server,
            remote_dir      => 'path/to/dir',
            debug_ftp       => 1,
            files           => [
                                    'foo.txt',
                                    'bar.txt',
                                    'baz.txt',
                                ],
        });

    print "The following files were sent successfully:\n\t",
        join("\n\t", @sent_files), "\n"
            if @sent_files;


    my @received_files = Net::FTP::Simple->retrieve_files({
            username        => $username,
            password        => $password,
            server          => $server,
            remote_dir      => 'path/to/dir',
            debug_ftp       => 1,
            files           => [
                                    'foo.txt',
                                    'bar.txt',
                                    'baz.txt',
                                ],
        });

    print "The following files were retrieved successfully:\n\t",
        join("\n\t", @received_files), "\n"
            if @received_files;

    my @received_filtered_files = Net::FTP::Simple->retrieve_files({
            username        => $username,
            password        => $password,
            server          => $server,
            remote_dir      => 'path/to/dir',
            debug_ftp       => 1,
            file_filter     => qr/^ba.\.txt/,
            delete_after    => 1,
        });

    print "The following files were retrieved successfully:\n\t",
        join("\n\t", @received_filtered_files), "\n"
            if @received_filtered_files;

    my @renamed_files = Net::FTP::Simple->rename_files({
            username        => $username,
            password        => $password,
            server          => $server,
            remote_dir      => 'path/to/dir',
            debug_ftp       => 1,
            rename_files    => {
                    'old_name'  => 'new_name',
            },
    });

INTERFACE

Net::FTP::Simple provides the user with four operations: list a directory, retrieve a directory or list of files, send a list of files and rename a list of files.

All four operations, list_files(), retrieve_files(), send_files() and rename_files() may be invoked using either module or class syntax; i.e., Net::FTP::Simple::list_files() or Net::FTP::Simple->list_files(). As these are one-shot operations, there is no publically-instantiable object.

All operations are invoked with a single hash ref argument with the options described below as hash keys.

There is a generalized retry infrastructure; currently only renames (used in both send_files() and rename_files()) are retried, but future enhancement should allow all operations to be retried. To disable retries for rename, set

 $Net::FTP::Simple::retry_max{'rename'} = 0;

The retry infrastructure also sleeps for 10 seconds by default between tries. This may be adjusted with

 $Net::FTP::Simple::retry_wait{'rename'} = 0;

WARNING: Directly fiddling with package variables like this does not make a good interface, so don't expect it to stay around!

Subroutines

send_files()

Given a list of files, send them via FTP.

It does not preserve the local path of the files; it strips the filename down to the base filename and sends it to the directory on the FTP server named in the 'remote_dir' parameter.

When uploading, files are sent with '.tmp' appended to their names and then renamed into place, because some FTP servers process files based on their extensions and this ensures each file is sent completely before processing.

'remote_dir' is created if it does not exist.

Returns an array or array ref of the original names of the sent files.

retrieve_files()

Retrieve a list of files or a directory of files.

Does not work recursively.

Unlike send_files, it does not create the (local) destination nor does it change to it.

If 'delete_after' is true, then the remote files are deleted after being successfully downloaded. [ FIXME Should a transfer be considered successful if the file is retrieved but not deleted? Currently, it is. ]

Files may be specified with a list called 'files' or a regular expression 'file_filter'. 'files' takes precedence over 'file_filter'; if both are given, the latter is ignored.

list_files()

List files in a given directory.

Ignores anything that is not a normal file--directories, device files, FIFOs, sockets, etc. Currently only works with UNIX-like directory listings.

rename_files()

Renames the files given in the hash ref 'rename_files', after first changing to 'remote_dir'.

Returns a list (or list ref, in scalar context) of the original names of the renamed files.

Common Options

  • server

    Hostname or IP address of FTP server.

  • username

    Login username.

  • password

    Login password.

  • mode

    ascii or binary (default binary).

  • debug_ftp

    (bool) Turn on Net::FTP debugging.

  • remote_dir

    Remote directory against which to operate.

  • files

    List ref of files to operate one.

retrieve_files() Options

  • delete_after

    (bool) Delete files after retrieving them.

  • file_filter

    Regex against which to apply to list of remote files.

list_files() Options

  • file_filter

    Regex against which to apply to list of remote files.

DIAGNOSTICS

This module is intended to be a simplified interface to complex options; as such, it handles almost all errors itself--by croaking. Errors with individual files (even if it involves all such files) are reported and the failing files not added to the list of successful transfers.

In some cases, operations which are known to fail with transient errors can be retried.

CONFIGURATION AND ENVIRONMENT

Net::FTP::Simple requires no configuration files or environment variables.

DEPENDENCIES

As this module is a facade layer on top of Net::FTP, it requires Net::FTP.

INCOMPATIBILITIES

None known.

BUGS AND LIMITATIONS

No bugs have been reported (so far). It is unlikely that the behaviours encapsulated in this module with meet with everyone's needs, but hey, that's life. For one thing, it probably should support proxying.

Please report any bugs or feature requests to bug-net-ftp-simple@rt.cpan.org, or through the web interface at http://rt.cpan.org.

TODO

  • Implement retry for all Net::FTP operations

  • Move carp messages into a package hash for easier testing and client-based filtering of warnings.

  • Add ability to disable renaming in send_files().

  • Split major operations into separate test modules, with separate module for private subroutines.

  • Add unit testing for retrieve_files().

  • More thorough testing all around.

AUTHOR

Wil Cooley <wcooley@nakedape.cc>

LICENSE AND COPYRIGHT

Copyright (c) 2006, Wil Cooley <wcooley@nakedape.cc>. All rights reserved.

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

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. IF SOMETHING IS TYPED IN ALL CAPITAL LETTERS IT LOOKS REALLY MEAN AND OFFICIAL, WHICH IS WHY LAWYERS LOVE IT. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.