NAME

CPAN::PackageDetails - Create or read 02.packages.details.txt.gz

SYNOPSIS

use CPAN::PackageDetails;

# read an existing file #####################
my $package_details = CPAN::PackageDetails->read( $filename );

my $creator    = $package_details->creator;  # See CPAN::PackageDetails::Header too
my $count      = $package_details->lines;

my $records    = $package_details->entries;

foreach my $record ( @$records )
	{
	# See CPAN::PackageDetails::Entry too
	print join "\t", map { $record->$_() } qw(package_name version path)
	}
	
# 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         => "02.packages.details.txt",
	url          => "http://example.com/MyCPAN/modules/02.packages.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 => $epoch_time,
	);

$package_details->add_entry(
	package_name => $package,
	version      => $package->VERSION;
	path         => $path,
	);
	
print "About to write ", $package_details->lines;
my $big_string = $package_details->as_string;

$package_details->write_file;

DESCRIPTION

CPAN uses an index file, 02.packages.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 02.packages.details.txt.gz: a header and the index

new

Create a new 02.packages.details.txt.gz file.

init

default_headers

Returns the keys for the

read( FILE )

Read an existing 02.packages.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

source_file

Returns the original file path for objects created through the read method.

write_file( OUTPUT_FILE )

write_fh( FILEHANDLE )

Headers

The 02.packages.details.txt.gz header is a short preamble that give information about the creation of the file, its intended use, and the number of entries in the file. It looks something like:

File:         02packages.details.txt
URL:          http://www.perl.com/CPAN/modules/02packages.details.txt
Description:  Package names found in directory $CPAN/authors/id/
Columns:      package name, version, path
Intended-For: Automated fetch routines, namespace documentation.
Written-By:   Id: mldistwatch.pm 1063 2008-09-23 05:23:57Z k 
Line-Count:   59754
Last-Updated: Thu, 23 Oct 2008 02:27:36 GMT

Note that there is a Columns field. This module tries to respect the ordering of columns in there. The usual CPAN tools expect only three columns and in the order in this example, but CPAN::PackageDetails tries to handle any number of columns in any order.

header_class

header

Returns the header object.

set_header

Add an entry to the collection. Call this on the CPAN::PackageDetails object and it will take care of finding the right handler.

header_exists

header_exists( FIELD )

Returns true if the header has a field named FIELD, regardless of its value.

columns_as_list

as_string

sub _fmtdate { my @date=split(/\s+/,scalar(gmtime())); return "$date[0], $date[2] $date[1] $date[4] $date[3] GMT"; }

Entries

An entry is a single line from 02.packages.details.txt that maps a package name to a source. It's a whitespace-separated list that has the values for the column identified in the "columns" field in the header.

By default, there are three columns: package name, version, and path.

Inside a CPAN::PackageDetails object, the actual work and manipulation of the entries are handled by delegate classes specified in entries_class and entry_class). At the moment these are immutable, so you'd have to subclass this module to change them.

new

entries_class

Returns the class to use for the entries collection, which is CPAN::PackageDetails::Entries by default. Anything that wants to work with the entries as a whole should do it through this class's interface. This is a hook for subclasses, and you don't need to fool with it for the common cases since most of this is implementation rather than interface.

entry_class

Returns the class to use for a single entry, which is CPAN::PackageDetails::Entry by default. Anything that wants to work with an entry as a whole should do it through this class's interface. This is a hook for subclasses, and you don't need to fool with it for the common cases since most of this is implementation rather than interface.

entries

Returns the entries object.

as_string

add_entry

Add an entry to the collection. Call this on the CPAN::PackageDetails object and it will take care of finding the right handler.

TO DO

SEE ALSO

SOURCE AVAILABILITY

This source is in Github:

http://github.com/briandfoy/cpan-packagedetails

AUTHOR

brian d foy, <bdfoy@cpan.org>

COPYRIGHT AND LICENSE

Copyright (c) 2008, brian d foy, All Rights Reserved.

You may redistribute this under the same terms as Perl itself.