/ 
CPAN-Releases-Latest-0.08
River stage zero No dependents
/ CPAN::Releases::Latest

NAME

CPAN::Releases::Latest - find latest release(s) of all dists on CPAN, including dev releases

SYNOPSIS

use CPAN::Releases::Latest;

my $latest   = CPAN::Releases::Latest->new(max_age => '1 day');
my $iterator = $latest->release_iterator();

while (my $release = $iterator->next_release) {
    printf "%s path=%s  time=%d  size=%d\n",
           $release->distname,
           $release->path,
           $release->timestamp,
           $release->size;
}

DESCRIPTION

This module constructs a list of all dists on CPAN, by default using the MetaCPAN API. The generated index is cached locally. It will let you iterate over the index, either release by release, or distribution by distribution.

See below for details of the two iterators you can instantiate.

Note: this is very much an alpha release; all things may change.

When you instantiate this class, you can specify the max_age of the generated index. You can specify the age using any of the expressions supported by Time::Duration::Parse:

5 minutes
1 hour and 30 minutes
2d
3600

If no units are given, it will be interpreted as a number of seconds. The default for max age is 1 day.

If you already have a cached copy of the index, and it is less than the specified age, then we'll use your cached copy and not even check with MetaCPAN.

distribution_iterator

The distribution_iterator method returns an iterator which will process the index dist by dist:

my $latest   = CPAN::Releases::Latest->new();
my $iterator = $latest->distribution_iterator();

while (my $dist = $iterator->next_distribution) {
   print $dist->distname, "\n";
   process_release($dist->release);
   process_release($dist->developer_release);
}

The iterator returns instances of CPAN::Releases::Latest::Distribution, or undef when the index has been exhausted. The distribution object has three attributes:

  • distname: the distribution name as determined by CPAN::DistnameInfo

  • release: a release object for the latest non-developer release, or undef

  • developer_release: a release object for the latest developer release that is more recent than the latest non-developer release, or undef

The release objects are instances of CPAN::Releases::Latest::Release, which are described in the next section, below.

release_iterator

The release_iterator method returns an iterator which will process the index release by release. See the example in the SYNOPSIS.

You will see the releases ordered distribution by distribution. For a given distribution you'll first see the latest non-developer release, if there is one; if the most recent release for the distribution is a developer release, then you'll see that. So for any dist you'll see at most two releases, and the developer release will always come second.

The release objects are instances of CPAN::Releases::Latest::Release, which have the following attributes:

  • distname: the distribution name as determined by CPAN::DistnameInfo

  • path: the partial path for the release tarball (eg N/NE/NEILB/enum-1.05.tar.gz)

  • timestamp: an epoch-based timestamp for when the tarball was uploaded to PAUSE.

  • size: the size of the release tarball, in bytes.

  • distinfo: an instance of CPAN::DistnameInfo, which is constructed lazily.

Data source

By default the locally cached index is generated using information requested from MetaCPAN, using MetaCPAN::Client. The plugin which does this is CPAN::Releases::Latest::Source::MetaCPAN. You can explicitly specify the source when calling the constructor:

$latest = CPAN::Releases::Latest->new( source => 'MetaCPAN' );

You can use a different source for the data, by providing your own plugin, which must live in the CPAN::Releases::Latest::Source namespace.

The plugin must return a hashref that has the following structure:

{
  release => {

    'Graph' => {
       path => 'J/JH/JHI/Graph-0.96.tar.gz',
       time => 1369483123,
       size => 147629,
    },

  },

  developer => {

    'Graph' => {
       path => 'N/NE/NEILB/Graph-0.96_01.tar.gz',
       time => 1394362358,
       size => 147335,
    },

  }

}

At the moment this isn't enforced, but a future version will croak if the source doesn't return the right structure.

SEE ALSO

CPAN::ReleaseHistory provides a similar iterator, but for all releases ever made to CPAN, even those that are no longer on CPAN.

BackPAN::Index is another way to get information about all releases ever made to CPAN.

REPOSITORY

https://github.com/neilb/CPAN-Releases-Latest

AUTHOR

Neil Bowers <neilb@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Neil Bowers <neilb@cpan.org>.

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