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           If you have a configured CPAN, then there's usually already a
72           cached file available:
73
74              use CPAN;
75              $CPAN::Be_Silent = 1;
76              CPAN::HandleConfig->load;
77              my $file = $CPAN::Config->{keep_source_where} . "/modules/02packages.details.txt.gz";
78              my $p = Parse::CPAN::Packages->new($file);
79
80       package($packagename)
81           Returns a "Parse::CPAN::Packages::Package" that represents the
82           named package.
83
84             my $p = Parse::CPAN::Packages->new($gzfilename);
85             my $package = $p->package("Acme::Colour");
86
87       packages()
88           Returns a list of Parse::CPAN::Packages::Package objects
89           representing all the packages that were extracted from the file.
90
91       package_count()
92           Returns the number of packages stored.
93
94       distribution($filename)
95           Returns a Parse::CPAN::Packages::Distribution object that
96           represents the filename passed:
97
98             my $p = Parse::CPAN::Packages->new($gzfilename);
99             my $dist = $p->distribution('L/LB/LBROCARD/Acme-Colour-1.00.tar.gz');
100
101       distributions()
102           Returns a list of Parse::CPAN::Packages::Distribution objects
103           representing all the known distributions.
104
105       distribution_count()
106           Returns the number of distributions stored.
107
108       latest_distribution($distname)
109           Returns the "Parse::CPAN::Packages::Distribution" object that
110           represents the latest distribution for the named disribution
111           passed, that is to say it returns the distribution that has the
112           highest version number (as determined by version.pm or number
113           comparison if that fails):
114
115             my $p = Parse::CPAN::Packages->new($gzfilename);
116             my $dist = $p->distribution('Acme-Color');
117
118       latest_distrbutions()
119           Returns a list of Parse::CPAN::Packages::Distribution objects
120           representing all the latest distributions.
121
122       latest_distribution_count()
123           Returns the number of distributions stored.
124
125   Preamble Methods
126       These methods return the information from the preamble at the start of
127       the file. They return undef if for any reason no matching preamble line
128       was found.
129
130       file()
131       url()
132       description()
133       columns()
134       intended_for()
135       written_by()
136       line_count()
137       last_updated()
138
139   Addtional Methods
140       These are additional methods that you may find useful.
141
142       parse($filename)
143           Parses the filename.  Works in a similar fashion to the the
144           constructor (i.e. you can pass it a filename for a
145           compressed/1uncompressed file, a uncompressed scalar containing the
146           file.  You can also pass nothing to indicate to load the compressed
147           file from the current working directory.)
148
149           Note that each time this function is run the packages and
150           distribtions found will be "added" to the current list of packages.
151
152       add_quick($package_name, $package_version, $prefix)
153           Quick way of adding a new package and distribution.
154
155       add_package($package_obj)
156           Adds a package.  Note that you'll probably want to add the
157           corrisponding distribution for that package too (it's not done
158           automatically.)
159
160       add_distribution($distribution_obj)
161           Adds a distribution.  Note that you'll probably want to add the
162           corresponding packages for that distribution too (it's not done
163           automatically.)
164
165       distribution_from_prefix($prefix)
166           Returns a distribution given a prefix.
167
168       latest_distributions
169           Returns all the latest distributions:
170
171             my @distributions = $p->latest_distributions;
172

AUTHOR

174       Leon Brocard <acme@astray.com>
175

COPYRIGHT

177       Copyright (C) 2004-9, Leon Brocard
178

LICENSE

180       This module is free software; you can redistribute it or modify it
181       under the same terms as Perl itself.
182

BUGS

184       This module leaks memory as packages hold distributions and
185       distributions hold packages.  No attempt has been made to fix this as
186       it's not anticpated that this will be used in long running programs
187       that will dispose of the objects once created.
188
189       The old interface for "new" where if you passed no arguments it would
190       look for a "02packages.details.txt.gz" in your current directory is no
191       longer supported.
192

TODO

194       delete_* methods.  merge_into method.  Documentation for other modules.
195