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.