NAME
Net::FTP::Find - Traverse a directory tree through Net::FTP (or Net::FTPSSL)
SYNOPSIS
use Net::FTP::Find;
my $ftp = Net::FTP::Find->new('localhost');
$ftp->login('user', 'pass');
$ftp->find(sub { ... }, '/');
$ftp->finddepth(sub { ... }, '/');
or
use Net::FTP;
use Net::FTP::Find::Mixin;
my $ftp = Net::FTP->new('localhost');
$ftp->login('user', 'pass');
$ftp->find(sub { ... }, '/');
$ftp->finddepth(sub { ... }, '/');
or
use Net::FTPSSL;
use Net::FTP::Find::Mixin qw(Net::FTPSSL);
my $ftp = Net::FTPSSL->new('localhost');
$ftp->login('user', 'pass');
$ftp->find(sub { ... }, '/');
$ftp->finddepth(sub { ... }, '/');
DESCRIPTION
These are functions for searching through directory trees doing work on
each file found similar to the File::Find. Net::FTP::Find provides two
functions, "find" and "finddepth". They work similarly but have subtle
differences.
FUNCTIONS
find
$ftp->find(\&wanted, @directories);
$ftp->find(\%options, @directories);
finddepth
$ftp->finddepth(\&wanted, @directories);
$ftp->finddepth(\%options, @directories);
%options
The first argument to "find()" is either a code reference to your
&wanted function, or a hash reference describing the operations to be
performed for each file. The code reference is described in "The wanted
function" below.
Here are the possible keys for the hash:
"wanted"
The value should be a code reference. This code reference is
described in "The wanted function" below. The &wanted subroutine is
mandatory.
"bydepth"
Reports the name of a directory only AFTER all its entries have been
reported. Entry point "finddepth()" is a shortcut for specifying "{
bydepth => 1 }" in the first argument of "find()".
"no_chdir"
Does not "cwd()" to each directory as it recurses. The "wanted()"
function will need to be aware of this, of course. In this case, $_
will be the same as $Net::FTP::Find::name.
"max_depth"
The directories that are deeper than this value is traversed.
"min_depth"
The directories that are shallower than this value is traversed.
"use_mlsd"
If true, Net::FTP::Find tries to use the "MLSD" to retrieve entries.
By using the "MLSD", we can fetch "mtime" of each file effectivly.
Net::FTP::Find use the "LIST" instead automatically if the "MLSD"
cannot be used. Default value is "1".
"fetch_mtime"
If true, Net::FTP::Find tries to fetch "mtime" of each file. When
"MLSD" can be used, "mtime" is fetched with file list. When "MLSD"
cannot be used, "mtime" is fetched by using "MDTM" internally.
Default value is "0".
The wanted function
The "wanted()" function does whatever verifications you want on each
file and directory. Note that despite its name, the "wanted()" function
is a generic callback function, and does not tell Net::FTP::Find if a
file is "wanted" or not. In fact, its return value is ignored.
The wanted function takes no arguments but rather does its work through
a collection of variables.
$Net::FTP::Find::dir is the current directory name,
$_ is the current filename within that directory
$Net::FTP::Find::name is the complete pathname to the file.
$Net::FTP::Find::is_directory is 1 if $_ is directory.
These variables may be able to use if server is supporting.
$Net::FTP::Find::mtime is modification time (Unix epoch). this value is
generated by parsing "YYYYMMDDHHMMSS" as GMT. If a server returns mtime
as JST, this value may not be correct.
$Net::FTP::Find::is_symlink is 1 if $_ is symlink.
$Net::FTP::Find::mode is mode.
$Net::FTP::Find::user is owner name.
$Net::FTP::Find::group is group name.
$Net::FTP::Find::size is file size in bytes.
The above variables have all been localized and may be changed without
effecting data outside of the wanted function.
For example, when examining the file /some/path/foo.ext you will have:
$Net::FTP::Find::dir = /some/path/
$_ = foo.ext
$Net::FTP::Find::name = /some/path/foo.ext
You are cwd()'d to $Net::FTP::Find::dir when the function is called,
unless "no_chdir" was specified. Note that when changing to directories
is in effect the root directory (/) is a somewhat special case inasmuch
as the concatenation of $Net::FTP::Find::dir, '/' and $_ is not
literally equal to $Net::FTP::Find::name. The table below summarizes all
variants:
$Net::FTP::Find::name $Net::FTP::Find::dir $_
default / / .
no_chdir=>0 /etc / etc
/etc/x /etc x
no_chdir=>1 / / /
/etc / /etc
/etc/x /etc /etc/x
AUTHOR
Taku Amano <taku@toi-planning.net>
Some part of code about Net::FTPSSL is referred to Net::FTPSSL.
A mostly parts of the document are from File::Find.
SEE ALSO
File::Find Net::FTP Net::FTPSSL Net::FTP::Find::Mixin
LICENSE
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.