NAME

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

SYNOPSIS

  use CPAN::ReleaseHistory 0.02;

  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

NOTE: this is very much an alpha release. Any and all feedback appreciated.

The internal caching format changed in 0.02, so you should make sure you have at least 0.02, using the use line shown in the SYNOPSIS.

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 $release returned by the next_release() method on the iterator is an instance of CPAN::ReleaseHistory::Release. It has four 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.

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);
    ...
 }

NOTES

At the moment this module will use up a lot of memory: it grabs the remote BackPAN index, extracts the data it needs into memory, sorts it, then writes it to the local cache. If this is a problem then I'll look at another way of doing it. If it's a problem for you, then you should look at BackPAN::Index.

SEE ALSO

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

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