blib/lib/Module/Util.pm

filter: Statementstmt 100% 92 / 92 Branchbran 97.0% 33 / 34 Conditioncond 66.6% 2 / 3 MC/DCmcdc 50.0% 1 / 2 Subroutinesub 100% 22 / 22 Podpod 100% 12 / 12 totaltotal 98.1% 162 / 165 CC 22 SCAR 9.9
CC
22
Cov
98%
find_in_namespace
6.0
find_installed
4.0
__ANON__
3.0
CRAP 2.7
↑ Summary
1 package Module::Util;
2  
3 2 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 2 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 2 our $VERSION = '1.09';
7  
8 =encoding UTF-8
9  
10 =head1 NAME
11  
12 Module::Util - Module name tools and transformations
13  
14 =head1 SYNOPSIS
15  
16 use Module::Util qw( :all );
17  
18 $valid = is_valid_module_name $potential_module;
19  
20 $relative_path = module_path $module_name;
21  
22 $file_system_path = module_fs_path $module_name;
23  
24 # load module at runtime
25 require module_path $module_name;
26  
27 # (see perldoc -f require for limitations of this approach.)
28  
29 =head1 DESCRIPTION
30  
31 This module provides a few useful functions for manipulating module names. Its
32 main aim is to centralise some of the functions commonly used by modules that
33 manipulate other modules in some way, like converting module names to relative
34 paths.
35  
36 =cut
37  
38 2 ▶use Exporter;
Subroutine BEGIN: called CC=1 SCAR=0.0
39 2 ▶use File::Spec::Functions qw( catfile rel2abs abs2rel splitpath splitdir );
Subroutine BEGIN: called CC=1 SCAR=0.0
40 2 ▶use File::Find;
Subroutine BEGIN: called CC=1 SCAR=0.0
41  
42 =head1 EXPORTS
43  
44 Nothing by default.
45  
46 Use the tag :all to import all functions.
47  
48 =head1 FUNCTIONS
49  
50 =cut
51  
52 2 our @ISA = qw( Exporter );
53 2 our @EXPORT = ();
54 2 our @EXPORT_OK = qw(
55 is_valid_module_name
56 module_is_loaded
57 find_installed
58 all_installed
59 find_in_namespace
60 module_path
61 module_fs_path
62 module_path_parts
63 path_to_module
64 fs_path_to_module
65 canonical_module_name
66 module_name_parts
67 );
68  
69 2 our %EXPORT_TAGS = (
70 all => [ @EXPORT_OK ]
71 );
72  
73 2 my $SEPARATOR = qr/ :: | ' /x;
74  
75 # leading underscores are technically valid as module names
76 # but no CPAN module has one.
77 2 our $module_re = qr/[[:alpha:]_] \w* (?: $SEPARATOR \w+ )*/xo;
78  
79 =head2 is_valid_module_name
80  
81 $bool = is_valid_module_name($module)
82  
83 Returns true if $module looks like a module name, false otherwise.
84  
85 =cut
86  
87 45 ▶sub is_valid_module_name ($) {
Subroutine is_valid_module_name: called CC=1 SCAR=0.0
Pod documented
88 45 my $module = shift;
89  
90 45 return $module =~ /\A $module_re \z/xo;
91 }
92  
93 =head2 module_is_loaded
94  
95 $abs_path_or_hook = module_is_loaded($module)
96  
97 Returns the %INC entry for the given module. This is usually the absolute path
98 of the module, but sometimes it is the hook object that loaded it.
99  
100 See perldoc -f require
101  
102 Equivalent to:
103  
104 $INC{module_path($module)};
105  
106 Except that invalid module names simply return false without generating
107 warnings.
108  
109 =cut
110  
111 2 ▶sub module_is_loaded ($) {
Subroutine module_is_loaded: called CC=2 SCAR=6.9
Pod documented
112 2 my $module = shift;
113  
114 2 ▶ my $path = module_path($module) or return;
Branch: 1 branch
BranchTrueFalseTotal
my $path = &module_path($module) or return 1 1 2
115  
116 1 return $INC{$path};
117 }
118  
119 =head2 find_installed
120  
121 $path = find_installed($module, [@inc])
122  
123 Returns the first found installed location of the given module. This is always
124 an absolute filesystem path, even if it is derived from a relative path in the
125 include list.
126  
127 By default, @INC is searched, but this can be overridden by providing extra
128 arguments.
129  
130 # look in @INC
131 $path = find_installed("Module::Util")
132  
133 # look only in lib and blib/lib, not in @INC
134 $path = find_installed("Module::Util", 'lib', 'blib/lib')
135  
136 Note that this will ignore any references in the search path, so it doesn't
137 necessarily follow that the module cannot be successfully C<require>d if this
138 returns nothing.
139  
140 =cut
141  
142 9 ▶sub find_installed ($;@) {
Subroutine find_installed: called CC=4 SCAR=13.9
Pod documented
143 9 my $module = shift;
144 9 ▶ my @inc = @_ ? @_ : @INC;
Branch: 1 branch
BranchTrueFalseTotal
@_ ? : 2 7 9
145  
146 9 for my $path (_abs_paths($module, @inc)) {
147 6 ▶ return $path if -e $path;
Branch: 1 branch
BranchTrueFalseTotal
if -e $path 3 3 6
148 }
149  
150 6 return;
151 }
152  
153 =head2 all_installed
154  
155 @paths = all_installed($module, [@inc])
156  
157 Like find_installed, but will return multiple results if the module is installed
158 in multiple locations.
159  
160 =cut
161  
162 2 ▶sub all_installed ($;@) {
Subroutine all_installed: called CC=2 SCAR=6.9
Pod documented
163 2 my $module = shift;
164 2 ▶ my @inc = @_ ? @_ : @INC;
Branch: 1 branch
BranchTrueFalseTotal
@_ ? : 1 1 2
165  
166 2 return grep { -e } _abs_paths($module, @inc);
167 }
168  
169 =head2 find_in_namespace
170  
171 @modules = find_in_namespace($namespace, [ @inc ])
172  
173 Searches for modules under a given namespace in the search path (@INC by
174 default).
175  
176 find_in_namespace("My::Namespace");
177  
178 Returns unique installed module names under the namespace. Note that this does
179 not include the passed-in name, even if it is the name of an installed module.
180  
181 Use of an empty string as the namespace returns all modules in @inc.
182  
183 =cut
184  
185 7 ▶sub find_in_namespace ($;@) {
Subroutine find_in_namespace: called CC=6 SCAR=17.9
Pod documented
186 7 my $ns = shift;
187 7 ▶ my @inc = @_ ? @_ : @INC;
Branch: 1 branch
BranchTrueFalseTotal
@_ ? : 3 4 7
188 7 my (@out, $ns_path);
189  
190 7 ▶ if ($ns ne '') {
Branch: 1 branch
BranchTrueFalseTotal
if ($ns ne '') { } 5 2 7
191 5 ▶ $ns_path = module_fs_path($ns) or return;
Branch: 1 branch
BranchTrueFalseTotal
$ns_path = &module_fs_path($ns) or return 1 4 5
192 1 $ns_path =~ s/\.pm\z//;
193 }
194 else {
195 2 $ns_path = '';
196 }
197  
198 3 for my $root (@inc) {
199 3 my $ns_root = rel2abs($ns_path, $root);
200  
201 3 for my $path (_find_modules($ns_root)) {
202 3 my $rel_path = abs2rel($path, rel2abs($root));
203 3 push @out, fs_path_to_module($rel_path);
204 }
205 }
206  
207 3 my %seen;
208 3 return grep { !$seen{$_}++ } @out;
209 }
210  
211 3 ▶sub _find_modules {
Subroutine _find_modules: called CC=1 SCAR=0.0
212 3 my @roots = @_;
213  
214 # versions of File::Find from earlier perls don't have this feature
215 2 ▶ BEGIN { unimport warnings qw( File::Find ) if $] >= 5.008 }
Subroutine BEGIN: called CC=2 SCAR=7.6
Branch: 1 branch
BranchTrueFalseTotal
if $] >= "5.008" 2 0 2
216  
217 3 my @out;
218 File::Find::find({
219 no_chdir => 1,
220 7 ▶ wanted => sub { push @out, $_ if -f $_ && /\.pm\z/ }
Subroutine __ANON__: called CC=3 SCAR=11.1
Branch: 1 branch
BranchTrueFalseTotal
if -f $_ and /\.pm\z/ 3 4 7
Condition66%2/3
-f $_ and /\.pm\z/
!ll&&!rl&&r
403
MC/DC50%1/2
-f $_ and /\.pm\z/
-f $_ /\.pm\z/
Truth table66%2/3
A and B
A= -f $_B= /\.pm\z/
ABresult
0X0
100
111
221 3 }, @roots);
222  
223 3 return @out;
224 }
225  
226 # munge a module name into multiple possible installed locations
227 11 ▶sub _abs_paths {
Subroutine _abs_paths: called CC=2 SCAR=6.9
228 11 my ($module, @inc) = @_;
229  
230 11 ▶ my $path = module_fs_path($module) or return;
Branch: 1 branch
BranchTrueFalseTotal
my $path = &module_fs_path($module) or return 5 6 11
231  
232 return
233 23 map { rel2abs($path, $_) }
234 5 grep { !ref }
235 @inc;
236 }
237  
238 =head2 module_path
239  
240 $path = module_path($module)
241  
242 Returns a relative path in the form used in %INC. Which I am led to believe is
243 always a unix file path, regardless of the platform.
244  
245 If the argument is not a valid module name, nothing is returned.
246  
247 =cut
248  
249 8 ▶sub module_path ($) {
Subroutine module_path: called CC=2 SCAR=6.9
Pod documented
250 8 my $module = shift;
251  
252 8 ▶ my @parts = module_path_parts($module) or return;
Branch: 1 branch
BranchTrueFalseTotal
my(@parts) = &module_path_parts($module) or return 2 6 8
253  
254 2 return join('/', @parts);
255 }
256  
257 =head2 module_fs_path
258  
259 $path = module_fs_path($module)
260  
261 Like module_path, but returns the path in the native filesystem format.
262  
263 On unix systems, this should be identical to module_path.
264  
265 =cut
266  
267 22 ▶sub module_fs_path ($) {
Subroutine module_fs_path: called CC=2 SCAR=6.9
Pod documented
268 22 my $module = shift;
269  
270 22 ▶ my @parts = module_path_parts($module) or return;
Branch: 1 branch
BranchTrueFalseTotal
my(@parts) = &module_path_parts($module) or return 8 14 22
271  
272 8 return catfile(@parts);
273 }
274  
275 =head2 path_to_module
276  
277 $module = path_to_module($path)
278  
279 Transforms a relative unix file path into a module name.
280  
281 # Print loaded modules as module names instead of paths:
282 print join("\n", map { path_to_module($_) } keys %INC
283  
284 Returns undef if the resulting module name is not valid.
285  
286 =cut
287  
288 3 ▶sub path_to_module {
Subroutine path_to_module: called CC=1 SCAR=0.0
Pod documented
289 3 my $path = shift;
290  
291 3 return _join_parts(split('/', $path));
292 }
293  
294 =head2 fs_path_to_module
295  
296 $module = fs_path_to_module($fs_path)
297  
298 Transforms relative filesystem paths into module names.
299  
300 # on windows:
301 fs_path_to_module("Module\\Util.pm")
302 # returns Module::Util
303  
304 Returns undef if the resulting module is not valid.
305  
306 =cut
307  
308 4 ▶sub fs_path_to_module {
Subroutine fs_path_to_module: called CC=1 SCAR=0.0
Pod documented
309 4 my $path = shift;
310  
311 4 my (undef, $dir, $file) = splitpath($path);
312 4 my @dirs = grep { length } splitdir($dir);
313  
314 4 return _join_parts(@dirs, $file);
315 }
316  
317 # opposite of module_path_parts, keep private
318 7 ▶sub _join_parts {
Subroutine _join_parts: called CC=3 SCAR=11.0
319 7 my @parts = @_;
320 7 ▶ $parts[-1] =~ s/\.pm\z// or return;
Branch: 1 branch
BranchTrueFalseTotal
$parts[-1] =~ s/\.pm\z// or return 6 1 7
321 6 my $module = join('::', @parts);
322 6 ▶ return unless is_valid_module_name($module);
Branch: 1 branch
BranchTrueFalseTotal
unless &is_valid_module_name($module) 1 5 6
323 5 return $module;
324 }
325  
326 =head2 module_path_parts
327  
328 @parts = module_path_parts($module_name)
329  
330 Returns the module name split into parts suitable for feeding to
331 File::Spec->catfile.
332  
333 module_path_parts('Module::Util')
334 # returns ('Module', 'Util.pm')
335  
336 If the module name is invalid, nothing is returned.
337  
338 =cut
339  
340 31 ▶sub module_path_parts ($) {
Subroutine module_path_parts: called CC=2 SCAR=6.9
Pod documented
341 31 my $module = shift;
342  
343 31 ▶ my @parts = module_name_parts($module) or return;
Branch: 1 branch
BranchTrueFalseTotal
my(@parts) = &module_name_parts($module) or return 11 20 31
344 11 $parts[-1] .= '.pm';
345  
346 11 return @parts;
347 }
348  
349 =head2 canonical_module_name
350  
351 $module = canonical_module_name($module);
352  
353 Returns the canonical module name for the given module. This basically consists
354 of eliminating any apostrophe symbols and replacing them with '::'.
355  
356 canonical_module_name("Acme::Don't"); # Acme::Don::t
357  
358 Returns undef if the name is not valid.
359  
360 =cut
361  
362 33 ▶sub canonical_module_name ($) {
Subroutine canonical_module_name: called CC=2 SCAR=6.9
Pod documented
363 33 my $module = shift;
364  
365 33 ▶ return unless is_valid_module_name($module);
Branch: 1 branch
BranchTrueFalseTotal
unless &is_valid_module_name($module) 20 13 33
366  
367 # $module = _join_parts(module_path_parts($module));
368 13 $module =~ s/'/::/g;
369  
370 13 return $module;
371 }
372  
373 =head2 module_name_parts
374  
375 @parts = module_name_parts($module);
376  
377 Returns a list of name parts for the given module.
378  
379 module_name_parts('Acme::Example); # ('Acme', 'Example')
380  
381 =cut
382  
383 32 ▶sub module_name_parts ($) {
Subroutine module_name_parts: called CC=2 SCAR=6.9
Pod documented
384 32 my $module = shift;
385  
386 32 ▶ $module = canonical_module_name($module) or return;
Branch: 1 branch
BranchTrueFalseTotal
$module = &canonical_module_name($module) or return 12 20 32
387  
388 12 return split($SEPARATOR, $module);
389 }
390  
391 2 1;
392  
393 __END__
↑ Summary