NAME

Net::FTP::Recursive - Recursive FTP Client class

SYNOPSIS

    use Net::FTP::Recursive;

    $ftp = New::FTP::Recursive->new("some.host.name", Debug => 0);
    $ftp->login("anonymous",'me@here.there');
    $ftp->cwd('/pub');
    $ftp->rget( ParseSub => \&yoursub );
    $ftp->quit;

DESCRIPTION

Net::FTP::Recursive is a class built on top of the Net::FTP package that implements recursive get and put methods for the retrieval and sending of entire directory structures.

This module's default behavior is such that the remote ftp server should understand the "dir" command and return UNIX-style directory listings. If you'd like to provide your own function for parsing the data retrieved from this command (in case the ftp server does not understand the "dir" command), all you need do is provide a function to one of the Recursive method calls. This function will take the output from the "dir" command (as a list of lines) and should return a list of Net::FTP::Recursive::File objects. This module is described below.

When the Debug flag is used with the Net::FTP object, the Recursive package will print some messages to STDERR.

CONSTRUCTOR

new (HOST [,OPTIONS])

A call to the new method to create a new Net::FTP::Recursive object just calls the Net::FTP new method. Please refer to the Net::FTP documentation for more information.

METHODS

rget ( [ParseSub =>\&yoursub] )

The recursive get method call. This will recursively retrieve the ftp object's current working directory and its contents into the local current working directory.

This will also take an optional argument that will control what happens when a symbolic link is encountered on the ftp server. The default is to ignore the symlink, but you can control the behavior by passing one of these arguments to the rget call (ie, $ftp->rget(SymlinkIgnore => 1)):

SymlinkIgnore - disregards symlinks

SymlinkCopy - copies the link target from the server to the client (if accessible)

SymlinkLink - creates the link on the client.

rput ( [ParseSub => \&yoursub] [DirCommand => $cmd])

The recursive put method call. This will recursively send the local current working directory and its contents to the ftp object's current working directory.

This method will take an optional set of arguments to tell it what the local directory listing command will be. By default, this is "ls -al". If you change the behavior through this argument, you probably also need to provide a ParseSub, as described above.

This will take an optional argument that will control what happens when a symbolic link is encountered on the ftp server. The default is to ignore the symlink, but you can control the behavior by passing one of these arguments to the rput call (ie, $ftp->rput(SymlinkIgnore => 1)):

SymlinkIgnore - disregards symlinks

SymlinkCopy - will copy the link target from the client to the server.

rdir ( Filehandle => $fh [, FilenameOnly => 1 ] [, ParseSub => \&yoursub ] )

The recursive dir method call. This will recursively retrieve directory contents from the server in a breadth-first fashion.

The method needs to be passed a filehandle to print to. The method call just does a print $fh, so as long as this call can succeed with whatever you pass to this function, it'll work.

The second, optional argument, is to retrieve only the filenames (including path information). The default is to display all of the information returned from the $ftp-dir call.

rls ( Filehandle => $fh [, ParseSub => \&yoursub ] )

The recursive ls method call. This will recursively retrieve directory contents from the server in a breadth-firth fashion. This is equivalent to calling $ftp-rdir( Filehandle => $fh, FilenameOnly => 1 )>.

Net::FTP::Recursive::File

This is a helper class that encapsulates the data representing one file in a directory listing.

METHODS

new ( )

This method creates the File object. It should be passed several parameters. It should always be passed:

OriginalLine => $line

Fields => \@fields

And it should also be passed one (and only one) of:

IsPlainFile => 1

IsDirectory => 1

IsSymlink => 1

OriginalLine should provide the original line from the output of a directory listing.

Fields should provide an 8 element list that supplies information about the file. The fields, in order, should be:

Permissions

Link Count

User Owner

Group Owner

Size

Last Modification Date/Time

Filename

Link Target

The IsPlainFile, IsDirectory, and IsSymlink fields need to be supplied so that for the output on your particular system, your code (in the ParseSub) can determine which type of file it is so that the Recursive calls can take the appropriate action for that file. Only one of these three fields should be set to a "true" value.

TODO LIST

Allow for formats to be given for output on rdir/rls.

REPORTING BUGS

When reporting bugs, please provide as much information as possible. A script that exhibits the bug would also be helpful, as well as output with the "Debug => 1" flag turned on in the FTP object.

AUTHOR

Jeremiah Lee <texasjdl@yahoo.com>

SEE ALSO

Net::FTP

Net::Cmd

ftp(1), ftpd(8), RFC 959

CREDITS

Andrew Winkler - for various input into the module.

COPYRIGHT

Copyright (c) 2001-2003 Jeremiah Lee.

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

cpanm Net::FTP::Recursive

perl -MCPAN -e shell
install Net::FTP::Recursive