1Perl::Metrics::Simple::UAsnearlyCsoinst:r:iFbiultee(d3P)Peerrll::DMoecturmiecnst:a:tSiiomnple::Analysis::File(3)
2
3
4

NAME

6       Perl::Metrics::Simple::Analysis::File - Methods analyzing a single
7       file.
8

SYNOPSIS

10         use Perl::Metrics::Simple::Analysis::File;
11         my $object = Perl::Metrics::Simple::Analysis::File->new(file => 'path/to/file');
12

VERSION

14       This is VERSION 0.1
15

DESCRIPTION

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
22       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

CLASS METHODS

27   new
28       Takes named parameters, current only the path parameter is recognized:
29
30         my $file_results = BPerl::Metrics::Simple::Analysis::File->new( path => $path );
31
32       Returns a new Perl::Metrics::Simple::Analysis::File object which has
33       been populated with the results of analyzing the file at path.
34
35       Throws an exception if the path is missing or unreadable.
36

OBJECT METHODS

38       Call on an object.
39
40   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
51   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
56         {
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
63   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
70   lines
71       Total non-blank, non-comment, non-pod lines.
72
73   main_stats
74       Returns the hashref generated by analyze_main without re-analyzing
75       document.
76
77   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
81   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
85   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
90   measure_complexity
91       Takes a PPI element and measures an approximation of the McCabe
92       Complexity (aka Cyclomatic Complexity) of the code.
93
94       McCabe Complexity is basically a count of how many paths there are
95       through the code.
96
97       We use a simplified method for counting this, which ignores things like
98       the possibility that a 'use' statement could throw an exception.
99
100       The actual measurement we use for a chunk of code is 1 plus 1 each
101       logic keyword or operator:
102
103       Logic operators:
104
105       The default list is:
106
107       @Perl::Metrics::Simple::Analysis::File::DEFAULT_LOGIC_OPERATORS
108
109           !
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
135       You can supply your own list by setting:
136       @Perl::Metrics::Simple::Analysis::File::LOGIC_OPERATORS before creating
137       a new object.
138
139       Logic keywords:
140
141       @Perl::Metrics::Simple::Analysis::File::DEFAULT_LOGIC_KEYWORDS
142
143           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
157       You can supply your own list by setting:
158       @Perl::Metrics::Simple::Analysis::File::LOGIC_KEYWORDS before creating
159       a new object.
160
161       Method modifiers:
162
163       @Perl::Metrics::Simple::Analysis::File::DEFAULT_METHOD_MODIFIERS
164
165           before
166           after
167           around
168
169       You can supply your own list by setting:
170       @Perl::Metrics::Simple::Analysis::File::METHOD_MODIFIERS before
171       creating a new object.
172
173       Examples of Complexity
174
175       Here are a couple of examples of how we count complexity:
176
177       Example of complexity count of 1:
178
179          use Foo;
180          print "Hello world.\n";
181          exit;
182
183       Example of complexity count of 2:
184
185          if ( $a ) {         # The "if" adds 1.
186              # do something
187          }
188
189       Example of complexity count of 6:
190
191           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
205   packages
206       Arrayref of unique packages found in the file.
207
208   path
209       Either the path to the file, or a scalar ref if that was supplied
210       instaed of a path.
211
212   subs
213       Count of subroutines found.
214

STATIC PACKAGE SUBROUTINES

216       Utility subs used internally, but no harm in exposing them for now.
217
218   hashify
219        %hash = Perl::Metrics::Simple::Analysis::File::hashify(@list);
220
221       Takes an array and returns a hash using the array values as the keys
222       and with the values all set to 1.
223
224   is_hash_key
225        $boolean = Perl::Metrics::Simple::Analysis::File::is_hash_key($ppi_element);
226
227       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
230         { foo => 123, bar => $a }
231
232       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

BUGS AND LIMITATIONS

237       None reported yet ;-)
238

DEPENDENCIES

240       Readonly
241       Perl::Metrics::Simple::Analysis
242

SUPPORT

244       Via CPAN:
245
246   Disussion Forum
247       http://www.cpanforum.com/dist/Perl-Metrics-Simple
248
249   Bug Reports
250       http://rt.cpan.org/NoAuth/Bugs.html?Dist=Perl-Metrics-Simple
251

AUTHOR

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
262       This program is free software; you can redistribute it and/or modify it
263       under the same terms as Perl itself.
264
265       The full text of the license can be found in the LICENSE file included
266       with this module.
267
268
269
270perl v5.28.0                      2015-P0e1r-l0:4:Metrics::Simple::Analysis::File(3)
Impressum