1Module::Extract(3)    User Contributed Perl Documentation   Module::Extract(3)
2
3
4

NAME

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

SYNOPSIS

9       Creating a Module::Extract subclass.
10
11         package My::Readme;
12
13         # Shows the README file for a module
14
15         use strict;
16         use base 'Module::Extract';
17
18         sub show {
19             my $self   = shift;
20             my $readme = $self->file_path('README');
21             if ( -f $readme ) {
22                 system( "cat $readme" );
23             } else {
24                 print "Dist does not have a README file";
25             }
26         }
27
28         1;
29
30       A script that uses the module to show the readme file for a
31       distribution filename provided by the user.
32
33         #!/usr/bin/perl
34
35         use My::Readme;
36
37         My::Readme->new( dist_file => $ARGV[0] )->show;
38
39         exit(0);
40

DESCRIPTION

42       Module::Extract is a convenience base class for creating module that
43       work with Perl distributions.
44
45       Its purpose is to take care of the mechanisms of locating and
46       extracting a Perl distribution so that your module can do something
47       specific to the distribution.
48
49       This module was originally created to provide an abstraction for the
50       extraction logic for both Module::Inspector and Module::P4P and to
51       allow additional features to be added in the future without having to
52       modify both of them, because the general problem of "locate, download,
53       and expand a distribution" is one that is almost ideal for adding
54       additional features down the line.
55
56   new
57         my $from_file = My::Class->new(
58             dist_file => 'tarball.tar.gz',
59             );
60
61         my $from_dir = My::Class->new(
62             dist_dir  => 'some/dir',
63             );
64
65       The "new" constructor takes a "dist_file" and/or a "dist_dir" param,
66       locates and (if needed) expands the distribution tarball.
67
68       It takes either a "dist_file" param, which should be the local path to
69       the tarball, or a "dist_dir" which should be the path to a directory
70       which contains an already-expanded distribution (such as from a
71       repository checkout).
72
73       Return a new Module::Extract-subclass object, or dies on error.
74
75   dist_file
76       The "dist_file" accessor returns the (absolute) path to the
77       distribution tarball. If the inspector was created with "dist_dir"
78       rather than "dist_file", this will return "undef".
79
80   dist_type
81       The "dist_type" method returns the archive type of the distribution
82       tarball. This will be either 'tar.gz', 'tgz', or 'zip'. Other file
83       types are not supported at this time.
84
85       If the inspector was created with "dist_dir" rather than "dist_file",
86       this will return "undef".
87
88   dist_dir
89       The "dist_dir" method returns the (absolute) distribution root
90       directory.
91
92       If the inspector was created with "dist_file" rather than "dist_file",
93       this method will return the temporary directory created to hold the
94       unwrapped tarball.
95
96   file_path
97         my $local_path = $inspector->file_path('lib/Foo.pm');
98
99       To simplify implementations, most tools that work with distributions
100       identify files in unix-style relative paths.
101
102       The "file_path" method takes a unix-style relative path and returns a
103       localised absolute path to the file on disk (either in the actual
104       distribution directory, or the temp directory holding the expanded
105       tarball.
106
107   dir_path
108         my $local_path = $inspector->file_path('lib');
109
110       The "dir_path" method is the matching pair of the "file_path" method.
111
112       As for that method, it takes a unix-style relative directory name, and
113       returns a localised absolute path to the directory.
114

SUPPORT

116       This module is stored in an Open Repository at the following address.
117
118       http://svn.phase-n.com/svn/cpan/trunk/Module-Extract <http://svn.phase-
119       n.com/svn/cpan/trunk/Module-Extract>
120
121       Write access to the repository is made available automatically to any
122       published CPAN author, and to most other volunteers on request.
123
124       If you are able to submit your bug report in the form of new (failing)
125       unit tests, or can apply your fix directly instead of submitting a
126       patch, you are strongly encouraged to do so as the author currently
127       maintains over 100 modules and it can take some time to deal with non-
128       Critcal bug reports or patches.
129
130       This will guarentee that your issue will be addressed in the next
131       release of the module.
132
133       If you cannot provide a direct test or fix, or don't have time to do
134       so, then regular bug reports are still accepted and appreciated via the
135       CPAN bug tracker.
136
137       http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Module-Extract
138       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Module-Extract>
139
140       For other issues, for commercial enhancement or support, or to have
141       your write access enabled for the repository, contact the author at the
142       email address above.
143

AUTHORS

145       Adam Kennedy <adamk@cpan.org>
146

SEE ALSO

148       Module::Inspector, Module::P4P
149

151       Copyright 2006 Adam Kennedy.
152
153       This program is free software; you can redistribute it and/or modify it
154       under the same terms as Perl itself.
155
156       The full text of the license can be found in the LICENSE file included
157       with this module.
158
159
160
161perl v5.12.0                      2006-10-02                Module::Extract(3)
Impressum