/ 
Perl-Download-FTP-0.05
River stage one • 1 direct dependent • 1 total dependent
/ Perl::Download::FTP

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',
    path            => '/path/to/download',
    verbose         => 1,
} );

$specific_release = $self->get_specific_release( {
    release         => 'perl-5.27.2.tar.xz',
    path            => '/path/to/download',
} );

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
dev_or_rc

      Defaults to dev. Selecting dev_or_fc will return any release which is either development|dev or rc.

  • 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,
} );

    Possible values for compression and type are the same as for list_releases().

  • Return Value

    Scalar holding path to download of tarball.

get_specific_release()

  • Purpose

    Download a specific release via FTP.

  • Arguments

    $specific_release = $self->get_specific_release( {
    release         => 'perl-5.27.2.tar.xz',
    path            => '/path/to/download',
} );

  • 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).