Parse::CPAN::Packages(3pm)

1Parse::CPAN::Packages(3U)ser Contributed Perl DocumentatiPoanrse::CPAN::Packages(3)
2
3
4

NAME

6       Parse::CPAN::Packages - Parse 02packages.details.txt.gz
7

SYNOPSIS

9         use Parse::CPAN::Packages;
10
11         # must have downloaded
12         my $p = Parse::CPAN::Packages->new("02packages.details.txt.gz");
13         # either a filename as above or pass in the contents of the file
14         # (uncompressed)
15         my $p = Parse::CPAN::Packages->new($packages_details_contents);
16
17         my $m = $p->package("Acme::Colour");
18         # $m is a Parse::CPAN::Packages::Package object
19         print $m->package, "\n";   # Acme::Colour
20         print $m->version, "\n";   # 1.00
21
22         my $d = $m->distribution();
23         # $d is a Parse::CPAN::Packages::Distribution object
24         print $d->prefix, "\n";    # L/LB/LBROCARD/Acme-Colour-1.00.tar.gz
25         print $d->dist, "\n";      # Acme-Colour
26         print $d->version, "\n";   # 1.00
27         print $d->maturity, "\n";  # released
28         print $d->filename, "\n";  # Acme-Colour-1.00.tar.gz
29         print $d->cpanid, "\n";    # LBROCARD
30         print $d->distvname, "\n"; # Acme-Colour-1.00
31
32         # all the package objects
33         my @packages = $p->packages;
34
35         # all the distribution objects
36         my @distributions = $p->distributions;
37
38         # the latest distribution
39         $d = $p->latest_distribution("Acme-Colour");
40         is($d->prefix, "L/LB/LBROCARD/Acme-Colour-1.00.tar.gz");
41         is($d->version, "1.00");
42
43         # all the latest distributions
44         my @distributions = $p->latest_distributions;
45

DESCRIPTION

47       The Comprehensive Perl Archive Network (CPAN) is a very useful
48       collection of Perl code. It has several indices of the files that it
49       hosts, including a file named "02packages.details.txt.gz" in the
50       "modules" directory. This file contains lots of useful information and
51       this module provides a simple interface to the data contained within.
52
53       In a future release Parse::CPAN::Packages::Package and
54       Parse::CPAN::Packages::Distribution might have more information.
55
56   Methods
57       new Creates a new instance from a details file.
58
59           The constructor can be passed either the path to the
60           "02packages.details.txt.gz" file, a path to an ungzipped version of
61           this file, or a scalar containing the entire uncompressed contents
62           of the file.
63
64           Note that this module does not concern itself with downloading this
65           file. You should do this yourself.  For example:
66
67              use LWP::Simple qw(get);
68              my $data = get("http://www.cpan.org/modules/02packages.details.txt.gz");
69              my $p = Parse::CPAN::Packages->new($data);
70
71       package($packagename)
72           Returns a "Parse::CPAN::Packages::Package" that represents the
73           named package.
74
75             my $p = Parse::CPAN::Distribution->new($gzfilename);
76             my $package = $p->package("Acme::Colour");
77
78       packages()
79           Returns a list of Parse::CPAN::Packages::Package objects
80           representing all the packages that were extracted from the file.
81
82       package_count()
83           Returns the numebr of packages stored.
84
85       distribution($filename)
86           Returns a Parse::CPAN::Distribution that represents the filename
87           passed:
88
89             my $p = Parse::CPAN::Distribution->new($gzfilename);
90             my $dist = $p->distribution('L/LB/LBROCARD/Acme-Colour-1.00.tar.gz');
91
92       distributions()
93           Returns a list of Parse::CPAN::Distribution objects representing
94           all the known distributions.
95
96       distribution_count()
97           Returns the number of distributions stored.
98
99       latest_distribution($distname)
100           Returns the "Parse::CPAN::Distribution" that represents the latest
101           distribution for the named disribution passed, that is to say it
102           returns the distribution that has the highest version number (as
103           determined by version.pm or number comparison if that fails):
104
105             my $p = Parse::CPAN::Distribution->new($gzfilename);
106             my $dist = $p->distribution('Acme-Color');
107
108       latest_distrbutions()
109           Returns a list of Parse::CPAN::Distribution objects representing
110           all the latest distributions.
111
112       latest_distribution_count()
113           Returns the number of distributions stored.
114
115   Preamble Methods
116       These methods return the information from the preamble at the start of
117       the file. They return undef if for any reason no matching preamble line
118       was found.
119
120       file()
121       url()
122       description()
123       columns()
124       intended_for()
125       written_by()
126       line_count()
127       last_updated()
128
129   Addtional Methods
130       These are additional methods that you may find useful.
131
132       parse($filename)
133           Parses the filename.  Works in a similar fashion to the the
134           constructor (i.e. you can pass it a filename for a
135           compressed/1uncompressed file, a uncompressed scalar containing the
136           file.  You can also pass nothing to indicate to load the compressed
137           file from the current working directory.)
138
139           Note that each time this function is run the packages and
140           distribtions found will be "added" to the current list of packages.
141
142       add_quick($package_name, $package_version, $prefix)
143           Quick way of adding a new package and distribution.
144
145       add_package($package_obj)
146           Adds a package.  Note that you'll probably want to add the
147           corrisponding distribution for that package too (it's not done
148           automatically.)
149
150       add_distribution($distribution_obj)
151           Adds a distribution.  Note that you'll probably want to add the
152           corresponding packages for that distribution too (it's not done
153           automatically.)
154
155       distribution_from_prefix($prefix)
156           Returns a distribution given a prefix.
157
158       latest_distributions
159           Returns all the latest distributions:
160
161             my @distributions = $p->latest_distributions;
162

AUTHOR

164       Leon Brocard <acme@astray.com>
165

COPYRIGHT

167       Copyright (C) 2004-9, Leon Brocard
168

LICENSE

170       This module is free software; you can redistribute it or modify it
171       under the same terms as Perl itself.
172

BUGS

174       This module leaks memory as packages hold distributions and
175       distributions hold packages.  No attempt has been made to fix this as
176       it's not anticpated that this will be used in long running programs
177       that will dispose of the objects once created.
178
179       The old interface for "new" where if you passed no arguments it would
180       look for a "02packages.details.txt.gz" in your current directory is no
181       longer supported.
182

TODO

184       delete_* methods.  merge_into method.  Documentation for other modules.
185