30 Nov 2003 21:19:04 UTC
- Distribution: Net-FTP-Recursive
- Module version: 1.8
- Source (raw)
- Browse (raw)
- How to Contribute
- Issues (3)
- Testers (0 / 0 / 0)
- KwaliteeBus factor: 0
- License: unknown
- Activity24 month
- Download (12.51KB)
- MetaCPAN Explorer
- Subscribe to distribution
- This version
- Latest version
- TODO LIST
- REPORTING BUGS
- SEE ALSO
Net::FTP::Recursive - Recursive FTP Client class
use Net::FTP::Recursive; $ftp = Net::FTP::Recursive->new("some.host.name", Debug => 0); $ftp->login("anonymous",'firstname.lastname@example.org'); $ftp->cwd('/pub'); $ftp->rget( ParseSub => \&yoursub ); $ftp->quit;
Net::FTP::Recursiveis 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.
All of the methods also take an optional
KeepFirstLineargument which is passed on to the default parsing routine. This argument supresses the discarding of the first line of output from the dir command. wuftpd servers provide a total line, the default behavior is to throw that total line away. If yours does not provide the total line,
KeepFirstLineis for you. This argument is used like the others, you provide the argument as the key in a key value pair where the value is true (ie, KeepFirstLine => 1).
Debugflag is used with the
Recursivepackage will print some messages to
All of the methods should return false ('') if they are successful, and a true value if unsuccessful. The true value will be a string of the concatenations of all of the error messages (with newlines). Note that this might be the opposite of the more intuitive return code.
- new (HOST [,OPTIONS])
A call to the new method to create a new
Net::FTP::Recursiveobject just calls the
Net::FTPnew method. Please refer to the
Net::FTPdocumentation for more information.
- rget ( [ParseSub =>\&yoursub] [,FlattenTree => 1] [,RemoveRemoteFiles => 1] )
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)):
SymlinkFollowoption, as of v1.6, does more sophisticated handling of symlinks. It will detect and avoid cycles, on all client platforms. Also, if on a UNIX (tm) platform, if it detects a cycle, it will create a symlink to the location where it downloaded the directory (or will download it subsequently, if it is in the subtree under where the recursing started). On Windows, it will call symlink just as on UNIX (tm), but that's probably not gonna do much for you. :)
FlattenTreeoptional argument will retrieve all of the files from the remote directory structure and place them in the current local directory. This option will resolve filename conflicts by retrieving files with the same name and renaming them in a "$filename.$i" fashion, where $i is the number of times it has retrieved a file with that name.
RemoveRemoteFilesargument to the function will allow the client to delete files from the server after it retrieves them. The default behavior is to leave all files and directories intact.
For the v1.6 release, I have also added some additional functionality that will allow the client to be more specific in choosing those files that are retrieved. All of these options take a regex object (made using the
qroperator) as their value. You may choose to use one or more of these options, they are applied in the order that they are listed. They are:
- OmitAll - Do not process file that matches this regex. Also may be overridden with the previous options.
- OmitFiles - Omit those plainish files that match this pattern.
- MatchDirs - Only recurse into directories that match this pattern.
- OmitDirs - Do not recurse into directories that match this pattern.
Currently, the added functionality given to the rget method is not implemented for the rput method.
- rput ( [ParseSub => \&yoursub] [,DirCommand => $cmd] [,FlattenTree => 1] [,RemoveLocalFiles => 1])
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)):
FlattenTreeoptional argument will send all of the files from the local directory structure and place them in the current remote directory. This option will resolve filename conflicts by sending files with the same name and renaming them in a "$filename.$i" fashion, where $i is the number of times it has retrieved a file with that name.
RemoveLocalFilesargument to the function will allow the client to delete files from the client after it sends them. The default behavior is to leave all files and directories intact. This option will only attempt to delete files that were actually transferred, symlinks (unless you set SymlinkCopy and it is a plain file) will not be removed (and of course any non-empty directories).
- 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.
This method WILL follow symlinks. It has the same basic cycle-checking code that is in rget, so it should not infinitely loop.
- rls ( Filehandle => $fh [, ParseSub => \&yoursub] )
The recursive ls method call. This will recursively retrieve directory contents from the server in a breadth-first fashion. This is equivalent to calling
$ftp-rdir( Filehandle => $fh, FilenameOnly => 1 )>.
- rdelete ( [ ParseSub => \&yoursub ] )
The recursive delete method call. This will recursively delete everything in the directory structure. This disregards the
SymlinkFollowoption and does not recurse into symlinks that refer to directories.
This is a helper class that encapsulates the data representing one file in a directory listing.
- new ( )
This method creates the File object. It should be passed several parameters. It should always be passed:
And it should also be passed at least one (but only one a true value) of:
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:
IsSymlinkfields 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.
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.
Jeremiah Lee <email@example.com>
ftp(1), ftpd(8), RFC 959
(in Chronological order)
Andrew Winkler - for various input into the module. Raj Mudaliar - documentation fix. Brian Reischl - for rdelete code. Chris Smith - for RemoveRemoteFiles code. Zainul Charbiwala - bug report & code to fix. Brian McGraw - bug report & feature request.
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.
1 POD Error
The following errors were encountered while parsing the POD:
- Around line 1236:
You forgot a '=back' before '=head1'
Module Install Instructions
To install Net::FTP::Recursive, copy and paste the appropriate command in to your terminal.
perl -MCPAN -e shell install Net::FTP::Recursive
For more information on module installation, please visit the detailed CPAN module installation guide.