blib/lib/App/PrereqGrapher.pm

filter: Statementstmt 80.9% 98 / 121 Branchbran 53.4% 31 / 58 Conditioncond 52.9% 9 / 17 MC/DCmcdc 27.2% 3 / 11 Subroutinesub 66.6% 16 / 24 Podpod 20.0% 1 / 5 totaltotal 66.9% 158 / 236 CC 39 SCAR 27.3
CC
39
Cov
70%
is_core
30.0
parse_options
24.2
generate_graph
22.2
CRAP 15.4
↑ Summary bin/prereq-grapher »
1 package App::PrereqGrapher;
2 2 $App::PrereqGrapher::VERSION = '0.14';
3 #
4 # ABSTRACT: generate dependency graph using Perl::PrereqScanner
5 #
6  
7 2 ▶use 5.006;
Subroutine BEGIN: called CC=1 SCAR=0.0
8 2 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
9 2 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
10  
11 2 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
12 2 ▶use Moo;
Subroutine BEGIN: called CC=1 SCAR=0.0
13 2 ▶use Perl::PrereqScanner;
Subroutine BEGIN: called CC=1 SCAR=0.0
14 2 ▶use Getopt::Long qw/:config no_ignore_case/;
Subroutine BEGIN: called CC=1 SCAR=0.0
15 2 ▶use Graph::Easy;
Subroutine BEGIN: called CC=1 SCAR=0.0
16 2 ▶use Module::Path qw(module_path);
Subroutine BEGIN: called CC=1 SCAR=0.0
17 2 ▶use Module::CoreList;
Subroutine BEGIN: called CC=1 SCAR=0.0
18  
19 my %formats =
20 (
21 3 ▶ 'dot' => sub { $_[0]->as_graphviz; },
Subroutine __ANON__: called CC=1 SCAR=0.0
22 0 ▶ 'svg' => sub { $_[0]->as_svg; },
Subroutine __ANON__: not called CC=1 SCAR=6.9
23 0 ▶ 'gml' => sub { $_[0]->as_graphml; },
Subroutine __ANON__: not called CC=1 SCAR=6.9
24 0 ▶ 'vcg' => sub { $_[0]->as_vcg; },
Subroutine __ANON__: not called CC=1 SCAR=6.9
25 0 ▶ 'html' => sub { $_[0]->as_html_file; },
Subroutine __ANON__: not called CC=1 SCAR=6.9
26 2 );
27  
28 has format => (
29 is => 'ro',
30 3 ▶ isa => sub { croak "valid formats: ", join(", ", keys %formats), "\n" unless exists $formats{$_[0]}; },
Subroutine __ANON__: called CC=2 SCAR=7.6
Branch: 1 branch
BranchTrueFalseTotal
unless exists $formats{$_[0]} 0 3 3
31 0 ▶ default => sub { return 'dot'; },
Subroutine __ANON__: not called CC=1 SCAR=6.9
32 2 );
33  
34 2 has output_file => (
35 is => 'ro',
36 );
37  
38 2 has no_core => (
39 is => 'ro',
40 );
41  
42 2 has no_recurse_core => (
43 is => 'ro',
44 );
45  
46 2 has verbose => (
47 is => 'ro',
48 );
49  
50 has depth => (
51 is => 'ro',
52 1 ▶ isa => sub { croak "depth must be an integer\n" unless $_[0] =~ /^\d+$/; },
Subroutine __ANON__: called CC=2 SCAR=7.6
Branch: 1 branch
BranchTrueFalseTotal
unless $_[0] =~ /^\d+$/ 0 1 1
53 2 );
54  
55 has timeout => (
56 is => 'ro',
57 0 ▶ isa => sub { croak "timeout must be an integer\n" unless $_[0] =~ /^\d+$/; },
Subroutine __ANON__: not called CC=2 SCAR=17.9
Branch: 1 branch
BranchTrueFalseTotal
unless $_[0] =~ /^\d+$/ 0 0 0
58 2 );
59  
60 sub new_with_options
61 1 ▶{
Subroutine new_with_options: called CC=1 SCAR=0.0
Pod undocumented
62 1 my $class = shift;
63 1 my %options = $class->parse_options();
64 1 my $instance = $class->new(%options, @_);
65  
66 1 return $instance;
67 }
68  
69 sub parse_options
70 1 ▶{
Subroutine parse_options: called CC=13 SCAR=31.9
Pod undocumented
71 1 my $class = shift;
72 1 my %options;
73 my %format;
74  
75 GetOptions(
76 'h|help' => \$options{'help'},
77 'd|depth=i' => \$options{'depth'},
78 't|timeout=i' => \$options{'timeout'},
79 'o|output-file=s' => \$options{'output_file'},
80 'nc|no-core' => \$options{'no_core'},
81 'nrc|no-recurse-core' => \$options{'no_recurse_core'},
82 'v|verbose' => \$options{'verbose'},
83 'dot' => \$format{'dot'},
84 'svg' => \$format{'svg'},
85 'gml' => \$format{'gml'},
86 'vcg' => \$format{'vcg'},
87 1 ▶ 'html' => \$format{'html'},
Branch: 1 branch
BranchTrueFalseTotal
&GetOptions("h|help", \$options{"help"}, "d|depth=i", \$options{"depth"}, "t|timeout=i", \$options{"timeout"}, "o|output-file=s", \$options{"output_file"}, "nc|no-core", \$options{"no_core"}, "nrc|no-recurse-core", \$options{"no_recurse_core"}, "v|verbose", \$options{"verbose"}, "dot", \$format{"dot"}, "svg", \$format{"svg"}, "gml", \$format{"gml"}, "vcg", \$format{"vcg"}, "html", \$format{"html"}) or croak("Can't get options.") 1 0 1
88 ) || croak "Can't get options.";
89 1 ▶ usage() if $options{'help'};
Branch: 1 branch
BranchTrueFalseTotal
if $options{"help"} 0 1 1
90  
91 1 foreach my $format (keys %formats) {
92 5 ▶ delete $format{$format} unless $format{$format};
Branch: 1 branch
BranchTrueFalseTotal
unless $format{$format} 4 1 5
93 }
94 1 ▶ if (keys %format > 1) {
Branch: 1 branch
BranchTrueFalseTotal
if (keys %format > 1) 0 1 1
95 0 print "FORMAT: ", join(', ', keys %format), "\n";
96 0 croak "you can only specify at most ONE output format (default is 'dot')";
97 }
98 1 ▶ if ($format{svg}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($format{"svg"}) 0 1 1
99 0 eval {
100 0 require Graph::Easy::As_svg;
101 };
102 0 ▶ if ($@) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 0 0 0
103 0 croak "You don't have Graph::Easy::As_svg installed, ",
104 "so I can't generate SVG";
105 }
106 }
107 1 ▶ $format{dot} = 1 unless keys %format == 1;
Branch: 1 branch
BranchTrueFalseTotal
unless keys %format == 1 0 1 1
108  
109 1 ▶ if ($options{no_core} && $options{no_recurse_core}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($options{"no_core"} and $options{"no_recurse_core"}) 0 1 1
Condition33%1/3
$options{"no_core"} and $options{"no_recurse_core"}
!ll&&!rl&&r
100
MC/DC0%0/2
$options{"no_core"} and $options{"no_recurse_core"}
$options{"no_core"} $options{"no_recurse_core"}
Truth table33%1/3
A and B
A= $options{"no_core"}B= $options{"no_recurse_core"}
ABresult
0X0
100
111
110 0 croak "doesn't make sense to specify no-core and no-recurse-core together";
111 }
112  
113 1 for (keys %options) {
114 7 ▶ delete $options{$_} unless defined $options{$_};
Branch: 1 branch
BranchTrueFalseTotal
unless defined $options{$_} 6 1 7
115 }
116 1 $options{format} = (keys %format)[0];
117  
118 1 return %options;
119 }
120  
121 sub generate_graph
122 3 ▶{
Subroutine generate_graph: called CC=20 SCAR=31.0
Pod documented
123 3 my ($self, @inputs) = @_;
124 3 my (@queue, %seen, $scanner, $graph, $module);
125 3 my ($prereqs, $depsref);
126 3 my ($path, $filename, $fh);
127 3 my $module_count = 0;
128 3 my %depth;
129  
130 3 $scanner = Perl::PrereqScanner->new;
131 3 $graph = Graph::Easy->new();
132 3 $graph->timeout($self->timeout);
133  
134 3 @depth{@inputs} = map { 0 } @inputs;
135  
136 3 push(@queue, @inputs);
137 3 ▶ while (@queue > 0) {
Branch: 1 branch
BranchTrueFalseTotal
if (@queue > 0) 124 3 127
138 124 $module = shift @queue;
139 124 ▶ next if $seen{$module};
Branch: 1 branch
BranchTrueFalseTotal
if $seen{$module} 82 42 124
140 42 $seen{$module} = 1;
141  
142 42 ▶ if (defined($path = module_path($module))) {
Branch: 2 branches
BranchTrueFalseTotal
if (defined($path = module_path($module))) { } 40 2 42
elsif (-f $module) { } 0 2 2
143 } elsif (-f $module) {
144 0 $path = $module;
145 } else {
146 2 ▶ carp "can't find $module - keeping calm and carrying on.\n" if $self->verbose;
Branch: 1 branch
BranchTrueFalseTotal
if $self->verbose 0 2 2
147 2 next;
148 }
149  
150 # Huge files (eg currently Perl::Tidy) will cause PPI to barf
151 # So we need to catch those, keep calm, and carry on
152 40 eval { $prereqs = $scanner->scan_file($path); };
153 40 ▶ next if $@;
Branch: 1 branch
BranchTrueFalseTotal
if $@ 0 40 40
154 40 ++$module_count;
155 40 $depsref = $prereqs->as_string_hash();
156 40 foreach my $dep (keys %{ $depsref }) {
157 142 ▶ if (!exists($depth{$dep}) || $depth{$dep} > $depth{$module} + 1) {
Branch: 1 branch
BranchTrueFalseTotal
if (not exists $depth{$dep} or $depth{$dep} > $depth{$module} + 1) 49 93 142
Condition66%2/3
not exists $depth{$dep} or $depth{$dep} > $depth{$module} + 1
l!l&&r!l&&!r
49093
MC/DC50%1/2
not exists $depth{$dep} or $depth{$dep} > $depth{$module} + 1
not exists $depth{$dep} $depth{$dep} > $depth{$module} + 1
Truth table66%2/3
not(A) or B
A= not exists $depth{$dep}B= $depth{$dep} > $depth{$module} + 1
ABresult
1X1
011
000
158 49 $depth{$dep} = $depth{$module} + 1;
159 }
160 142 ▶ if ($self->no_core && is_core($dep)) {
Branch: 2 branches
BranchTrueFalseTotal
if ($self->no_core and is_core($dep)) { } 0 142 142
elsif ($dep eq 'perl') { } 10 132 142
Condition33%1/3
$self->no_core and is_core($dep)
!ll&&!rl&&r
14200
MC/DC0%0/2
$self->no_core and is_core($dep)
$self->no_core is_core($dep)
Truth table33%1/3
A and B
A= $self->no_coreB= is_core($dep)
ABresult
0X0
100
111
161 # don't include core modules
162 } elsif ($dep eq 'perl') {
163 10 $graph->add_edge($module, "perl $depsref->{perl}");
164 } else {
165 132 $graph->add_edge($module, $dep);
166 132 ▶ next if $self->depth && $depth{$dep} >= $self->depth;
Branch: 1 branch
BranchTrueFalseTotal
if $self->depth and $depth{$dep} >= $self->depth 11 121 132
Condition100%3/3
$self->depth and $depth{$dep} >= $self->depth
!ll&&!rl&&r
1101111
MC/DC100%2/2
$self->depth and $depth{$dep} >= $self->depth
$self->depth $depth{$dep} >= $self->depth
Truth table100%3/3
A and B
A= $self->depthB= $depth{$dep} >= $self->depth
ABresult
0X0
100
111
167 121 ▶ push(@queue, $dep) unless $self->no_recurse_core && is_core($dep);
Branch: 1 branch
BranchTrueFalseTotal
unless $self->no_recurse_core and is_core($dep) 121 0 121
Condition33%1/3
$self->no_recurse_core and is_core($dep)
!ll&&!rl&&r
12100
MC/DC0%0/2
$self->no_recurse_core and is_core($dep)
$self->no_recurse_core is_core($dep)
Truth table33%1/3
A and B
A= $self->no_recurse_coreB= is_core($dep)
ABresult
0X0
100
111
168 }
169 }
170 }
171  
172 3 ▶ $filename = $self->output_file || 'dependencies.'.$self->format;
Condition50%1/2
$self->output_file || 'dependencies.' . $self->format
l!l
30
MC/DC0%0/1
$self->output_file || 'dependencies.' . $self->format
$self->output_file
Truth table50%1/2
A
A= $self->output_file
Aresult
11
00
173 3 ▶ open($fh, '>', $filename) ||
Branch: 1 branch
BranchTrueFalseTotal
open $fh, ">", $filename or croak("Failed to write ${filename}: $!\n") 3 0 3
174 croak "Failed to write $filename: $!\n";
175 3 print $fh $formats{$self->format}->($graph);
176 3 close($fh);
177 3 ▶ print STDERR "$module_count modules processed. Graph written to $filename\n" if $self->verbose;
Branch: 1 branch
BranchTrueFalseTotal
if $self->verbose 0 3 3
178 }
179  
180 sub is_core
181 0 ▶{
Subroutine is_core: not called CC=5 SCAR=34.0
Pod undocumented
182 0 my $module = shift;
183 0 ▶ my $version = @_ > 0 ? shift : $^V;
Branch: 1 branch
BranchTrueFalseTotal
@_ > 0 ? : 0 0 0
184  
185 0 ▶ return 0 unless defined(my $first_release = Module::CoreList::first_release($module));
Branch: 1 branch
BranchTrueFalseTotal
unless defined(my $first_release = Module::CoreList::first_release($module)) 0 0 0
186 0 ▶ return 0 unless $version >= $first_release;
Branch: 1 branch
BranchTrueFalseTotal
unless $version >= $first_release 0 0 0
187 0 ▶ return 1 if !defined(my $final_release = Module::CoreList::removed_from($module));
Branch: 1 branch
BranchTrueFalseTotal
unless defined(my $final_release = Module::CoreList::removed_from($module)) 0 0 0
188 0 return $version <= $final_release;
189 }
190  
191 sub usage
192 0 ▶{
Subroutine usage: not called CC=1 SCAR=6.9
Pod undocumented
193 0 require Pod::Usage;
194 0 Pod::Usage::pod2usage();
195 0 exit;
196 }
197  
198 2 1;
199  
200 =head1 NAME
201  
202 App::PrereqGrapher - generate dependency graph using Perl::PrereqScanner
203  
204 =head1 SYNOPSIS
205  
206 use App::PrereqGrapher;
207  
208 my %options = (
209 format => 'dot',
210 no_core => 0,
211 no_recurse_core => 1,
212 output_file => 'prereqs.dot',
213 verbose => 0,
214 );
215 my $grapher = App::PrereqGrapher->new( %options );
216  
217 $grapher->generate_graph('Module::Path');
218  
219 =head1 DESCRIPTION
220  
221 App::PrereqGrapher builds a directed graph of the prereqs or dependencies for
222 a file or module. It uses Perl::PrereqScanner to find the dependencies for the seed,
223 and then repeatedly calls Perl::PrereqScanner on those dependencies, and so on,
224 until all dependencies have been found.
225  
226 It then saves the resulting graph to a file, using one of the five supported formats.
227 The default format is 'dot', the format used by the GraphViz graph drawing toolkit.
228  
229 If your code contains lines like:
230  
231 require 5.006;
232 use 5.006;
233  
234 Then you'll end up with a dependency labelled B<perl 5.006>;
235 this way you can see where you're dependent on modules which
236 require different minimum versions of perl.
237  
238 =head1 METHODS
239  
240 =head2 new
241  
242 The constructor understands the following options:
243  
244 =over 4
245  
246 =item format
247  
248 Select the output format, which must be one of: dot, svg, vcg, gml, or html.
249 See L</"OUTPUT FORMATS"> for more about the supported output formats.
250 If not specified, the default format is 'dot'.
251  
252 =item output_file
253  
254 Specifies the name of the file to write the dependency graph into,
255 including the extension. If not specified, the filename will be C<dependencies>,
256 with the extension set according to the format.
257  
258 =item depth
259  
260 Only generate the graph to the specified depth.
261 If the complete dependency graph is very large, this option may help you get
262 an overview.
263  
264 =item no_core
265  
266 Don't include any modules which are core (included with perl) for the version
267 of perl being used.
268  
269 =item no_recurse_core
270  
271 When a core module is used, include it in the dependency graph,
272 but don't show any of I<its> dependencies.
273  
274 =item timeout
275  
276 Specifies the timeout for Graph::Easy when its laying out the graph.
277 This is mainly relevant for formats like SVG and HTML, where the graph
278 layout is done in Perl. Defaults to 5 seconds.
279  
280 =item verbose
281  
282 Display verbose logging as the grapher runs.
283 Currently this will just tell you if a module was use'd or require'd,
284 but couldn't be found locally.
285  
286 =back
287  
288 =head2 generate_graph
289  
290 Takes one or more seed items. Each item may be a module or the path to a perl file.
291  
292 $grapher->generate_graph('Module::Path', 'Module::Version');
293  
294 It will first try and interpret each item as a module, but if it can't find a module
295 with the given name, it will try and interpret it as a file path.
296 This means that if you have a file called C<strict> for example, then you won't be
297 able to run:
298  
299 $grapher->generate_graph('strict');
300  
301 as it will be interpreted as the module of that name. Put an explicit path to stop this:
302  
303 $grapher->generate_graph('./strict');
304  
305 =head1 OUTPUT FORMATS
306  
307 =over 4
308  
309 =item dot
310  
311 The format used by GraphViz and related tools.
312  
313 =item svg
314  
315 Scalable Vector Graphics (SVG) a W3C standard.
316 You have to install L<Graph::Easy::As_svg> if you want to use this format.
317  
318 =item vcg
319  
320 The VCG or GDL format.
321  
322 =item gml
323  
324 Graph Markup Language, aka GraphML.
325  
326 =item html
327  
328 Generate an HTML format with embedded CSS. I haven't been able to get this to work,
329 but it's one of the formats supported by L<Graph::Easy>.
330  
331 =back
332  
333 =head1 KNOWN BUGS
334  
335 L<Perl::PrereqScanner> uses L<PPI> to parse each item.
336 PPI has a hard-coded limit for the size of file it's prepared to parse
337 (currently just over 1M).
338 This means that very large files will be ignored;
339 for example Perl::Tidy cannot be graphed,
340 and if you try and graph a file that use's Perl::Tidy,
341 then it just won't appear in the graph.
342  
343 If a class isn't defined in its own file,
344 then App::PrereqGrapher won't find it;
345 for example Tie::StdHash is defined inside Tie::Hash.
346 By default these are silently ignored,
347 but if you use the B<-verbose> option you'll get the following warning:
348  
349 can't find Tie::StdHash - keeping calm and carrying on.
350  
351 Perl::PrereqScanner parses code and makes no attempt to
352 determine whether any of it would actually run on your platform.
353 For example, one module might decide at run-time whether to C<require>
354 Foo::Bar or Foo::Baz, and might never use Foo::Baz on your OS.
355 But Perl::PrereqScanner will see both of Foo::Bar and Foo::Baz
356 as pre-reqs.
357  
358 =head1 TODO
359  
360 =over 4
361  
362 =item *
363  
364 Have an option to control what depth we should recurse to?
365 You might only be interested in the dependencies of your code,
366 and their first level of dependencies.
367  
368 =item *
369  
370 Show some indication that we're running. It can take a long time to run
371 if your ultimate dependency graph is very large.
372  
373 =back
374  
375 =head1 SEE ALSO
376  
377 The distribution for this module contains a command-line script,
378 L<prereq-grapher>. It has its own documentation.
379  
380 This module uses L<Perl::PrereqScanner> to parse the source code,
381 and L<Graph::Easy> to generate and save the dependency graph.
382  
383 If you want to generate SVG graphs, you need to have L<Graph::Easy::As_svg> installed.
384  
385 L<http://neilb.org/reviews/dependencies.html>: a review of CPAN modules that can be used
386 to get dependency information.
387  
388 =head1 REPOSITORY
389  
390 L<https://github.com/neilb/App-PrereqGrapher>
391  
392 =head1 AUTHOR
393  
394 Neil Bowers E<lt>neilb@cpan.orgE<gt>
395  
396 =head1 COPYRIGHT AND LICENSE
397  
398 This software is copyright (c) 2012 by Neil Bowers <neilb@cpan.org>.
399  
400 This is free software; you can redistribute it and/or modify it under
401 the same terms as the Perl 5 programming language system itself.
402  
403 =cut
404  
↑ Summary bin/prereq-grapher »