CPAN::PackageDetails - Create or read 02packages.details.txt.gz
use CPAN::PackageDetails;
# read an existing file #####################
my $package_details = CPAN::PackageDetails->read( $filename );
my $count = $package_details->count;
my $records = $package_details->entries;
foreach my $record ( @$records )
{
# See CPAN::PackageDetails::Entry too
print join "\t", map { $record->$_() } ('package name', 'version', 'path')
print join "\t", map { $record->$_() } $package_details->columns_as_list;
}
# not yet implemented, but would be really, really cool eh?
my $records = $package_details->entries(
logic => 'OR', # but that could be AND, which is the default
package => qr/^Test::/, # or a string
author => 'OVID', # case insenstive
path => qr/foo/,
);
# create a new file #####################
my $package_details = CPAN::PackageDetails->new(
file => "02packages.details.txt",
url => "http://example.com/MyCPAN/modules/02packages.details.txt",
description => "Package names for my private CPAN",
columns => "package name, version, path",
intended_for => "My private CPAN",
written_by => "$0 using CPAN::PackageDetails $CPAN::PackageDetails::VERSION",
last_updated => CPAN::PackageDetails->format_date,
allow_packages_only_once => 1,
);
$package_details->add_entry(
package_name => $package,
version => $package->VERSION;
path => $path,
);
print "About to write ", $package_details->count, " entries\n";
$package_details->write_file( $file );
# OR ...
$package_details->write_fh( \*STDOUT )
CPAN uses an index file, 02packages.details.txt.gz, to map package names to distribution files. Using this module, you can get a data structure of that file, or create your own.
There are two parts to the 02packages.details.txt.gz: a header and the index. This module uses a top-level CPAN::PackageDetails object to control everything and comprise an CPAN::PackageDetails::Header and CPAN::PackageDetails::Entries object. The CPAN::PackageDetails::Entries object is a collection of CPAN::PackageDetails::Entry objects.
For the most common uses, you don't need to worry about the insides of what class is doing what. You'll call most of the methods on the top-level CPAN::PackageDetails object and it will make sure that it gets to the right place.
These methods are in the top-level object, and there are more methods for this class in the sections that cover the Header, Entries, and Entry objects.
Create a new 02packages.details.txt.gz file. The default_headers method shows you which values you can pass to new. For instance:
my $package_details = CPAN::PackageDetails->new(
url => $url,
columns => 'author, package name, version, path',
)
If you specify the allow_packages_only_once option with a true value and you try to add that package twice, the object will die. See add_entry.
Sets up the object. new calls this automatically for you.
Returns the hash of header fields and their default values:
file "02packages.details.txt"
url "http://example.com/MyCPAN/modules/02packages.details.txt"
description "Package names for my private CPAN"
columns "package name, version, path"
intended_for "My private CPAN"
written_by "$0 using CPAN::PackageDetails $CPAN::PackageDetails::VERSION"
last_updated format_date()
In the header, these fields show up with the underscores turned into hyphens, and the letters at the beginning or after a hyphen are uppercase.
Read an existing 02packages.details.txt.gz file.
While parsing, it modifies the field names to map them to Perly identifiers. The field is lowercased, and then hyphens become underscores. For instance:
Written-By ---> written_by
Returns the original file path for objects created through the read method.
Formats the object as a string and writes it to a temporary file and gzips the output. When everything is complete, it renames the temporary file to its final name.
write_file carps and returns nothing if you pass it no arguments, if it cannot open OUTPUT_FILE for writing, or if it cannot rename the file.
Formats the object as a string and writes it to FILEHANDLE
This method takes an existing 02packages.details.txt.gz named in FILE and the the CPAN root at CPAN_PATH (to append to the relative paths in the index), then checks the file for several things:
1. That there are entries in the file
2. The number of entries matches those declared in the Line-Count header
3. All paths listed in the file exist under CPAN_PATH
4. All distributions under CPAN_PATH have an entry (not counting older versions)
If any of these checks fail, check_file croaks with a hash reference with these keys:
# present in every error object
filename the FILE you passed in
cpan_path the CPAN_PATH you passed in
cwd the current working directory
error_count
# if FILE is missing
missing_file exists and true if FILE doesn't exist
# if the entry count in the file is wrong
# that is, the actual line count and header disagree
entry_count_mismatch true
line_count the line count declared in the header
entry_count the actual count
# if some distros in CPAN_HOME are missing in FILE
missing_in_file anonymous array of missing paths
# if some entries in FILE are missing the file in CPAN_HOME
missing_in_repo anonymous array of missing paths
Given an object and a CPAN_PATH, return an anonymous array of the distributions in the object that are not in CPAN_PATH. That is, complain when the object has extra distributions.
check_file calls this for you and adds the result to its error output.
Given an object and a CPAN_PATH, return an anonymous array of the distributions in CPAN_PATH that do not show up in the object. That is, complain when the object doesn't have all the dists.
check_file calls this for you and adds the result to its error output.
Returns the class that CPAN::PackageDetails uses to create the header object.
Returns the header object.
Entries are the collection of the items describing the package details. It comprises all of the Entry object.
Returns the class to use for the Entries object.
To use a different Entries class, tell new which class you want to use by passing the entries_class option:
CPAN::PackageDetails->new(
...,
entries_class => $class,
);
Note that you are responsible for loading the right class yourself.
Returns the number of entries.
This dispatches to the count in CPAN::PackageDetails::Entries. These are the same:
$package_details->count;
$package_details->entries->count;
Returns the entries object.
Returns the class to use for each Entry object.
To use a different Entry class, tell new which class you want to use by passing the entry_class option:
CPAN::PackageDetails->new(
...,
entry_class => $class,
)
Note that you are responsible for loading the right class yourself.
This source is in Github:
http://github.com/briandfoy/cpan-packagedetails
brian d foy, <bdfoy@cpan.org>
Copyright (c) 2009, brian d foy, All Rights Reserved.
You may redistribute this under the same terms as Perl itself.
