Wil Cooley > Net-FTP-Simple-0.0007 > Net::FTP::Simple

Download:
Net-FTP-Simple-0.0007.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.0007   Source  

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

retrieve_files() Options

list_files() Options

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 ^

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.

syntax highlighting: