Module::Manifest(3pm)

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

NAME

6       Module::Manifest - Parse and examine a Perl distribution MANIFEST file
7

SYNOPSIS

9       Open and parse a MANIFEST and MANIFEST.SKIP:
10
11         my $manifest = Module::Manifest->new( 'MANIFEST', 'MANIFEST.SKIP' );
12
13       Check if a given file matches any known skip masks:
14
15         print "yes\n" if $manifest->skipped('.svn');
16

DESCRIPTION

18       Module::Manifest is a simple utility module created originally for use
19       in Module::Inspector.
20
21       It can load a MANIFEST file that comes in a Perl distribution tarball,
22       examine the contents, and perform some simple tasks. It can also load
23       the MANIFEST.SKIP file and check that.
24
25       Granted, the functionality needed to do this is quite simple, but the
26       Perl distribution MANIFEST specification contains a couple of little
27       idiosyncracies, such as line comments and space-seperated inline
28       comments.
29
30       The use of this module means that any little nigglies are dealt with
31       behind the scenes, and you can concentrate the main task at hand.
32
33   Comparison to ExtUtil::Manifest
34       This module is quite similar to ExtUtils::Manifest, or is at least
35       similar in scope. However, there is a general difference in approach.
36
37       ExtUtils::Manifest is imperative, requires the existance of the actual
38       MANIFEST file on disk, and requires that your current directory remains
39       the same.
40
41       Module::Manifest treats the MANIFEST file as an object, can load a the
42       file from anywhere on disk, and can run some of the same functionality
43       without having to change your current directory context.
44
45       That said, note that Module::Manifest is aimed at reading and checking
46       existing MANFIFEST files, rather than creating new ones.
47

COMPATIBILITY

49       This module should be compatible with Perl 5.005 and above. However, it
50       has only been rigorously tested under Perl 5.10.0 on Linux.
51
52       If you encounter any problems on a different version or architecture,
53       please contact the maintainer.
54

METHODS

56   new
57         Module::Manifest->new( $manifest, $skip )
58
59       Creates a "Module::Manifest" object, which either parses the files
60       referenced by the $manifest (for MANIFEST) and $skip (for
61       MANIFEST.SKIP). If no parameters are specified, it creates an empty
62       object.
63
64       Example code:
65
66         my $manifest = Module::Manifest->new;
67         my $manifest = Module::Manifest->new( $manifest );
68         my $manifest = Module::Manifest->new( $manifest, $skip );
69
70       This method will return an appropriate Module::Manifest object or
71       throws an exception on error.
72
73   open
74         $manifest->open( $type => $filename )
75
76       Open and parse the file given by $filename, which may be a relative
77       path.  The available $type options are either: 'skip' or 'manifest'
78
79       Example code:
80
81         $manifest->open( skip => 'MANIFEST.SKIP' );
82         $manifest->open( manifest => 'MANIFEST' );
83
84       This method doesn't return anything, but may throw an exception on
85       error.
86
87   parse
88         $manifest->parse( $type => \@files )
89
90       Parse "\@files", which is an array reference containing a list of files
91       or regular expression masks. The available $type options are either:
92       'skip' or 'manifest'
93
94       Example code:
95
96         $manifest->parse( skip => [
97              '\B\.svn\b',
98              '^Build$',
99              '\bMakefile$',
100         ]);
101
102       This method doesn't return anything, but may throw an exception on
103       error.
104
105   skipped
106         $manifest->skipped( $filename )
107
108       Check if $filename matches any masks that should be skipped, given the
109       regular expressions provided to either the "parse" or "open" methods.
110
111       Absolute path names must first be relativized and converted to a Unix-
112       like path string by using the "normalize" method.
113
114       Example code:
115
116         if ($manifest->skipped('Makefile.PL')) {
117           # do stuff
118         }
119
120       This method returns a boolean true or false value indicating whether
121       the file path is skipped according the "skipfile".
122
123   normalize
124         Module::Manifest->normalize( $path, $rel )
125         $manifest->normalize( $path, $rel )
126
127       This method takes a given platform-specific path string and converts it
128       to a Unix-style string compatible with the MANIFEST and MANIFEST.SKIP
129       specifications.
130
131       Note that this method normalizes paths depending on the platform
132       detected by $^O -- that is, Win32 style paths can only be normalized if
133       the module is currently running under Win32.
134
135       By default, this method will relativize file paths to the current
136       working directory (using File::Spec's "abs2rel" method without a
137       $root). To disable this behaviour, set $rel to a false value.
138
139       Example code:
140
141         # Useful for normalizing Win32-style paths
142         my $normal = Module::Manifest->normalize('t\\test\\file');
143         # Returns: t/test/file (ie, in Unix style for MANIFEST)
144
145       This returns a normalized version of the given path.
146
147   file
148         $manifest->file
149
150       The "file" accessor returns the absolute path of the MANIFEST file that
151       was loaded.
152
153   skipfile
154         $manifest->skipfile
155
156       The "skipfile" accessor returns the absolute path of the MANIFEST.SKIP
157       file that was loaded.
158
159   dir
160         $manifest->dir
161
162       The "dir" accessor returns the path to the directory that contains the
163       MANIFEST or skip file, and thus SHOULD be the root of the distribution.
164
165   files
166         $manifest->files
167
168       The "files" method returns the (relative, unix-style) list of files
169       within the manifest. In scalar context, returns the number of files in
170       the manifest.
171
172       Example code:
173
174         my @files = $manifest->files;
175

LIMITATIONS

177       The directory returned by the "dir" method is overwritten whenever
178       "open" is called. This means that, if MANIFEST and MANIFEST.SKIP are
179       not in the same directory, the module may get a bit confused.
180

SUPPORT

182       This module is stored in an Open Repository at the following address:
183
184       <http://svn.ali.as/cpan/trunk/Module-Manifest>
185
186       Write access to the repository is made available automatically to any
187       published CPAN author, and to most other volunteers on request.
188
189       If you are able to submit your bug report in the form of new (failing)
190       unit tests, or can apply your fix directly instead of submitting a
191       patch, you are strongly encouraged to do so. The author currently
192       maintains over 100 modules and it may take some time to deal with non-
193       critical bug reports or patches.
194
195       This will guarantee that your issue will be addressed in the next
196       release of the module.
197
198       If you cannot provide a direct test or fix, or don't have time to do
199       so, then regular bug reports are still accepted and appreciated via the
200       CPAN bug tracker.
201
202       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Module-Manifest>
203
204       For other issues, for commercial enhancement and support, or to have
205       your write access enabled for the repository, contact the author at the
206       email address above.
207

AUTHOR

209       Adam Kennedy <adamk@cpan.org>
210
211   CONTIRBUTORS
212       Jonathan Yu <jawnsy@cpan.org>
213

COPYRIGHT

218       Copyright 2006 - 2010 Adam Kennedy
219
220       This program is free software; you can redistribute it and/or modify it
221       under the same terms as Perl itself.
222
223       The full text of the license can be found in the LICENSE file included
224       with this module.
225
226
227
228perl v5.16.3                      2010-06-15               Module::Manifest(3)