Ivan Tubert-Brohman


AnnoCPAN::Dist - CPAN distribution extracting and munging


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


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.


$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.


Return the AnnoCPAN::Archive object for this distribution.


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


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


Returns a list of all the filenames in the package.


Returns the contents of a file in the package.


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


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


Return true if the distribution has a lib/ directory.


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".


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.


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


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


Ivan Tubert-Brohman <itub@cpan.org>


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.