NAME

       Module::Extract - Base class for working with Perl distributions

SYNOPSIS

       Creating a Module::Extract subclass.

         package My::Readme;

         # Shows the README file for a module

         use strict;
         use base 'Module::Extract';

         sub show {
             my $self   = shift;
             my $readme = $self->file_path('README');
             if ( -f $readme ) {
                 system( "cat $readme" );
             } else {
                 print "Dist does not have a README file";
             }
         }

         1;

       A script that uses the module to show the readme file for a distribution filename provided
       by the user.

         #!/usr/bin/perl

         use My::Readme;

         My::Readme->new( dist_file => $ARGV[0] )->show;

         exit(0);

DESCRIPTION

       Module::Extract is a convenience base class for creating module that work with Perl
       distributions.

       Its purpose is to take care of the mechanisms of locating and extracting a Perl
       distribution so that your module can do something specific to the distribution.

       This module was originally created to provide an abstraction for the extraction logic for
       both Module::Inspector and Module::P4P and to allow additional features to be added in the
       future without having to modify both of them, because the general problem of "locate,
       download, and expand a distribution" is one that is almost ideal for adding additional
       features down the line.

   new
         my $from_file = My::Class->new(
             dist_file => 'tarball.tar.gz',
             );

         my $from_dir = My::Class->new(
             dist_dir  => 'some/dir',
             );

       The "new" constructor takes a "dist_file" and/or a "dist_dir" param, locates and (if
       needed) expands the distribution tarball.

       It takes either a "dist_file" param, which should be the local path to the tarball, or a
       "dist_dir" which should be the path to a directory which contains an already-expanded
       distribution (such as from a repository checkout).

       Return a new Module::Extract-subclass object, or dies on error.

   dist_file
       The "dist_file" accessor returns the (absolute) path to the distribution tarball. If the
       inspector was created with "dist_dir" rather than "dist_file", this will return "undef".

   dist_type
       The "dist_type" method returns the archive type of the distribution tarball. This will be
       either 'tar.gz', 'tgz', or 'zip'. Other file types are not supported at this time.

       If the inspector was created with "dist_dir" rather than "dist_file", this will return
       "undef".

   dist_dir
       The "dist_dir" method returns the (absolute) distribution root directory.

       If the inspector was created with "dist_file" rather than "dist_file", this method will
       return the temporary directory created to hold the unwrapped tarball.

   file_path
         my $local_path = $inspector->file_path('lib/Foo.pm');

       To simplify implementations, most tools that work with distributions identify files in
       unix-style relative paths.

       The "file_path" method takes a unix-style relative path and returns a localised absolute
       path to the file on disk (either in the actual distribution directory, or the temp
       directory holding the expanded tarball.

   dir_path
         my $local_path = $inspector->file_path('lib');

       The "dir_path" method is the matching pair of the "file_path" method.

       As for that method, it takes a unix-style relative directory name, and returns a localised
       absolute path to the directory.

SUPPORT

       This module is stored in an Open Repository at the following address.

       <http://svn.phase-n.com/svn/cpan/trunk/Module-Extract>

       Write access to the repository is made available automatically to any published CPAN
       author, and to most other volunteers on request.

       If you are able to submit your bug report in the form of new (failing) unit tests, or can
       apply your fix directly instead of submitting a patch, you are strongly encouraged to do
       so as the author currently maintains over 100 modules and it can take some time to deal
       with non-Critcal bug reports or patches.

       This will guarentee that your issue will be addressed in the next release of the module.

       If you cannot provide a direct test or fix, or don't have time to do so, then regular bug
       reports are still accepted and appreciated via the CPAN bug tracker.

       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Module-Extract>

       For other issues, for commercial enhancement or support, or to have your write access
       enabled for the repository, contact the author at the email address above.

AUTHORS

       Adam Kennedy <adamk@cpan.org>

SEE ALSO

       Module::Inspector, Module::P4P

COPYRIGHT

       Copyright 2006 Adam Kennedy.

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.

       The full text of the license can be found in the LICENSE file included with this module.