NAME

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

SYNOPSIS

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 )

DESCRIPTION

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.

Methods

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.

new

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.

init

Sets up the object. new calls this automatically for you.

default_headers

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( FILE )

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

source_file

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

write_file( OUTPUT_FILE )

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_fh( FILEHANDLE )

Formats the object as a string and writes it to FILEHANDLE

check_file

Methods in CPAN::PackageDetails

header_class

Returns the class that CPAN::PackageDetails uses to create the header object.

header

Returns the header object.

Methods in CPAN::PackageDetails::Header

Entries

Entries are the collection of the items describing the package details. It comprises all of the Entry object.

Methods is CPAN::PackageDetails

entries_class

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.

count

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;

entries

Returns the entries object.

entry_class

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.

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) 2009, brian d foy, All Rights Reserved.

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