CPAN::Releases::Latest(3pm)

1CPAN::Releases::Latest(U3s)er Contributed Perl DocumentatCiPoAnN::Releases::Latest(3)
2
3
4

NAME

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

SYNOPSIS

10        use CPAN::Releases::Latest;
11
12        my $latest   = CPAN::Releases::Latest->new(max_age => '1 day');
13        my $iterator = $latest->release_iterator();
14
15        while (my $release = $iterator->next_release) {
16            printf "%s path=%s  time=%d  size=%d\n",
17                   $release->distname,
18                   $release->path,
19                   $release->timestamp,
20                   $release->size;
21        }
22

DESCRIPTION

24       This module constructs a list of all dists on CPAN, by default using
25       the MetaCPAN API.  The generated index is cached locally.  It will let
26       you iterate over the index, either release by release, or distribution
27       by distribution.
28
29       See below for details of the two iterators you can instantiate.
30
31       Note: this is very much an alpha release; all things may change.
32
33       When you instantiate this class, you can specify the "max_age" of the
34       generated index. You can specify the age using any of the expressions
35       supported by Time::Duration::Parse:
36
37        5 minutes
38        1 hour and 30 minutes
39        2d
40        3600
41
42       If no units are given, it will be interpreted as a number of seconds.
43       The default for max age is 1 day.
44
45       If you already have a cached copy of the index, and it is less than the
46       specified age, then we'll use your cached copy and not even check with
47       MetaCPAN.
48
49   distribution_iterator
50       The "distribution_iterator" method returns an iterator which will
51       process the index dist by dist:
52
53        my $latest   = CPAN::Releases::Latest->new();
54        my $iterator = $latest->distribution_iterator();
55
56        while (my $dist = $iterator->next_distribution) {
57           print $dist->distname, "\n";
58           process_release($dist->release);
59           process_release($dist->developer_release);
60        }
61
62       The iterator returns instances of CPAN::Releases::Latest::Distribution,
63       or "undef" when the index has been exhausted.  The distribution object
64       has three attributes:
65
66       •   distname: the distribution name as determined by CPAN::DistnameInfo
67
68       •   release: a release object for the latest non-developer release, or
69           "undef"
70
71       •   developer_release: a release object for the latest developer
72           release that is more recent than the latest non-developer release,
73           or "undef"
74
75       The release objects are instances of CPAN::Releases::Latest::Release,
76       which are described in the next section, below.
77
78   release_iterator
79       The "release_iterator" method returns an iterator which will process
80       the index release by release. See the example in the SYNOPSIS.
81
82       You will see the releases ordered distribution by distribution.  For a
83       given distribution you'll first see the latest non-developer release,
84       if there is one; if the most recent release for the distribution is a
85       developer release, then you'll see that.  So for any dist you'll see at
86       most two releases, and the developer release will always come second.
87
88       The release objects are instances of CPAN::Releases::Latest::Release,
89       which have the following attributes:
90
91       •   distname: the distribution name as determined by CPAN::DistnameInfo
92
93       •   path: the partial path for the release tarball (eg
94           "N/NE/NEILB/enum-1.05.tar.gz")
95
96       •   timestamp: an epoch-based timestamp for when the tarball was
97           uploaded to PAUSE.
98
99       •   size: the size of the release tarball, in bytes.
100
101       •   distinfo: an instance of CPAN::DistnameInfo, which is constructed
102           lazily.
103

Data source

105       By default the locally cached index is generated using information
106       requested from MetaCPAN, using MetaCPAN::Client. The plugin which does
107       this is CPAN::Releases::Latest::Source::MetaCPAN. You can explicitly
108       specify the source when calling the constructor:
109
110        $latest = CPAN::Releases::Latest->new( source => 'MetaCPAN' );
111
112       You can use a different source for the data, by providing your own
113       plugin, which must live in the "CPAN::Releases::Latest::Source"
114       namespace.
115
116       The plugin must return a hashref that has the following structure:
117
118        {
119          release => {
120
121            'Graph' => {
122               path => 'J/JH/JHI/Graph-0.96.tar.gz',
123               time => 1369483123,
124               size => 147629,
125            },
126
127          },
128
129          developer => {
130
131            'Graph' => {
132               path => 'N/NE/NEILB/Graph-0.96_01.tar.gz',
133               time => 1394362358,
134               size => 147335,
135            },
136
137          }
138
139        }
140
141       At the moment this isn't enforced, but a future version will croak if
142       the source doesn't return the right structure.
143

REPOSITORY

152       <https://github.com/neilb/CPAN-Releases-Latest>
153

AUTHOR

155       Neil Bowers <neilb@cpan.org>
156

COPYRIGHT AND LICENSE

158       This software is copyright (c) 2014 by Neil Bowers <neilb@cpan.org>.
159
160       This is free software; you can redistribute it and/or modify it under
161       the same terms as the Perl 5 programming language system itself.
162
163
164
165perl v5.38.0                      2023-07-20         CPAN::Releases::Latest(3)