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.
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.
allow_packages_only_once
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.
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
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:
http://github.com/briandfoy/cpan-packagedetails
brian d foy, <bdfoy@cpan.org>
<bdfoy@cpan.org>
Copyright (c) 2009, brian d foy, All Rights Reserved.
You may redistribute this under the same terms as Perl itself.
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.