NAME

CPAN::ReleaseHistory - information about all files ever released to CPAN

SYNOPSIS

use CPAN::ReleaseHistory 0.10;

my $history  = CPAN::ReleaseHistory->new();
my $iterator = $history->release_iterator();

while (my $release = $iterator->next_release) {
  print 'path = ', $release->path,           "\n";
  print 'dist = ', $release->distinfo->dist, "\n";
  print 'time = ', $release->timestamp,      "\n";
  print 'size = ', $release->size,           "\n";
}

DESCRIPTION

This module provides an iterator that can be used to look at every file that has ever been released to CPAN, regardless of whether it is still on CPAN.

The BackPAN index used was changed in release 0.10, which resulted in the caching mechanism changing, so you should make sure you have at least version 0.10, as shown in the SYNOPSIS above.

The $release returned by the next_release() method on the iterator is an instance of CPAN::ReleaseHistory::Release. It has five methods:

path

the relative path of the release. For example N/NE/NEILB/again-0.05.tar.gz.

distinfo

an instance of CPAN::DistnameInfo, which is constructed lazily. Ie it is only created if you ask for it.

timestamp

An integer epoch-based timestamp.

date

An ISO-format date string (YYYY-MM-DD) for the timestamp in UTC (ie the date used by PAUSE and CPAN, rather than the time of release in your local timezone.

size

The number of bytes in the file.

Be aware

When iterating over CPAN's history, you'll find that most distribution names reveal a clean release history. For example, JUERD did two releases of again, which I then adopted:

J/JU/JUERD/again-0.01.tar.gz
J/JU/JUERD/again-0.02.tar.gz
N/NE/NEILB/again-0.03.tar.gz
N/NE/NEILB/again-0.04.tar.gz
N/NE/NEILB/again-0.05.tar.gz

But you will also discover that there are various 'anomalies' in the history of CPAN releases. These are usually well in the past -- PAUSE and the related toolchains have evolved to prevent most of these. For example, here's the sequence of releases for distributions called 'enum':

Z/ZE/ZENIN/enum-1.008.tar.gz
Z/ZE/ZENIN/enum-1.009.tar.gz
Z/ZE/ZENIN/enum-1.010.tar.gz
Z/ZE/ZENIN/enum-1.011.tar.gz
N/NJ/NJLEON/enum-0.02.tar.gz
Z/ZE/ZENIN/enum-1.013.tar.gz
Z/ZE/ZENIN/enum-1.014.tar.gz
Z/ZE/ZENIN/enum-1.015.tar.gz
Z/ZE/ZENIN/enum-1.016.tar.gz
R/RO/ROODE/enum-0.01.tar.gz
N/NE/NEILB/enum-1.016_01.tar.gz
N/NE/NEILB/enum-1.02.tar.gz
N/NE/NEILB/enum-1.03.tar.gz
N/NE/NEILB/enum-1.04.tar.gz
N/NE/NEILB/enum-1.05.tar.gz
N/NE/NEILB/enum-1.06.tar.gz

The enum module was first released by ZENIN, and I (NEILB) recently adopted it. But you'll see that there have been two other releases of other modules (with similar aims).

Depending on what you're trying to do, you might occasionally be surprised by the sequence of version numbers and maintainers.

METHODS

At the moment there is only one method, to create a release iterator. Other methods will be added as required / requested.

release_iterator()

See the SYNOPSIS.

This supports one optional argument, well_formed, which if true says that the iterator should only return releases where the dist name and author's PAUSE id could be found:

my $iterator = CPAN::ReleaseHistory->new()->release_iterator(
                   well_formed => 1
               );

This saves you from having to write code like the following:

while (my $release = $iterator->next_release) {
   next unless defined($release->distinfo);
   next unless defined($release->distinfo->dist);
   next unless defined($release->distinfo->cpanid);
   ...
}

SEE ALSO

BackPAN::Index - creates an SQLite database of the BackPAN index, and provides an interface for querying it.

backpan.cpantesters.org - the BackPAN site from where this module grabs the index.

REPOSITORY

https://github.com/neilbowers/CPAN-ReleaseHistory

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.

cpanm CPAN::ReleaseHistory

perl -MCPAN -e shell
install CPAN::ReleaseHistory