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->get_hash; 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, disallow_alpha_versions => 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.
CPAN::PackageDetails
CPAN::PackageDetails::Header
CPAN::PackageDetails::Entries
CPAN::PackageDetails::Entry
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:
default_headers
new
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 in CPAN::PackageDetails::Entries.
allow_packages_only_once
add_entry
If you specify the disallow_alpha_versions option with a true value and you try to add that package twice, the object will die. See add_entry in CPAN::PackageDetails::Entries.
disallow_alpha_versions
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.
read
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.
write_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 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:
check_file
# 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.
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:
entries_class
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:
count
$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:
entry_class
CPAN::PackageDetails->new( ..., entry_class => $class, )
This source is in Github:
https://github.com/briandfoy/cpan-packagedetails
brian d foy, <briandfoy@pobox.com>
<briandfoy@pobox.com>
Copyright © 2009-2024, brian d foy <briandfoy@pobox.com>. All rights reserved.
You may redistribute this under the terms of the Artistic License 2.0.
To install CPAN::PackageDetails, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CPAN::PackageDetails
CPAN shell
perl -MCPAN -e shell install CPAN::PackageDetails
For more information on module installation, please visit the detailed CPAN module installation guide.