File Coverage

blib/lib/CPAN/ReleaseHistory.pm
Criterion Covered Total %
statement 7 9 77.7
branch n/a
condition n/a
subroutine 3 3 100.0
pod n/a
total 10 12 83.3


line stmt bran cond sub pod time code
1             package CPAN::ReleaseHistory;
2             $CPAN::ReleaseHistory::VERSION = '0.12';
3 2     2   32400 use 5.006;
  2         7  
  2         65  
4 2     2   22358 use Moo;
  2         28941  
  2         15  
5 2     2   5402 use MooX::Role::CachedURL 0.06;
  0            
  0            
6              
7             use CPAN::DistnameInfo;
8             use Carp;
9             use autodie qw(open);
10              
11             use CPAN::ReleaseHistory::Release;
12              
13             with 'MooX::Role::CachedURL';
14              
15             has '+url' =>
16             (
17             default => sub { return 'http://backpan.cpantesters.org/backpan-releases-by-dist-index.txt.gz' },
18             );
19              
20             has '+max_age' =>
21             (
22             default => sub { '1 day' },
23             );
24              
25              
26             sub release_iterator
27             {
28             my $self = shift;
29              
30             require CPAN::ReleaseHistory::ReleaseIterator;
31             return CPAN::ReleaseHistory::ReleaseIterator->new( history => $self, @_ );
32             }
33              
34             1;
35              
36             =head1 NAME
37              
38             CPAN::ReleaseHistory - information about all files ever released to CPAN
39              
40             =head1 SYNOPSIS
41              
42             use CPAN::ReleaseHistory 0.10;
43              
44             my $history = CPAN::ReleaseHistory->new();
45             my $iterator = $history->release_iterator();
46              
47             while (my $release = $iterator->next_release) {
48             print 'path = ', $release->path, "\n";
49             print 'dist = ', $release->distinfo->dist, "\n";
50             print 'time = ', $release->timestamp, "\n";
51             print 'size = ', $release->size, "\n";
52             }
53            
54             =head1 DESCRIPTION
55              
56             This module provides an iterator that can be used to look at every file
57             that has ever been released to CPAN, regardless of whether it is still on CPAN.
58              
59             The BackPAN index used was changed in release 0.10, which resulted in the caching
60             mechanism changing, so you should make sure you have at least version 0.10,
61             as shown in the SYNOPSIS above.
62              
63             The C<$release> returned by the C method on the iterator
64             is an instance of L. It has five methods:
65              
66             =over 4
67              
68             =item path
69              
70             the relative path of the release. For example C.
71              
72             =item distinfo
73              
74             an instance of L, which is constructed lazily.
75             Ie it is only created if you ask for it.
76              
77             =item timestamp
78              
79             An integer epoch-based timestamp.
80              
81             =item date
82              
83             An ISO-format date string (YYYY-MM-DD) for the timestamp in UTC
84             (ie the date used by PAUSE and CPAN, rather than the time of release
85             in your local timezone.
86              
87             =item size
88              
89             The number of bytes in the file.
90              
91             =back
92              
93             =head2 Be aware
94              
95             When iterating over CPAN's history, you'll find that most distribution names reveal
96             a clean release history. For example, JUERD did two releases of L,
97             which I then adopted:
98              
99             J/JU/JUERD/again-0.01.tar.gz
100             J/JU/JUERD/again-0.02.tar.gz
101             N/NE/NEILB/again-0.03.tar.gz
102             N/NE/NEILB/again-0.04.tar.gz
103             N/NE/NEILB/again-0.05.tar.gz
104              
105             But you will also discover that there are various 'anomalies' in the history of CPAN releases.
106             These are usually well in the past -- PAUSE and the related toolchains have evolved to
107             prevent most of these.
108             For example, here's the sequence of releases for distributions called 'enum':
109              
110             Z/ZE/ZENIN/enum-1.008.tar.gz
111             Z/ZE/ZENIN/enum-1.009.tar.gz
112             Z/ZE/ZENIN/enum-1.010.tar.gz
113             Z/ZE/ZENIN/enum-1.011.tar.gz
114             N/NJ/NJLEON/enum-0.02.tar.gz
115             Z/ZE/ZENIN/enum-1.013.tar.gz
116             Z/ZE/ZENIN/enum-1.014.tar.gz
117             Z/ZE/ZENIN/enum-1.015.tar.gz
118             Z/ZE/ZENIN/enum-1.016.tar.gz
119             R/RO/ROODE/enum-0.01.tar.gz
120             N/NE/NEILB/enum-1.016_01.tar.gz
121             N/NE/NEILB/enum-1.02.tar.gz
122             N/NE/NEILB/enum-1.03.tar.gz
123             N/NE/NEILB/enum-1.04.tar.gz
124             N/NE/NEILB/enum-1.05.tar.gz
125             N/NE/NEILB/enum-1.06.tar.gz
126              
127             The L module was first released by ZENIN, and I (NEILB) recently adopted it.
128             But you'll see that there have been two other releases of other modules (with similar aims).
129              
130             Depending on what you're trying to do, you might occasionally be surprised by the sequence
131             of version numbers and maintainers.
132              
133             =head1 METHODS
134              
135             At the moment there is only one method, to create a release iterator.
136             Other methods will be added as required / requested.
137              
138             =head2 release_iterator()
139              
140             See the SYNOPSIS.
141              
142             This supports one optional argument, C, which if true says that the
143             iterator should only return releases where the dist name and author's PAUSE id
144             could be found:
145              
146             my $iterator = CPAN::ReleaseHistory->new()->release_iterator(
147             well_formed => 1
148             );
149              
150             This saves you from having to write code like the following:
151              
152             while (my $release = $iterator->next_release) {
153             next unless defined($release->distinfo);
154             next unless defined($release->distinfo->dist);
155             next unless defined($release->distinfo->cpanid);
156             ...
157             }
158              
159             =head1 SEE ALSO
160              
161             L - creates an SQLite database of the BackPAN index,
162             and provides an interface for querying it.
163              
164             L - the BackPAN site
165             from where this module grabs the index.
166              
167             =head1 REPOSITORY
168              
169             L
170              
171             =head1 AUTHOR
172              
173             Neil Bowers Eneilb@cpan.orgE
174              
175             =head1 COPYRIGHT AND LICENSE
176              
177             This software is copyright (c) 2014 by Neil Bowers .
178              
179             This is free software; you can redistribute it and/or modify it under
180             the same terms as the Perl 5 programming language system itself.
181              
182             =cut
183