view release on metacpan or  search on metacpan

lib/AnnoCPAN/Dist.pm  view on Meta::CPAN

package AnnoCPAN::Dist;

use strict;
use warnings;
use 5.006;
use List::Util qw(first);
use AnnoCPAN::Archive;
use AnnoCPAN::DBI;
use AnnoCPAN::PodParser;
use IO::String;
use Digest::MD5 qw(md5_hex);
use File::stat ();
use base qw(CPAN::DistnameInfo Exporter);
use overload '""' => 'distvname';
use constant {
    DIST_ADDED          => 0,
    DIST_OLD            => 1,
    DIST_NO_ARCHIVE     => 2,
    DIST_UGLY_PACKAGE   => 3,
    DIST_STORE_ERR      => 4,
};

our $VERSION = '0.22';
our @EXPORT_OK = qw(
    DIST_ADDED 
    DIST_OLD 
    DIST_NO_ARCHIVE 
    DIST_UGLY_PACKAGE 
    DIST_STORE_ERR
);
our %EXPORT_TAGS = ( all => \@EXPORT_OK );


=head1 NAME

AnnoCPAN::Dist - CPAN distribution extracting and munging

=head1 SYNOPSIS

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

=head1 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:

=over

=item *

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

=item *

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

=item *

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

=item *

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

=back

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.

=head1 METHODS

=over

=cut

# default files to ignore
my @exclude = (
    qr(/inc/),      # used by Module::Install bundles
    qr(/t/),
    qr(/eg/),
    qr(/blib/),
    qr(/Makefile(.PL)?$),
    qr(/Build.PL$),
    qr(/MANIFEST$)i,
    qr(/README$)i,
    qr(/Changes$)i,
    qr(/ChangeLog$)i,
    qr(/LICENSE$)i,
    qr(/TODO$)i,
    qr(/AUTHORS?$)i,
);

# default files to include
my @include = (