NAME

Perl::Download::FTP - Identify Perl releases and download the most recent via FTP

SYNOPSIS

    use Perl::Download::FTP;

    $self = Perl::Download::FTP->new( {
        host        => 'ftp.cpan.org',
        dir         => '/pub/CPAN/src/5.0',
        verbose     => 1,
    } );

    @all_releases = $self->ls();

    $classified_releases = $self->classify_releases();

    @releases = $self->list_releases( {
        type            => 'production',
        compression     => 'gz',
    } );

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

DESCRIPTION

This library provides (a) methods for obtaining a list of all Perl 5 releases which are available for FTP download; and (b) a method for obtaining the most recent release.

Compression Formats

Perl releases have, over time, used three different compression formats: gz, bz2 and xz. gz is the one that has been used in every production, development and release candidate release, so that is the default value used herein. All three compression formats are available for use herein.

Testing

This library can only be truly tested by attempting live FTP connections and downloads of Perl 5 source code tarballs. 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 constructor.

• Arguments

      $self = Perl::Download::FTP->new();
  
      $self = Perl::Download::FTP->new( {
          host        => 'ftp.cpan.org',
          dir         => '/pub/CPAN/src/5.0',
          verbose     => 1,
      } );
  
      $self = Perl::Download::FTP->new( {
          host        => 'ftp.cpan.org',
          dir         => '/pub/CPAN/src/5.0',
          Timeout     => 5,
      } );

  Takes a hash reference with, typically, two elements: host and dir. Any options which can be passed to Net::FTP::new() may also be passed as key-value pairs. When no argument is provided, 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/.) You may also pass verbose for more descriptive output; by default, this is off.

• Return Value

  Perl::Download::FTP object.

• Comment

  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.

ls()

• Purpose

  Identify all Perl releases.

• Arguments

      @all_releases = $self->ls();

  Returns list of all Perl core tarballs on the FTP host.

      @all_gzipped_releases = $self->ls('gz');

  Returns list of only those all tarballs on the FTP host which are compressed in .gz format. Also available (in separate calls): bz2, xz.

• Return Value

  List of strings like:

      "perl-5.10.0-RC2.tar.gz",
      "perl-5.10.0.tar.gz",
      "perl-5.26.0.tar.gz",
      "perl-5.26.1-RC1.tar.gz",
      "perl-5.27.0.tar.gz",
      "perl-5.6.0.tar.gz",
      "perl-5.6.1-TRIAL1.tar.gz",
      "perl-5.6.1-TRIAL2.tar.gz",
      "perl-5.6.1-TRIAL3.tar.gz",
      "perl5.003_07.tar.gz",
      "perl5.004.tar.gz",
      "perl5.004_01.tar.gz",
      "perl5.005.tar.gz",
      "perl5.005_01.tar.gz",
  
      "perl-5.10.1.tar.bz2",
      "perl-5.12.2-RC1.tar.bz2",
      "perl-5.26.1-RC1.tar.bz2",
      "perl-5.27.0.tar.bz2",
      "perl-5.8.9.tar.bz2",
  
      "perl-5.21.10.tar.xz",
      "perl-5.21.6.tar.xz",
      "perl-5.22.0-RC1.tar.xz",
      "perl-5.22.0.tar.xz",
      "perl-5.22.1-RC4.tar.xz",
      "perl-5.26.1.tar.xz",
      "perl-5.27.2.tar.xz",

classify_releases()

• Purpose

  Categorize releases as production, development or RC (release candidate).

• Arguments

  None. Works on data stored in object by ls().

• Return Value

  Hash reference.

list_releases()

• Purpose

  List all releases for a specified compression format and release type, sorted in reverse logical order.

• Arguments

      @releases = $self->list_releases( {
          type            => 'production',
          compression     => 'gz',
      } );

  Takes a hash reference with, typically two elements:

  • compression

    Available values:

        gz      bz2     xz

    Defaults to gz.

  • type

    Available values:

        production      prod
        development     dev
        rc

    Defaults to dev.

• Return Value

  List of strings naming Perl release tarballs for the specified compression format and type. The list is sorted in reverse logical order, i.e., the newest production release will be the first item in the list and the oldest will be the last. So, for instance, the list of development releases in gz format will start with something like:

      perl-5.27.5.tar.gz
      perl-5.27.4.tar.gz
      perl-5.27.3.tar.gz

  and end with:

      perl5.004_02.tar.gz
      perl5.004_01.tar.gz
      perl5.003_07.tar.gz

get_latest_release()

• Purpose

  Download the latest release via FTP.

• Arguments

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

• 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 2017. All rights reserved.

SEE ALSO

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

cpanm Perl::Download::FTP

perl -MCPAN -e shell
install Perl::Download::FTP