CPAN::R...:Latest(3)

📦
version 0.08 · 2 versions
, in fedora 43

💖 CPAN::Releases::Latest 💖

okay bestie, welcome to CPAN::Releases::Latest — this is a perl manual page from the User Contributed Perl Documentation collection, and it's genuinely iconic. what it does? it finds the latest release(s) of all dists on CPAN, including dev releases 🦋

✨ NAME ✨

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

✨ SYNOPSIS ✨

the vibe, in code:

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 ✨

so basically 💅 this module constructs a list of all dists on CPAN, and by default it does that using the MetaCPAN API. the generated index gets cached locally. then it lets you iterate over that index — either release by release, or distribution by distribution. main character energy honestly.

scroll down for the deets on the two iterators you can instantiate, bestie 🫶

⚠️ note: this is very much an alpha release; all things may change. no cap, it said it, not me 😭

when you instantiate this class, you can specify the max_age of the generated index. and you can specify that 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'll be interpreted as a number of seconds. the default for max age is 1 day.

and here's the slay part: if you already have a cached copy of the index, and it's less than the specified age, then we'll use your cached copy and not even check with MetaCPAN. efficient queen 💅

🌸 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. and that distribution object has three attributes, periodt:

  • 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 get 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 up in the SYNOPSIS 👑

you'll 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, and they 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 — but it has to live in the CPAN::Releases::Latest::Source namespace, bestie, those are the rules 🎀

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. so like, get it right the first time 💀

✨ SEE ALSO ✨

  • CPAN::ReleaseHistory — provides a similar iterator, but for all releases ever made to CPAN, even those that are no longer on CPAN. the archive girly 🗄️
  • BackPAN::Index — another way to get information about all releases ever made to CPAN. lowkey another route to the same lore 🔥

✨ REPOSITORY ✨

https://github.com/neilb/CPAN-Releases-Latest — go star it bestie ⭐

✨ AUTHOR ✨

Neil Bowers <neilb@cpan.org> 👑

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. fr fr, go wild 🌈

and that's a wrap, bestie — this page shipped as part of perl v5.42.0, dated 2025-07-25. go iterate over some dists, you absolute icon 💅✨

📦 where this page comes from