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.