NAME

Perl::Download::FTP::Distribution - Identify CPAN distributions and download the most recent tarball via FTP

SYNOPSIS

    use Perl::Download::FTP::Distribution;

    $self = Perl::Download::FTP::Distribution->new( {
        host            => 'ftp.cpan.org',
        dir             => 'pub/CPAN/modules/by-module',
        distribution    => 'Test-Smoke',
        verbose         => 1,
    } );

    @all_releases = $self->ls();

    $latest_release = $self->get_latest_release( {
        path            => '/path/to/download',
        verbose         => 1,
    } );

DESCRIPTION

This library provides (a) methods for obtaining a list of all releases available on CPAN for a given Perl distribution; and (b) a method for downloading the most recent release or a specific release.

This library is similar to Perl::Download::FTP contained in this same CPAN distribution, except that in this module our objective is to download a CPAN library rather than a tarball of the Perl 5 core distribution.

Testing

This library can only be truly tested by attempting live FTP connections and downloads of tarballs of CPAN distributions. Since testing over the internet can be problematic when being conducted in an automatic manner or when the user is behind a firewall, the test files under t/ will only be run live when you say:

    export PERL_ALLOW_NETWORK_TESTING=1 && make test

Each test file further attempts to confirm the possibility of making an FTP connection by using CPAN library Test::RequiresInternet.

METHODS

new()

• Purpose

  Perl::Download::FTP::Distribution constructor.

• Arguments

      $self = Perl::Download::FTP::Distribution->new( {
          distribution    => 'Test-Smoke',
      } );
  
      $self = Perl::Download::FTP::Distribution->new( {
          distribution    => 'Test-Smoke',
          host            => 'ftp.cpan.org',
          dir             => 'pub/CPAN/modules/by-module',
          verbose         => 1,
      } );
  
      $self = Perl::Download::FTP::Distribution->new( {
          distribution    => 'Test-Smoke',
          host            => 'ftp.cpan.org',
          dir             => 'pub/CPAN/modules/by-module',
          Timeout     => 5,
      } );

  Takes a hash reference with, typically, three elements: distribution, host and dir.

  • The distribution element is mandatory; its value must be spelled with hyphens (e.g., Test-Smoke, rather than with the double colons used for modules (Test::Smoke).

  • When no argument is provided for either of host or dir, the values shown above for host and dir will be used. You may enter values for any CPAN mirror which provides FTP access. (See https://www.cpan.org/SITES.html and http://mirrors.cpan.org/.)

  • Any options which can be passed to Net::FTP::new() may also be passed as key-value pairs.

  • You may also pass verbose for more descriptive output; by default, this is off.

• Return Value

  Perl::Download::FTP::Distribution object.

• Comments

  The method establishes an FTP connection to <host>, logs you in as an anonymous user, and changes directory to dir.

  Wrapper around Net::FTP object. You will get Net::FTP error messages at any point of failure. Uses FTP Passive mode.

  Note that the value for dir on a given CPAN FTP mirror is different from the value for dir one would use in downloading a Perl 5 core distribution tarball via Perl::Download::FTP.

ls()

• Purpose

  Identify all currently available tarballs of the CPAN distribution in question.

• Arguments

      @all_releases = $self->ls();

  None; all information needed is in the object.

• Return Value

  List of strings like:

      'Test-Smoke-1.53.tar.gz',
      'Test-Smoke-1.59.tar.gz',
          'Test-Smoke-1.6.tar.gz',
          'Test-Smoke-1.70.tar.gz',
      'Test-Smoke-1.71.tar.gz',

• Comment

  Results do not include versions which have been moved to BackCPAN.

get_latest_release()

• Purpose

  Download the latest release via FTP.

• Arguments

      $latest_release = $self->get_latest_release( {
          path            => '/path/to/download',
          verbose         => 1,
      } );

  Takes a hash reference with two possible elements: path and verbose. The value of path should be a string holding the path to the directory to which the tarball will be downloaded. If not provided, the tarball will be downloaded to the current working directory.

• Return Value

  Scalar holding path to download of tarball.

BUGS AND SUPPORT

Please report any bugs by mail to bug-Perl-Download-FTP@rt.cpan.org or through the web interface at http://rt.cpan.org.

ACKNOWLEDGEMENTS

Thanks for feedback from Chad Granum, Kent Fredric and David Golden in the perl.cpan.workers newsgroup.

AUTHOR

    James E Keenan
    CPAN ID: JKEENAN
    jkeenan@cpan.org
    http://thenceforward.net/perl

COPYRIGHT

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

The full text of the license can be found in the LICENSE file included with this module.

Copyright James E Keenan 2018. All rights reserved.

SEE ALSO

perl(1). Net::FTP(3). Test::RequiresInternet(3).