1Perl::Metrics::Simple::UAsnearlyCsoinst:r:iFbiultee(d3P)Peerrll::DMoecturmiecnst:a:tSiiomnple::Analysis::File(3)
2
6 Perl::Metrics::Simple::Analysis::File - Methods analyzing a single
7 file.
8
10 use Perl::Metrics::Simple::Analysis::File;
11 my $object = Perl::Metrics::Simple::Analysis::File->new(file => 'path/to/file');
12
14 This is VERSION 0.1
15
17 A Perl::Metrics::Simple::Analysis::File object is created by
18 Perl::Metrics::Simple for each file analyzed. These objects are
19 aggregated into a Perl::Metrics::Simple::Analysis object by
20 Perl::Metrics::Simple.
21 In general you will not use this class directly, instead you will use
23 Perl::Metrics::Simple, but there's no harm in exposing the various
24 methods this class provides.
25
27 new
28 Takes named parameters, current only the path parameter is recognized:
29 my $file_results = BPerl::Metrics::Simple::Analysis::File->new( path => $path );
31 Returns a new Perl::Metrics::Simple::Analysis::File object which has
33 been populated with the results of analyzing the file at path.
34 Throws an exception if the path is missing or unreadable.
36
38 Call on an object.
39 all_counts
41 Convenience method. Takes no arguments and returns a hashref of all
42 counts:
43 {
44 path => $self->path,
45 lines => $self->lines,
46 main_stats => $self->main_stats,
47 subs => $self->subs,
48 packages => $self->packages,
49 }
50 analyze_main
52 Takes a PPI document and an arrayref of PPI::Statement::Sub objects and
53 returns a hashref with information about the 'main' (non-subroutine)
54 portions of the document:
55 {
57 lines => $lines, # Line count outside subs. Skips comments and pod.
58 mccabe_complexity => $complexity, # Cyclomatic complexity of all non-sub areas
59 path => '/path/to/file',
60 name => '{code not in named subroutines}', # always the same name
61 };
62 get_node_length
64 Takes a PPI node and returns a count of the newlines it contains. PPI
65 normalizes line endings to newlines so CR/LF, CR and LF all come out
66 the same. The line counts reported by the various methods in this class
67 all exclude blank lines, comment lines and pod (the PPI document is
68 pruned before counting.)
69 lines
71 Total non-blank, non-comment, non-pod lines.
72 main_stats
74 Returns the hashref generated by analyze_main without re-analyzing
75 document.
76 logic_keywords
78 Returns an array (in array context) or ref-to-ARRAY of the keywords
79 used in calculating complexity. See Logic Keywords section below.
80 logic_operators
82 Returns an array (in array context) or ref-to-ARRAY of the operators
83 used in calculating complexity. See Logic Operators section below.
84 method_modifiers
86 Returns an array (in array context) or ref-to-ARRAY of the method
87 modifiers considered to return methods during calculating complexity.
88 See Method modifiers section below.
89 measure_complexity
91 Takes a PPI element and measures an approximation of the McCabe
92 Complexity (aka Cyclomatic Complexity) of the code.
93 McCabe Complexity is basically a count of how many paths there are
95 through the code.
96 We use a simplified method for counting this, which ignores things like
98 the possibility that a 'use' statement could throw an exception.
99 The actual measurement we use for a chunk of code is 1 plus 1 each
101 logic keyword or operator:
102 Logic operators:
104 The default list is:
106 @Perl::Metrics::Simple::Analysis::File::DEFAULT_LOGIC_OPERATORS
108 !
110 !~
111 &&
112 &&=
113 //
114 <
115 <<=
116 <=>
117 ==
118 =~
119 >
120 >>=
121 ?
122 and
123 cmp
124 eq
125 gt
126 lt
127 ne
128 not
129 or
130 xor
131 ||
132 ||=
133 ~~
134 You can supply your own list by setting:
136 @Perl::Metrics::Simple::Analysis::File::LOGIC_OPERATORS before creating
137 a new object.
138 Logic keywords:
140 @Perl::Metrics::Simple::Analysis::File::DEFAULT_LOGIC_KEYWORDS
142 else
144 elsif
145 for
146 foreach
147 goto
148 grep
149 if
150 last
151 map
152 next
153 unless
154 until
155 while
156 You can supply your own list by setting:
158 @Perl::Metrics::Simple::Analysis::File::LOGIC_KEYWORDS before creating
159 a new object.
160 Method modifiers:
162 @Perl::Metrics::Simple::Analysis::File::DEFAULT_METHOD_MODIFIERS
164 before
166 after
167 around
168 You can supply your own list by setting:
170 @Perl::Metrics::Simple::Analysis::File::METHOD_MODIFIERS before
171 creating a new object.
172 Examples of Complexity
174 Here are a couple of examples of how we count complexity:
176 Example of complexity count of 1:
178 use Foo;
180 print "Hello world.\n";
181 exit;
182 Example of complexity count of 2:
184 if ( $a ) { # The "if" adds 1.
186 # do something
187 }
188 Example of complexity count of 6:
190 sub foo { # 1: for non-empty code
192 if ( @list ) { # 1: "if"
193 foreach my $x ( @list ) { # 1: "foreach"
194 if ( ! $x ) { # 2: 1 for "if" and 1 for "!"
195 do_something($x);
196 }
197 else { # 1 for "else"
198 do_something_else($x);
199 }
200 }
201 }
202 return;
203 }
204 packages
206 Arrayref of unique packages found in the file.
207 path
209 Either the path to the file, or a scalar ref if that was supplied
210 instaed of a path.
211 subs
213 Count of subroutines found.
214
216 Utility subs used internally, but no harm in exposing them for now.
217 hashify
219 %hash = Perl::Metrics::Simple::Analysis::File::hashify(@list);
220 Takes an array and returns a hash using the array values as the keys
222 and with the values all set to 1.
223 is_hash_key
225 $boolean = Perl::Metrics::Simple::Analysis::File::is_hash_key($ppi_element);
226 Takes a PPI::Element and returns true if the element is a hash key, for
228 example "foo" and "bar" are hash keys in the following:
229 { foo => 123, bar => $a }
231 Copied and somehwat simplified from
233 http://search.cpan.org/src/THALJEF/Perl-Critic-0.19/lib/Perl/Critic/Utils.pm
234 See Perl::Critic::Utils.
235
237 None reported yet ;-)
238
240 Readonly
241 Perl::Metrics::Simple::Analysis
242
244 Via CPAN:
245 Disussion Forum
247 http://www.cpanforum.com/dist/Perl-Metrics-Simple
248 Bug Reports
250 http://rt.cpan.org/NoAuth/Bugs.html?Dist=Perl-Metrics-Simple
251
253 Matisse Enzer
254 CPAN ID: MATISSE
255 Eigenstate Consulting, LLC
256 matisse@eigenstate.net
257 http://www.eigenstate.net/
258
260 Copyright (c) 2006-2009 by Eigenstate Consulting, LLC.
261 This program is free software; you can redistribute it and/or modify it
263 under the same terms as Perl itself.
264 The full text of the license can be found in the LICENSE file included
266 with this module.
267perl v5.32.1 2021-P0e3r-l2:9:Metrics::Simple::Analysis::File(3)