blib/lib/Module/Find.pm

filter: Statementstmt 100% 78 / 78 Branchbran 88.4% 23 / 26 Conditioncond 72.7% 8 / 11 MC/DCmcdc 50.0% 3 / 6 Subroutinesub 100% 14 / 14 Podpod 100% 7 / 7 totaltotal 93.6% 133 / 142 CC 21 SCAR 16.3
CC
21
Cov
95%
_find
9.1
_wanted
7.0
usesub
4.0
CRAP 5.1
↑ Summary
1 package Module::Find;
2  
3 13 ▶use 5.008001;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 13 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 13 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 13 ▶use File::Spec;
Subroutine BEGIN: called CC=1 SCAR=0.0
8 13 ▶use File::Find;
Subroutine BEGIN: called CC=1 SCAR=0.0
9  
10 13 our $VERSION = '0.17';
11  
12 13 our $basedir = undef;
13 13 our @results = ();
14 13 our $prune = 0;
15 13 our $followMode = 1;
16  
17 13 our @ISA = qw(Exporter);
18  
19 13 our @EXPORT = qw(findsubmod findallmod usesub useall setmoduledirs);
20  
21 13 our @EXPORT_OK = qw(followsymlinks ignoresymlinks);
22  
23 =encoding utf-8
24  
25 =head1 NAME
26  
27 Module::Find - Find and use installed modules in a (sub)category
28  
29 =head1 SYNOPSIS
30  
31 use Module::Find;
32  
33 # use all modules in the Plugins/ directory
34 @found = usesub Mysoft::Plugins;
35  
36 # use modules in all subdirectories
37 @found = useall Mysoft::Plugins;
38  
39 # find all DBI::... modules
40 @found = findsubmod DBI;
41  
42 # find anything in the CGI/ directory
43 @found = findallmod CGI;
44
45 # set your own search dirs (uses @INC otherwise)
46 setmoduledirs(@INC, @plugindirs, $appdir);
47
48 # not exported by default
49 use Module::Find qw(ignoresymlinks followsymlinks);
50
51 # ignore symlinks
52 ignoresymlinks();
53
54 # follow symlinks (default)
55 followsymlinks();
56  
57 =head1 DESCRIPTION
58  
59 Module::Find lets you find and use modules in categories. This can be very
60 useful for auto-detecting driver or plugin modules. You can differentiate
61 between looking in the category itself or in all subcategories.
62  
63 If you want Module::Find to search in a certain directory on your
64 harddisk (such as the plugins directory of your software installation),
65 make sure you modify C<@INC> before you call the Module::Find functions.
66  
67 =head1 FUNCTIONS
68  
69 =over
70  
71 =item C<setmoduledirs(@directories)>
72  
73 Sets the directories to be searched for modules. If not set, Module::Find
74 will use @INC. If you use this function, @INC will I<not> be included
75 automatically, so add it if you want it. Set to undef to revert to
76 default behaviour.
77  
78 =cut
79  
80 6 ▶sub setmoduledirs {
Subroutine setmoduledirs: called CC=1 SCAR=0.0
Pod documented
81 6 return @Module::Find::ModuleDirs = grep { defined } @_;
82 }
83  
84 =item C<@found = findsubmod Module::Category>
85  
86 Returns modules found in the Module/Category subdirectories of your perl
87 installation. E.g. C<findsubmod CGI> will return C<CGI::Session>, but
88 not C<CGI::Session::File> .
89  
90 =cut
91  
92 10 ▶sub findsubmod(*) {
Subroutine findsubmod: called CC=1 SCAR=0.0
Pod documented
93 10 $prune = 1;
94
95 10 return _find($_[0]);
96 }
97  
98 =item C<@found = findallmod Module::Category>
99  
100 Returns modules found in the Module/Category subdirectories of your perl
101 installation. E.g. C<findallmod CGI> will return C<CGI::Session> and also
102 C<CGI::Session::File> .
103  
104 =cut
105  
106 10 ▶sub findallmod(*) {
Subroutine findallmod: called CC=1 SCAR=0.0
Pod documented
107 10 $prune = 0;
108
109 10 return _find($_[0]);
110 }
111  
112 =item C<@found = usesub Module::Category>
113  
114 Uses and returns modules found in the Module/Category subdirectories of your perl
115 installation. E.g. C<usesub CGI> will return C<CGI::Session>, but
116 not C<CGI::Session::File> .
117  
118 If any module dies during loading, usesub will also die at this point.
119  
120 =cut
121  
122 4 ▶sub usesub(*) {
Subroutine usesub: called CC=4 SCAR=13.9
Pod documented
123 4 $prune = 1;
124
125 4 my @r = _find($_[0]);
126  
127 4 ▶ local @INC = @Module::Find::ModuleDirs
Branch: 1 branch
BranchTrueFalseTotal
if @Module::Find::ModuleDirs 1 3 4
128 if (@Module::Find::ModuleDirs);
129
130 4 foreach my $m (@r) {
131 4 eval " require $m; import $m ; ";
132 4 ▶ die $@ if $@;
Branch: 1 branch
BranchTrueFalseTotal
if $@ 1 3 4
133 }
134
135 3 return @r;
136 }
137  
138 =item C<@found = useall Module::Category>
139  
140 Uses and returns modules found in the Module/Category subdirectories of your perl installation. E.g. C<useall CGI> will return C<CGI::Session> and also
141 C<CGI::Session::File> .
142  
143 If any module dies during loading, useall will also die at this point.
144  
145 =cut
146  
147 6 ▶sub useall(*) {
Subroutine useall: called CC=4 SCAR=13.9
Pod documented
148 6 $prune = 0;
149
150 6 my @r = _find($_[0]);
151
152 6 ▶ local @INC = @Module::Find::ModuleDirs
Branch: 1 branch
BranchTrueFalseTotal
if @Module::Find::ModuleDirs 1 5 6
153 if (@Module::Find::ModuleDirs);
154
155 6 foreach my $m (@r) {
156 10 eval " require $m; import $m; ";
157 10 ▶ die $@ if $@;
Branch: 1 branch
BranchTrueFalseTotal
if $@ 1 9 10
158 }
159
160 5 return @r;
161 }
162  
163 # 'wanted' functions for find()
164 # you know, this would be a nice application for currying...
165 77 ▶sub _wanted {
Subroutine _wanted: called CC=7 SCAR=19.5
166 77 my $name = File::Spec->abs2rel($_, $basedir);
167 77 ▶ return unless $name && $name ne File::Spec->curdir() && substr($name, 0, 1) ne '.';
Branch: 1 branch
BranchTrueFalseTotal
unless $name and $name ne "File::Spec"->curdir and substr($name, 0, 1) ne "." 25 52 77
Condition66%4/6
$name and $name ne "File::Spec"->curdir and substr($name, 0, 1) ne "."
!ll&&!rl&&r
25052
$name and $name ne "File::Spec"->curdir
!ll&&!rl&&r
02552
MC/DC33%1/3
$name and $name ne "File::Spec"->curdir and substr($name, 0, 1) ne "."
$name $name ne "File::Spec"->curdir substr($name, 0, 1) ne "."
Truth table50%2/4
A and B and C
A= $nameB= $name ne "File::Spec"->curdirC= substr($name, 0, 1) ne "."
ABCresult
0XX0
10X0
1100
1111
168  
169 52 ▶ if (-d && $prune) {
Branch: 1 branch
BranchTrueFalseTotal
if (-d $_ and $Module::Find::prune) 9 43 52
Condition100%3/3
-d $_ and $Module::Find::prune
!ll&&!rl&&r
33109
MC/DC100%2/2
-d $_ and $Module::Find::prune
-d $_ $Module::Find::prune
Truth table100%3/3
A and B
A= -d $_B= $Module::Find::prune
ABresult
0X0
100
111
170 9 $File::Find::prune = 1;
171 9 return;
172 }
173  
174 43 ▶ return unless /\.pm$/;
Branch: 1 branch
BranchTrueFalseTotal
unless /\.pm$/ 10 33 43
175  
176 33 $name =~ s|\.pm$||;
177 33 $name = join('::', File::Spec->splitdir($name));
178  
179 33 push @results, $name;
180 }
181  
182  
183 # helper functions for finding files
184  
185 30 ▶sub _find(*) {
Subroutine _find: called CC=9 SCAR=22.1
186 30 my ($category) = @_;
187 30 ▶ return undef unless defined $category;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $category 0 30 30
188  
189 30 my $dir = File::Spec->catdir(split(/::|'/, $category));
190  
191 30 @results = ();
192  
193 30 ▶ foreach my $inc (@Module::Find::ModuleDirs ? @Module::Find::ModuleDirs : @INC) {
Branch: 1 branch
BranchTrueFalseTotal
@Module::Find::ModuleDirs ? : 7 23 30
194 190 ▶ if (ref $inc) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $inc) { } 1 189 190
195 1 ▶ if (my @files = eval { $inc->files }) {
Branch: 1 branch
BranchTrueFalseTotal
if (my(@files) = eval { do { $inc->files } }) 1 0 1
196 push @results,
197 1 ▶ map { s/^\Q$category\E::// ? $_ : () }
Branch: 1 branch
BranchTrueFalseTotal
s/^\Q$category\E::// ? : 1 0 1
198 1 map { s{/}{::}g; s{\.pm$}{}; $_ }
199 1 grep { /\.pm$/ }
200 @files;
201 }
202 }
203 else {
204 189 our $basedir = File::Spec->catdir($inc, $dir);
205  
206 189 ▶ next unless -d $basedir;
Branch: 1 branch
BranchTrueFalseTotal
unless -d $Module::Find::basedir 164 25 189
207 25 find({wanted => \&_wanted,
208 no_chdir => 1,
209 follow => $followMode}, $basedir);
210 }
211 }
212  
213 # filter duplicate modules
214 30 my %seen = ();
215 30 @results = grep { not $seen{$_}++ } @results;
216  
217 30 @results = map "$category\::$_", @results;
218  
219 @results = map {
220 30 ▶ ($_ =~ m{^(\w+(?:(?:::|')\w+)*)$})[0] || die "$_ does not look like a package name"
Condition50%1/2
($_ =~ /^(\w+(?:(?:::|')\w+)*)$/)[0] || die("$_ does not look like a package name")
l!l
320
MC/DC0%0/1
($_ =~ /^(\w+(?:(?:::|')\w+)*)$/)[0] || die("$_ does not look like a package name")
($_ =~ /^(\w+(?:(?:::|')\w+)*)$/)[0]
Truth table50%1/2
A
A= ($_ =~ /^(\w+(?:(?:::|')\w+)*)$/)[0]
Aresult
11
00
221 } @results;
222  
223 30 return @results;
224 }
225  
226 =item C<ignoresymlinks()>
227  
228 Do not follow symlinks. This function is not exported by default.
229  
230 =cut
231  
232 1 ▶sub ignoresymlinks {
Subroutine ignoresymlinks: called CC=1 SCAR=0.0
Pod documented
233 1 $followMode = 0;
234 }
235  
236 =item C<followsymlinks()>
237  
238 Follow symlinks (default behaviour). This function is not exported by default.
239  
240 =cut
241  
242 1 ▶sub followsymlinks {
Subroutine followsymlinks: called CC=1 SCAR=0.0
Pod documented
243 1 $followMode = 1;
244 }
245  
246 =back
247  
248 =head1 HISTORY
249  
250 =over 8
251  
252 =item 0.01, 2004-04-22
253  
254 Original version; created by h2xs 1.22
255  
256 =item 0.02, 2004-05-25
257  
258 Added test modules that were left out in the first version. Thanks to
259 Stuart Johnston for alerting me to this.
260  
261 =item 0.03, 2004-06-18
262  
263 Fixed a bug (non-localized $_) by declaring a loop variable in use functions.
264 Thanks to Stuart Johnston for alerting me to this and providing a fix.
265  
266 Fixed non-platform compatibility by using File::Spec.
267 Thanks to brian d foy.
268  
269 Added setmoduledirs and updated tests. Idea shamelessly stolen from
270 ...errm... inspired by brian d foy.
271  
272 =item 0.04, 2005-05-20
273  
274 Added POD tests.
275  
276 =item 0.05, 2005-11-30
277  
278 Fixed issue with bugfix in PathTools-3.14.
279  
280 =item 0.06, 2008-01-26
281  
282 Module::Find now won't report duplicate modules several times anymore (thanks to Uwe Völker for the report and the patch)
283  
284 =item 0.07, 2009-09-08
285  
286 Fixed RT#38302: Module::Find now follows symlinks by default (can be disabled).
287  
288 =item 0.08, 2009-09-08
289  
290 Fixed RT#49511: Removed Mac OS X extended attributes from distribution
291  
292 =item 0.09, 2010-02-26
293  
294 Fixed RT#38302: Fixed META.yml generation (thanks very much to cpanservice for the help).
295  
296 =item 0.10, 2010-02-26
297  
298 Fixed RT#55010: Removed Unicode BOM from Find.pm.
299  
300 =item 0.11, 2012-05-22
301  
302 Fixed RT#74251: defined(@array) is deprecated under Perl 5.15.7.
303 Thanks to Roman F, who contributed the implementation.
304  
305 =item 0.12, 2014-02-08
306  
307 Fixed RT#81077: useall fails in taint mode
308 Thanks to Aran Deltac, who contributed the implementation and test.
309  
310 Fixed RT#83596: Documentation doesn't describe behaviour if a module fails to load
311 Clarified documentation for useall and usesub.
312  
313 Fixed RT#62923: setmoduledirs(undef) doesn't reset to searching @INC
314 Added more explicit tests.
315 Thanks to Colin Robertson for his input.
316  
317 =item 0.13, 2015-03-09
318  
319 This release contains two contributions from Moritz Lenz:
320  
321 Link to Module::Pluggable and Class::Factory::Util in "SEE ALSO"
322  
323 Align package name parsing with how perl does it (allowing single quotes as module separator)
324  
325 Also, added a test for meta.yml
326  
327 =item 0.14, 2019-12-25
328  
329 A long overdue update. Thank you for the many contributions!
330  
331 Fixed RT#99055: Removed file readability check (pull request contributed by Moritz Lenz)
332  
333 Now supports @INC hooks (pull request contributed by Graham Knop)
334  
335 Now filters out filenames starting with a dot (pull request contributed by Desmond Daignault)
336  
337 Now uses strict (pull request contributed by Shlomi Fish)
338  
339 Fixed RT#122016: test/ files show up in metacpan (bug report contributed by Karen Etheridge)
340  
341 =item 0.15, 2019-12-26
342  
343 Fixed RT#127657 (bug report contributed by Karen Etheridge): Module::Find now uses @ModuleDirs
344 (if specified) for loading modules. Previously, when using setmoduledirs() to set an array of
345 directories that did not contain @INC, Module::Find would find the modules correctly, but load
346 them from @INC.
347  
348 =item 0.16, 2022-08-01
349  
350 Fixes an issue where symlink tests failed on systems that do not support creation of symlinks.
351 The issue appears on Windows systems due to changed behaviour in C<File::Find> described
352 in L<perl5/issue #19995|https://github.com/Perl/perl5/issues/19995>
353 Symlink tests were previously skipped if C<symlink()> is not available, and now
354 also if creation of a symlink is not possible.
355  
356 Fixes L<issue #9|https://github.com/crenz/Module-Find/issues/9>. Note that on Windows system,
357 the patch to C<File::Find> from L<perl5/PR #20008|https://github.com/Perl/perl5/pull/20008>
358 will be required for proper operation.
359  
360 =item 0.17, 2025-02-16
361  
362 Fixes L<issue 13|https://github.com/crenz/Module-Find/issues/13> / L<148978|https://rt.cpan.org/Ticket/Display.html?id=148978>
363 where warnings where produced upon extracting the installation archive, which prevented installation under cpanm and other tools.
364  
365 =back
366  
367 =head1 DEVELOPMENT NOTES
368  
369 The development repository for this module is hosted on GitHub: L<http://github.com/crenz/Module-Find/>. Please report any bugs by opening an issue there.
370  
371 =head1 SEE ALSO
372  
373 L<perl>, L<Module::Pluggable>, L<Class::Factory::Util>
374  
375 =head1 AUTHOR
376  
377 Christian Renz, E<lt>crenz@web42.comE<gt>
378  
379 =head1 COPYRIGHT AND LICENSE
380  
381 Copyright 2004-2025 by Christian Renz <crenz@web42.com>. All rights reserved.
382  
383 This library is free software; you can redistribute it and/or modify
384 it under the same terms as Perl itself.
385  
386 =cut
387  
388 13 1;
↑ Summary