File(3)

NAME
Net::FTP::File - Perl extension for simplifying FTP file operations.

SYNOPSIS
   use Net::FTP::File;

   my $ftp = Net::FTP->new("some.host.name", Debug => 0)
      or die "Cannot connect to some.host.name: $@";

   $ftp->login("anonymous",'-anonymous@')
      or die "Cannot login ", $ftp->message;

   if($ftp->isfile($file) {
      $ftp->move($file,$newfile) or warn $ftp->message;
      $ftp->chmod(644, $newfile) or warn $ftp->message;
   } else { print "$file does not exist or is a directory"; }

   my $dirinfo_hashref = $ftp->dir_hashref;

   print Dumper $dirinfo_hashref->{$file}; # Dumper() is from Data::Dumper, just FYI

   $ftp->quit;

METHODS

  $ftp->exists
Returns true if the argument exists and is a file or directory.

   print "$file exists\n" if $ftp->exists($file);

  $ftp->isfile
Returns true if the argument exists and is not a directory.

   print "$file is a file\n" if $ftp->isfile($file);

  $ftp->isdir
Returns true if the argument is a directory. It returns undef and sets $ftp->message if there is a problem while determining its status.

   my $isdir = $ftp->isdir($file);

   print "$file is a directory\n" if $isdir;
   print $ftp->message if undef $ftp->message;

  $ftp->copy
Copies files (not directories) on the remote server. Returns undef if the argument !$ftp->isfile or there are otherwise errors.

   $ftp->copy($orig, $new) or die $ftp->message;

or you can specify a directory to change into after $orig is read and before it writes $new (it will attempt to change back to the current directory once its done):

   $ftp->copy($orig, $new, $dir) or die $ftp->message;

and also a timout for the reading and writing of the files:

   $ftp->copy($orig, $new, $dir, $timeout) or die $ftp->message;

or only a timout (IE third argument is numeric)

   $ftp->copy($orig, $new, $timeout) or die $ftp->message;

if you want to change into a directory whose name is made of all numbers then you can either define the forth argument or use a trailing slash on the third argument (if there is no forth argument) so that it is not all numeric.

  $ftp->move
$ftp->copy()'s a file (so all of $ftp->copy()'s arguments and paradigms apply to this method, then deletes the original if successful and checks that all went well and sets $ftp->message if it didn't.

   $ftp->move($orig, $new) or die $ftp->message;

It returns undef and sets $ftp->message if you specify the same thing for each file so that its not deleted when the original is removed.

  $ftp->chmod
Returns undefined if the FTP server does not support the FTP protocol's SITE CHMOD. Otherwise it returns 1 if response is ok, 0 if it failed and -1 if it was neither specifically.

   $ftp->chmod(644, $file) or die $ftp->message;

The arguments are sent basically as "SITE CHMOD your args here" so you will need to call $ftp->chmod with arguments the FTP server you are connected to understands. 99% of the time it will be like the example above.

  $ftp->touch
   $ftp->touch or die $ftp->message;

If the file does not exist it creates a new zero byte file.

If the file does exist it modifies its $ftp->mdtm to now.

If the file is a directory it will return -1 * since $ftp->mdtm doesn't really work with directories. You can have it attempt to create a new file of the same name by specifying a second argument that is true:

   $ftp->touch('public_html'); # returns -1 since its a directory

If any knows of a way to change the equivalent of $ftp->mdtm of a directory using ftp, let me know please :)

   $ftp->touch('public_html',1); # attempts to create a file called public_html

One caveat is that some FTP servers will give "public_html: Is a directory" even though its trying to $ftp->put a new file. Anyone who knows a way around that I'd be happy to hear from you :)

Unless there is a problem (IE or die $ftp->message) it will return the current $ftp->mdtm

  $ftp->empty
Create a new empty file or make an existing file 0 size (used by $ftp->touch for non existant or 0 byte files).

   $ftp->empty($file) or die $ftp->message;

  $ftp->dir_hashref
It takes the same arguments as $ftp->dir and returns a hashref of info parsed from $ftp->dir. Each key is the file or path name as returned by $ftp->dir and the value is another hashref of info whose keys are defined in $Net::FTP::File::DirProcHash{cols} (Default is the "Pretty" version, see $ftp->pretty_dir below) and corresponding values are parsed with $Net::FTP::File::DirProcHash{proc}. This can all be customized as needed, see "HANDLING DIRECTORY LISTING FORMATS OF DIFFERENT FTP SERVERS" below for more info.

   my $dir_info_hashref = $ftp->dir_hashref(@net_ftp_dir_args);

Note that spaces in path names and links are not escaped. if that is necessary for your application then you must escape them.

Multiple spaces and single or multiple spaces at the beginning or end are properly preserved.

  $ftp->pretty_dir
Returns true or false if "Pretty" mode is on or off respectively, sets "Pretty" mode if given an argument. "Pretty" mode means that the keys of each file's hashref in $ftp->dir_hashref are either long names (IE Pretty) or short [a-z_]+ versions (IE Utilitarian)

   print $ftp->pretty_dir ? 'I feel Pretty oh so Pretty' : 'I am Utilitarian hear me roar';

   use Net::FTP::File;
   use Data::Dumper;
   ...

   print Dumper $ftp->dir_hashref(@net_ftp_dir_args); # "Pretty" version

   $ftp->pretty_dir(0);
   print Dumper $ftp->dir_hashref(@net_ftp_dir_args); # [a-z_]+ version

   $ftp->pretty_dir(1);
   print Dumper $ftp->dir_hashref(@net_ftp_dir_args); # "Pretty" version

Changing $Net::FTP::File::DirProcHash{cols} overrides any previous $ftp->pretty_dir call/setting and setting $ftp->pretty_dir overrides any custom $Net::FTP::File::DirProcHash{cols}

  $ftp->fstat
This is currently not implemented but will be in the next version. The goal will be to imitate Perl's built in stat() function. It is not $ftp->stat since one day Net::FTP may want to support STAT and likely will call it stat()

HANDLING DIRECTORY LISTING FORMATS OF DIFFERENT FTP SERVERS
Since most FTP servers have their own format of results when using $ftp->dir, this module has a setup that will work with, hopefully, most *nix FTP servers. You can control how $ftp->dir is parsed by customizing the entries in %Net::FTP::File::DirProcHash to suit your FTP server's particular whims. The parts of that hash are described below. Also the source will be very helpful to learn how it fits together so you can achieve whatever you need.

  $Net::FTP::File::DirProcHash{proc}
This is a code reference that you can specify that will parse the lines returned from $ftp->dir The first argument is the line and the second is a hash ref that will ultimatley be returned by $ftp->dir_hashref

  $Net::FTP::File::DirProcHash{cols}
The keys of this hashref should correspond to the index number of the array of items you get when you parse the line in $Net::FTP::File::DirProcHash{proc}->() The values are the labels for these fields.

SEE ALSO
Net::FTP

COMPARISON
Is this module just like another module with similar functionality?

No it is not!

1.  It is a subclass and not a new class that uses Net::FTP underneath. That means the object is a normal Net::FTP object and has all the methods Net::FTP has.

2.  It does not override Net::FTP methods (IE does not have methods the same name as Net::FTP) which means you don't have to sort through how the function differs from the standard version in the Net::FTP module.

3.  Its waaaay simpler to use without a bunch of weird config stuff to cloud the issue, odd hard to remember arguments, obscure methods to replace valid existing ones that are part of Net::FTP, or new methods that are badly named (IE think "grep" on this one). There are other things as well.

4.  It follows the paradigm of Perl name spaces, objects, and general good practice much better and in a way that is more intuitive and expandable.

AUTHOR
Daniel Muey, <http://drmuey.com/cpan_contact.pl>

COPYRIGHT AND LICENSE
Copyright 2005 by Daniel Muey

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

POD ERRORS
Hey! The above document had some coding errors, which are explained below:

Around line 372:
    '=item' outside of any '=over'

Around line 388:
    You forgot a '=back' before '=head1'