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.