blib/lib/Module/Manifest.pm

filter: Statementstmt 78.0% 78 / 100 Branchbran 67.1% 43 / 64 Conditioncond 46.6% 7 / 15 MC/DCmcdc 40.0% 4 / 10 Subroutinesub 93.3% 14 / 15 Podpod 100% 9 / 9 totaltotal 72.7% 155 / 213 CC 40 SCAR 25.7
CC
40
Cov
72%
normalize
56.0
open
14.6
parse
8.0
CRAP 13.0
↑ Summary
1 package Module::Manifest; # git description: 39313df
2  
3 =pod
4  
5 =head1 NAME
6  
7 Module::Manifest - Parse and examine a Perl distribution MANIFEST file
8  
9 =head1 VERSION
10  
11 version 1.09
12  
13 =head1 SYNOPSIS
14  
15 Open and parse a MANIFEST and MANIFEST.SKIP:
16  
17 my $manifest = Module::Manifest->new( 'MANIFEST', 'MANIFEST.SKIP' );
18  
19 Check if a given file matches any known skip masks:
20  
21 print "yes\n" if $manifest->skipped('.svn');
22  
23 =head1 DESCRIPTION
24  
25 B<Module::Manifest> is a simple utility module created originally for use
26 in L<Module::Inspector>.
27  
28 It can load a F<MANIFEST> file that comes in a Perl distribution tarball,
29 examine the contents, and perform some simple tasks. It can also load the
30 F<MANIFEST.SKIP> file and check that.
31  
32 Granted, the functionality needed to do this is quite simple, but the
33 Perl distribution F<MANIFEST> specification contains a couple of little
34 idiosyncracies, such as line comments and space-seperated inline
35 comments.
36  
37 The use of this module means that any little nigglies are dealt with behind
38 the scenes, and you can concentrate the main task at hand.
39  
40 =head2 Comparison to ExtUtil::Manifest
41  
42 This module is quite similar to L<ExtUtils::Manifest>, or is at least
43 similar in scope. However, there is a general difference in approach.
44  
45 L<ExtUtils::Manifest> is imperative, requires the existance of the actual
46 F<MANIFEST> file on disk, and requires that your current directory remains
47 the same.
48  
49 L<Module::Manifest> treats the F<MANIFEST> file as an object, can load
50 a the file from anywhere on disk, and can run some of the same
51 functionality without having to change your current directory context.
52  
53 That said, note that L<Module::Manifest> is aimed at reading and checking
54 existing MANFIFEST files, rather than creating new ones.
55  
56 =head1 COMPATIBILITY
57  
58 This module should be compatible with Perl 5.005 and above. However, it has
59 only been rigorously tested under Perl 5.10.0 on Linux.
60  
61 If you encounter any problems on a different version or architecture, please
62 contact the maintainer.
63  
64 =head1 METHODS
65  
66 =cut
67  
68 3 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
69 3 ▶use Carp ();
Subroutine BEGIN: called CC=1 SCAR=0.0
70 3 ▶use File::Spec ();
Subroutine BEGIN: called CC=1 SCAR=0.0
71 3 ▶use File::Spec::Unix ();
Subroutine BEGIN: called CC=1 SCAR=0.0
72 3 ▶use File::Basename ();
Subroutine BEGIN: called CC=1 SCAR=0.0
73 3 ▶use Params::Util ();
Subroutine BEGIN: called CC=1 SCAR=0.0
74  
75 3 our $VERSION = '1.09';
76  
77 # These platforms were copied from File::Spec
78 3 my %platforms = (
79 MacOS => 1,
80 MSWin32 => 1,
81 os2 => 1,
82 VMS => 1,
83 epoc => 1,
84 NetWare => 1,
85 symbian => 1,
86 dos => 1,
87 cygwin => 1,
88 );
89  
90 =pod
91  
92 =head2 new
93  
94 Module::Manifest->new( $manifest, $skip )
95  
96 Creates a C<Module::Manifest> object, which either parses the files
97 referenced by the C<$manifest> (for MANIFEST) and C<$skip>
98 (for MANIFEST.SKIP). If no parameters are specified, it creates an empty
99 object.
100  
101 Example code:
102  
103 my $manifest = Module::Manifest->new;
104 my $manifest = Module::Manifest->new( $manifest );
105 my $manifest = Module::Manifest->new( $manifest, $skip );
106  
107 This method will return an appropriate B<Module::Manifest> object or
108 throws an exception on error.
109  
110 =cut
111  
112 15 ▶sub new {
Subroutine new: called CC=4 SCAR=14.0
Pod documented
113 15 my ($class, $manifest, $skipfile) = @_;
114  
115 15 ▶ Carp::carp('Return value discarded') unless (defined wantarray);
Branch: 1 branch
BranchTrueFalseTotal
unless defined wantarray 1 14 15
116  
117 15 my $self = bless {
118 file => $manifest,
119 skipfile => $skipfile,
120 }, $class;
121  
122 15 ▶ $self->open( skip => $skipfile ) if Params::Util::_STRING($skipfile);
Branch: 1 branch
BranchTrueFalseTotal
if &Params::Util::_STRING($skipfile) 0 15 15
123 15 ▶ $self->open( manifest => $manifest ) if Params::Util::_STRING($manifest);
Branch: 1 branch
BranchTrueFalseTotal
if &Params::Util::_STRING($manifest) 0 15 15
124  
125 15 return $self;
126 }
127  
128 =pod
129  
130 =head2 open
131  
132 $manifest->open( $type => $filename )
133  
134 Open and parse the file given by C<$filename>, which may be a relative path.
135 The available C<$type> options are either: 'skip' or 'manifest'
136  
137 Example code:
138  
139 $manifest->open( skip => 'MANIFEST.SKIP' );
140 $manifest->open( manifest => 'MANIFEST' );
141  
142 This method doesn't return anything, but may throw an exception on error.
143  
144 =cut
145  
146 4 ▶sub open {
Subroutine open: called CC=8 SCAR=26.8
Pod documented
147 4 my ($self, $type, $name) = @_;
148  
149 4 ▶ Carp::croak('You must call this method as an object') unless (ref $self);
Branch: 1 branch
BranchTrueFalseTotal
unless ref $self 1 3 4
150 3 ▶ unless ( defined $name && length $name ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $name and length $name) 2 1 3
Condition100%3/3
defined $name and length $name
!ll&&!rl&&r
111
MC/DC100%2/2
defined $name and length $name
defined $name length $name
Truth table100%3/3
A and B
A= defined $nameB= length $name
ABresult
0X0
100
111
151 2 Carp::croak('You must pass a filename to read and parse');
152 }
153  
154 # Derelativise the file name if needed
155 1 my $file = File::Spec->rel2abs($name);
156 1 $self->{dir} = File::Basename::dirname($file);
157  
158 1 ▶ unless ( -f $file and -r _ ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (-f $file and -r _) 1 0 1
Condition33%1/3
-f $file and -r _
!ll&&!rl&&r
100
MC/DC0%0/2
-f $file and -r _
-f $file -r _
Truth table33%1/3
A and B
A= -f $fileB= -r _
ABresult
0X0
100
111
159 1 Carp::croak('Did not provide a readable file path');
160 }
161  
162 0 my @file;
163 0 ▶ unless ( open(MANFILE, $file) ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (CORE::open MANFILE, $file) 0 0 0
164 0 Carp::croak('Failed to load ' . $name . ': ' . $!);
165 }
166 # Slurping should be fine since files are relatively small
167 0 @file = <MANFILE>;
168 0 ▶ unless ( close MANFILE ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (close MANFILE) 0 0 0
169 0 Carp::croak('Failed to close file! This is VERY bad.');
170 }
171  
172 # Parse the file
173 0 $self->parse( $type => \@file );
174  
175 0 return;
176 }
177  
178 =pod
179  
180 =head2 parse
181  
182 $manifest->parse( $type => \@files )
183  
184 Parse C<\@files>, which is an array reference containing a list of files or
185 regular expression masks. The available C<$type> options are either: 'skip'
186 or 'manifest'
187  
188 Example code:
189  
190 $manifest->parse( skip => [
191 '\B\.svn\b',
192 '^Build$',
193 '\bMakefile$',
194 ]);
195  
196 This method doesn't return anything, but may throw an exception on error.
197  
198 =cut
199  
200 5 ▶sub parse {
Subroutine parse: called CC=8 SCAR=20.8
Pod documented
201 5 my ($self, $type, $array) = @_;
202  
203 5 ▶ Carp::croak('You must call this method as an object') unless (ref $self);
Branch: 1 branch
BranchTrueFalseTotal
unless ref $self 1 4 5
204 4 ▶ unless ( ref $array eq 'ARRAY' ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (ref $array eq "ARRAY") 1 3 4
205 1 Carp::croak('Files or masks must be specified as an array reference');
206 }
207  
208 # This hash ensures there are no duplicates
209 3 my %hash;
210 3 foreach my $line (@{$array}) {
211 8 ▶ next unless $line =~ /^\s*([^\s#]\S*)/;
Branch: 1 branch
BranchTrueFalseTotal
unless $line =~ /^\s*([^\s#]\S*)/ 0 8 8
212 8 ▶ if ($hash{$1}++) {
Branch: 1 branch
BranchTrueFalseTotal
if ($hash{$1}++) 1 7 8
213 1 Carp::carp('Duplicate file or mask ' . $1);
214 }
215 }
216  
217 3 my @masks = sort keys %hash;
218 3 ▶ if ($type eq 'skip') {
Branch: 2 branches
BranchTrueFalseTotal
if ($type eq 'skip') { } 1 2 3
elsif ($type eq 'manifest') { } 1 1 2
219 1 $self->{skiplist} = \@masks;
220 } elsif ($type eq 'manifest') {
221 1 $self->{manifest} = \@masks;
222 } else {
223 1 Carp::croak('Available types are: skip, manifest');
224 }
225  
226 2 return;
227 }
228  
229 =pod
230  
231 =head2 skipped
232  
233 $manifest->skipped( $filename )
234  
235 Check if C<$filename> matches any masks that should be skipped, given the
236 regular expressions provided to either the C<parse> or C<open> methods.
237  
238 Absolute path names must first be relativized and converted to a Unix-like
239 path string by using the C<normalize> method.
240  
241 Example code:
242  
243 if ($manifest->skipped('Makefile.PL')) {
244 # do stuff
245 }
246  
247 This method returns a boolean true or false value indicating whether the
248 file path is skipped according the C<skipfile>.
249  
250 =cut
251  
252 10 ▶sub skipped {
Subroutine skipped: called CC=8 SCAR=20.8
Pod documented
253 10 my ($self, $file) = @_;
254  
255 10 ▶ Carp::croak('You must call this method as an object') unless (ref $self);
Branch: 1 branch
BranchTrueFalseTotal
unless ref $self 1 9 10
256 9 ▶ Carp::carp('Return value discarded') unless (defined wantarray);
Branch: 1 branch
BranchTrueFalseTotal
unless defined wantarray 1 8 9
257 9 ▶ unless ( defined $file && length $file ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $file and length $file) 2 7 9
Condition100%3/3
defined $file and length $file
!ll&&!rl&&r
117
MC/DC100%2/2
defined $file and length $file
defined $file length $file
Truth table100%3/3
A and B
A= defined $fileB= length $file
ABresult
0X0
100
111
258 2 Carp::croak('You must pass a filename or path to check');
259 }
260  
261 # Quit early if we have no skip list
262 7 ▶ return 0 unless (exists $self->{skiplist});
Branch: 1 branch
BranchTrueFalseTotal
unless exists $self->{"skiplist"} 1 6 7
263  
264 # Loop through masks and exit early if there's a match
265 6 foreach my $mask (@{ $self->{skiplist} }) {
266 14 ▶ return 1 if ($file =~ /$mask/i);
Branch: 1 branch
BranchTrueFalseTotal
if $file =~ /$mask/i 4 10 14
267 }
268 2 return 0;
269 }
270  
271 =pod
272  
273 =head2 normalize
274  
275 Module::Manifest->normalize( $path, $rel )
276 $manifest->normalize( $path, $rel )
277  
278 This method takes a given platform-specific path string and converts it
279 to a Unix-style string compatible with the MANIFEST and MANIFEST.SKIP
280 specifications.
281  
282 Note that this method normalizes paths depending on the platform detected
283 by C<$^O> -- that is, Win32 style paths can only be normalized if the
284 module is currently running under Win32.
285  
286 By default, this method will relativize file paths to the current working
287 directory (using L<File::Spec>'s C<abs2rel> method without a C<$root>). To
288 disable this behaviour, set C<$rel> to a false value.
289  
290 Example code:
291  
292 # Useful for normalizing Win32-style paths
293 my $normal = Module::Manifest->normalize('t\\test\\file');
294 # Returns: t/test/file (ie, in Unix style for MANIFEST)
295  
296 This returns a normalized version of the given path.
297  
298 =cut
299  
300 0 ▶sub normalize {
Subroutine normalize: not called CC=7 SCAR=40.3
Pod documented
301 0 my (undef, $path, $rel) = @_;
302  
303 0 ▶ Carp::carp('Return value discarded') unless (defined wantarray);
Branch: 1 branch
BranchTrueFalseTotal
unless defined wantarray 0 0 0
304 0 ▶ unless ( defined $path && length $path ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $path and length $path) 0 0 0
Condition0%0/3
defined $path and length $path
!ll&&!rl&&r
000
MC/DC0%0/2
defined $path and length $path
defined $path length $path
Truth table0%0/3
A and B
A= defined $pathB= length $path
ABresult
0X0
100
111
305 0 Carp::croak('You must pass a filename or path to check');
306 }
307  
308 # Relativize if $rel is undefined or a true value
309 0 ▶ if ( !defined $rel || $path ) {
Branch: 1 branch
BranchTrueFalseTotal
if (not defined $rel or $path) 0 0 0
Condition0%0/3
not defined $rel or $path
l!l&&r!l&&!r
000
MC/DC0%0/2
not defined $rel or $path
not defined $rel $path
Truth table0%0/3
not(A) or B
A= not defined $relB= $path
ABresult
1X1
011
000
310 0 $path = File::Spec->abs2rel($path);
311 }
312  
313 # Portably deal with different OSes
314 0 ▶ if ($platforms{$^O}) { # Check if we are on a non-Unix platform
Branch: 1 branch
BranchTrueFalseTotal
if ($platforms{$^O}) 0 0 0
315 # Get path info from File::Spec, split apart
316 0 my (undef, $dir, $filename) = File::Spec->splitpath($path);
317 0 my @dir = File::Spec->splitdir($dir);
318  
319 # Reconstruct the path in Unix-style
320 0 $dir = File::Spec::Unix->catdir(@dir);
321 0 $path = File::Spec::Unix->catpath(undef, $dir, $filename);
322 }
323  
324 0 return $path;
325 }
326  
327 =pod
328  
329 =head2 file
330  
331 $manifest->file
332  
333 The C<file> accessor returns the absolute path of the MANIFEST file that
334 was loaded.
335  
336 =cut
337  
338 2 ▶sub file {
Subroutine file: called CC=3 SCAR=11.0
Pod documented
339 2 my ($self) = @_;
340 2 ▶ Carp::croak('You must call this method as an object') unless (ref $self);
Branch: 1 branch
BranchTrueFalseTotal
unless ref $self 1 1 2
341 1 ▶ Carp::carp('Return value discarded') unless (defined wantarray);
Branch: 1 branch
BranchTrueFalseTotal
unless defined wantarray 1 0 1
342 1 return $self->{file};
343 }
344  
345 =pod
346  
347 =head2 skipfile
348  
349 $manifest->skipfile
350  
351 The C<skipfile> accessor returns the absolute path of the MANIFEST.SKIP file
352 that was loaded.
353  
354 =cut
355  
356 2 ▶sub skipfile {
Subroutine skipfile: called CC=3 SCAR=11.0
Pod documented
357 2 my ($self) = @_;
358 2 ▶ Carp::croak('You must call this method as an object') unless (ref $self);
Branch: 1 branch
BranchTrueFalseTotal
unless ref $self 1 1 2
359 1 ▶ Carp::carp('Return value discarded') unless (defined wantarray);
Branch: 1 branch
BranchTrueFalseTotal
unless defined wantarray 1 0 1
360 1 return $self->{skipfile};
361 }
362  
363 =pod
364  
365 =head2 dir
366  
367 $manifest->dir
368  
369 The C<dir> accessor returns the path to the directory that contains the
370 MANIFEST or skip file, and thus SHOULD be the root of the distribution.
371  
372 =cut
373  
374 2 ▶sub dir {
Subroutine dir: called CC=3 SCAR=11.0
Pod documented
375 2 my ($self) = @_;
376 2 ▶ Carp::croak('You must call this method as an object') unless (ref $self);
Branch: 1 branch
BranchTrueFalseTotal
unless ref $self 1 1 2
377 1 ▶ Carp::carp('Return value discarded') unless (defined wantarray);
Branch: 1 branch
BranchTrueFalseTotal
unless defined wantarray 1 0 1
378 1 return $self->{dir};
379 }
380  
381 =pod
382  
383 =head2 files
384  
385 $manifest->files
386  
387 The C<files> method returns the (relative, unix-style) list of files within
388 the manifest. In scalar context, returns the number of files in the manifest.
389  
390 Example code:
391  
392 my @files = $manifest->files;
393  
394 =cut
395  
396 2 ▶sub files {
Subroutine files: called CC=4 SCAR=15.0
Pod documented
397 2 my ($self) = @_;
398 2 ▶ Carp::croak('You must call this method as an object') unless (ref $self);
Branch: 1 branch
BranchTrueFalseTotal
unless ref $self 1 1 2
399 1 ▶ Carp::carp('Return value discarded') unless (defined wantarray);
Branch: 1 branch
BranchTrueFalseTotal
unless defined wantarray 1 0 1
400 1 ▶ if (exists($self->{manifest})) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $self->{"manifest"}) 0 1 1
401 0 return @{ $self->{manifest} };
402 }
403 1 return ();
404 }
405  
406 3 1;
407  
408 =pod
409  
410 =head1 LIMITATIONS
411  
412 The directory returned by the C<dir> method is overwritten whenever C<open>
413 is called. This means that, if MANIFEST and MANIFEST.SKIP are not in the
414 same directory, the module may get a bit confused.
415  
416 =head1 SUPPORT
417  
418 This module is stored in an Open Repository at the following address:
419  
420 L<http://svn.ali.as/cpan/trunk/Module-Manifest>
421  
422 Write access to the repository is made available automatically to any
423 published CPAN author, and to most other volunteers on request.
424  
425 If you are able to submit your bug report in the form of new (failing) unit
426 tests, or can apply your fix directly instead of submitting a patch, you are
427 B<strongly> encouraged to do so. The author currently maintains over 100
428 modules and it may take some time to deal with non-critical bug reports or
429 patches.
430  
431 This will guarantee that your issue will be addressed in the next release of
432 the module.
433  
434 If you cannot provide a direct test or fix, or don't have time to do so, then
435 regular bug reports are still accepted and appreciated via the CPAN bug
436 tracker.
437  
438 L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Module-Manifest>
439  
440 For other issues, for commercial enhancement and support, or to have your
441 write access enabled for the repository, contact the author at the email
442 address above.
443  
444 =head1 AUTHOR
445  
446 Adam Kennedy E<lt>adamk@cpan.orgE<gt>
447  
448 =head2 CONTIRBUTORS
449  
450 Jonathan Yu E<lt>jawnsy@cpan.orgE<gt>
451  
452 =head1 SEE ALSO
453  
454 L<ExtUtils::Manifest>
455  
456 =head1 COPYRIGHT
457  
458 Copyright 2006 - 2010 Adam Kennedy
459  
460 This program is free software; you can redistribute it and/or modify it
461 under the same terms as Perl itself.
462  
463 The full text of the license can be found in the LICENSE file included
464 with this module.
465  
466 =cut
↑ Summary