.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Module::Extract 3pm" .TH Module::Extract 3pm "2022-06-15" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Module::Extract \- Base class for working with Perl distributions .SH "SYNOPSIS" .IX Header "SYNOPSIS" Creating a Module::Extract subclass. .PP .Vb 1 \& package My::Readme; \& \& # Shows the README file for a module \& \& use strict; \& use base \*(AqModule::Extract\*(Aq; \& \& sub show { \& my $self = shift; \& my $readme = $self\->file_path(\*(AqREADME\*(Aq); \& if ( \-f $readme ) { \& system( "cat $readme" ); \& } else { \& print "Dist does not have a README file"; \& } \& } \& \& 1; .Ve .PP A script that uses the module to show the readme file for a distribution filename provided by the user. .PP .Vb 1 \& #!/usr/bin/perl \& \& use My::Readme; \& \& My::Readme\->new( dist_file => $ARGV[0] )\->show; \& \& exit(0); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBModule::Extract\fR is a convenience base class for creating module that work with Perl distributions. .PP 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. .PP 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 \*(L"locate, download, and expand a distribution\*(R" is one that is almost ideal for adding additional features down the line. .SS "new" .IX Subsection "new" .Vb 3 \& my $from_file = My::Class\->new( \& dist_file => \*(Aqtarball.tar.gz\*(Aq, \& ); \& \& my $from_dir = My::Class\->new( \& dist_dir => \*(Aqsome/dir\*(Aq, \& ); .Ve .PP The \f(CW\*(C`new\*(C'\fR constructor takes a \f(CW\*(C`dist_file\*(C'\fR and/or a \f(CW\*(C`dist_dir\*(C'\fR param, locates and (if needed) expands the distribution tarball. .PP It takes either a \f(CW\*(C`dist_file\*(C'\fR param, which should be the local path to the tarball, or a \f(CW\*(C`dist_dir\*(C'\fR which should be the path to a directory which contains an already-expanded distribution (such as from a repository checkout). .PP Return a new \fBModule::Extract\fR\-subclass object, or dies on error. .SS "dist_file" .IX Subsection "dist_file" The \f(CW\*(C`dist_file\*(C'\fR accessor returns the (absolute) path to the distribution tarball. If the inspector was created with \f(CW\*(C`dist_dir\*(C'\fR rather than \f(CW\*(C`dist_file\*(C'\fR, this will return \f(CW\*(C`undef\*(C'\fR. .SS "dist_type" .IX Subsection "dist_type" The \f(CW\*(C`dist_type\*(C'\fR 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. .PP If the inspector was created with \f(CW\*(C`dist_dir\*(C'\fR rather than \&\f(CW\*(C`dist_file\*(C'\fR, this will return \f(CW\*(C`undef\*(C'\fR. .SS "dist_dir" .IX Subsection "dist_dir" The \f(CW\*(C`dist_dir\*(C'\fR method returns the (absolute) distribution root directory. .PP If the inspector was created with \f(CW\*(C`dist_file\*(C'\fR rather than \f(CW\*(C`dist_file\*(C'\fR, this method will return the temporary directory created to hold the unwrapped tarball. .SS "file_path" .IX Subsection "file_path" .Vb 1 \& my $local_path = $inspector\->file_path(\*(Aqlib/Foo.pm\*(Aq); .Ve .PP To simplify implementations, most tools that work with distributions identify files in unix-style relative paths. .PP The \f(CW\*(C`file_path\*(C'\fR 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. .SS "dir_path" .IX Subsection "dir_path" .Vb 1 \& my $local_path = $inspector\->file_path(\*(Aqlib\*(Aq); .Ve .PP The \f(CW\*(C`dir_path\*(C'\fR method is the matching pair of the \f(CW\*(C`file_path\*(C'\fR method. .PP As for that method, it takes a unix-style relative directory name, and returns a localised absolute path to the directory. .SH "SUPPORT" .IX Header "SUPPORT" This module is stored in an Open Repository at the following address. .PP .PP Write access to the repository is made available automatically to any published \s-1CPAN\s0 author, and to most other volunteers on request. .PP 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 \fBstrongly\fR 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. .PP This will guarentee that your issue will be addressed in the next release of the module. .PP 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 \s-1CPAN\s0 bug tracker. .PP .PP 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. .SH "AUTHORS" .IX Header "AUTHORS" Adam Kennedy .SH "SEE ALSO" .IX Header "SEE ALSO" Module::Inspector, Module::P4P .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2006 Adam Kennedy. .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .PP The full text of the license can be found in the \&\s-1LICENSE\s0 file included with this module.