=head1 NAME

Net::FTP::Robust - download files over FTP

=head1 SYNOPSIS

 my $ftp = Net::FTP::Robust->new
  ( Host    => $host
  , Port    => $port
  );

 # when needed, many attempts will be made to retrieve all
 $ftp->get($remote_dir, $local_dir);
 $ftp->get($remote_dir);

 # to get client-side errors as well:
 use Log::Report;       # get 'try()'
 try { $ftp->get(...) };
 if($@) {...}

 # make the process more verbose, start with
 Log::Report mode => 'VERBOSE';
 Log::Report mode => 'DEBUG';

 # to catch all reports: errors, warnings, debugs etc
 try { $ftp->get(...) } mode => 'DEBUG';
 push @trace, $@->exceptions; # simply prints all
 $@->reportFatal;             # re-cast real errors

=head1 DESCRIPTION

This module is specialized in (on the moment only) downloading large
data-sets (gigabytes) autonomously. It uses Net::FTP, and adds various
algorithms to work around various common problems.  In general, local
errors are fatal and server or network errors are recovered.

See L</DETAILS> far down on this page for more explanations and
limitations.

=head1 METHODS

=head2 Constructors

Net::FTP::Robust-E<gt>B<new>(OPTIONS)

=over 4

Use to connect to one ftp-server.
All B<OPTIONS which start with capitals> are passed to Net::FTP
method C<new()>.

 Option        --Default
 host            <undef>
 login_attempts  10
 login_delay     60
 password        '-anonymous@'
 skip_names      <skip hidden files>
 user            'anonymous'

. host => HOSTNAME

=over 4

Alternative for the C<Host> parameter for Net::FTP subroutine new.

=back

. login_attempts => INTEGER

=over 4

How many different connections will we use. Between each attempt,
we wait C<login_delay> seconds.  When '0' is specified, it will
continue forever: you can solve problems discovered in the logs.

=back

. login_delay => INTEGER

=over 4

How much time to wait between retries which require to login again,
in seconds.

=back

. password => STRING

. skip_names => CODE

=over 4

Do not attempt directories or files which contain certain patterns.
When the CODE returns 1, then the element will be ignored.  Typically,
the CODE will apply some regular expressions.

The CODE reference will get three arguments: the ftp object (Net::FTP)
with established connection, the full remote path of the entry, and the
basename of the entry.

=back

. user => STRING

=back

=head2 Download

$obj-E<gt>B<get>(FROM, [TO])

=over 4

The FROM directory or file on the remote server is copied TO a local
directory (defaults to '.')

=back

=head1 DETAILS

=head2 Comparison

Net::FTP implements the FTP protocol.
Various modules on CPAN asbtract the transport protocol further,
for instance Net::FTP::Recurse.  Each module has its own focus.
C<Net::FTP::Robust> is specialized in retries and logging, to retrieve
data which takes hours to download, sometimes over quite instable
connections.  It uses Log::Report which can connect to various logging
frameworks for its messages.

=head2 Limitations

The L<get()|Net::FTP::Robust/"Download"> will collect directories recursively or single files.

When a new L<get()|Net::FTP::Robust/"Download"> is ran with the same destination directory, then
the download will continue where it left-of.  Files which were only
partially downloaded will get downloaded only for the missing part.

Files will not get deleted, not on the server and not on the client.
Symbolic links on the server are invisible on the local copy.

When downloading, the name of the directory and file will temporarily be
mangled: only when the download is completed, the real name will show up.
For UNIX, the names will temporarily start with a dot, to be hidden from
the standard C<ls(1)> output.

When you have the permission from your OS, the modification time
will get copied from the source as well.

=head1 SEE ALSO

This module is part of Net-FTP-Robust distribution version 0.03,
built on November 13, 2009. Website: F<http://perl.overmeer.net>.  See also L<Net::FTPSSL>.

=head1 COPYRIGHTS

Copyrights of the perl code and the related documentation by
2009 by Mark Overmeer. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See F<http://www.perl.com/perl/misc/Artistic.html>

