NAME

AnnoCPAN::Dist - CPAN distribution extracting and munging

SYNOPSIS

    use AnnoCPAN::Dist;
    my $dist = AnnoCPAN::Dist->new('/path/to/Dist-0.01.tar.gz')
        or die "$@";
    $dist->extract;

DESCRIPTION

AnnoCPAN has to understand CPAN distribution packages, find all the relevant documentation they contain, and figure out the versions and the correct pathname for each document. This is not a trivial task given the inconsistent ways in which CPAN distributions are packaged; there are several specific cases to consider. Note that this module does not aim at 100.00% coverage (but at least 99%, I hope); if a package does not comply with any of the standards that this package understands, it will be silently excluded. One can only hope the authors of the excluded package will some day decide to package their modules in more standard ways.

This module claims to understand the following types of packages:

• Files in the .zip and .tar.gz file formats.

• Packages where all the modules are in the lib/ subdirectory.

• Packages bundled with Module::Install, where the inc/ directory should be ignored.

• "Old-style" packages, where the modules are in the top directory, with sub-namespaces in subdirectories.

Files that appear to be PPM packages are ignored.

This class inherits from CPAN::DistnameInfo, and relies on it for parsing the filename and figuring out things such as the version number.

The version numbers are derived from the package filename only, and are expected to be floating-point numbers. The $VERSION values inside the module code are considered irrelevant for the purpose of this project.

METHODS

$class->new($fname, %options)

Create a new distribution object from a filename. Returns undef on failure. Currently the only option is 'verbose'; if true, various diagnostic messages are printed to STDOUT and STDERR when extracting the file.

$obj->archive

Return the AnnoCPAN::Archive object for this distribution.

$obj->mtime

Returns the modification time of the package (seconds since epoch).

$obj->stat

Returns a File::stat object for the distribution package.

$obj->files

Returns a list of all the filenames in the package.

$obj->read_file($fname)

Returns the contents of a file in the package.

$obj->verbose

Returns true if the verbose option was given when constructing the object.

$obj->rel_pathname

Returns the pathname relative to the CPAN root (e.g., authors/id/A/AA/AAA/aaa-1.0.tar.gz)

$obj->has_lib

Return true if the distribution has a lib/ directory.

$obj->namespace_from_path($fname)

Given the path of one of the files in the archive, use heuristics to find out its path in the perl module hierarchy. For example, given "Dist-0.01/lib/My/Module.pm", returns "My/Module.pm".

$obj->extract

Open the archive, extract the pod, and load it into the database. Returns true on success, false on failure.

The same distribution file will not be loaded twice; in that case, returns true without doing anything.

$obj->store_podver($path, $pod)

Store a pod.

$obj->store_distver

Add a record to the database (using AnnoCPAN::DBI::Dist). Returns the new object if it was created successfully.

SEE ALSO

AnnoCPAN::DBI, AnnoCPAN::Update, CPAN::DistnameInfo

AUTHOR

Ivan Tubert-Brohman <itub@cpan.org>

COPYRIGHT

Copyright (c) 2005 Ivan Tubert-Brohman. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.