Perl::...s::File(3pm)

💖 Perl::Metrics::Simple::Analysis::File 💖

okay bestie, so this page is Perl::Metrics::Simple::Analysis::File(3pm) — the whole vibe is "I analyze ONE file and tell you everything about it." it's part of the user contributed perl documentation, and she's here to spill the tea on your code's complexity. 🎀

---

✨ SYNOPSIS ✨

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

---

🌸 VERSION 🌸

This is VERSION 0.1 — baby's first version, and she's serving. 💅

---

🦋 DESCRIPTION 🦋

A Perl::Metrics::Simple::Analysis::File object gets created by Perl::Metrics::Simple for each file analyzed. then all those lil objects get aggregated into a Perl::Metrics::Simple::Analysis object by Perl::Metrics::Simple. it's giving family reunion. 🫶

In general you will not use this class directly — you'll use Perl::Metrics::Simple instead. but honestly? there's no harm in exposing the various methods this class provides. live a little. 🌈

---

👑 CLASS METHODS 👑

💜 new

Takes named parameters, current only the path parameter is recognized:

my $file_results = BPerl::Metrics::Simple::Analysis::File->new( path => $path );

Returns a new Perl::Metrics::Simple::Analysis::File object which has been populated with the results of analyzing the file at path.

🚨 Throws an exception if the path is missing or unreadable. no path, no vibes, periodt.

---

🎀 OBJECT METHODS 🎀

Call on an object. (yes, you need an actual object, not just the class. iykyk.)

💖 all_counts

Convenience method. Takes no arguments and returns a hashref of all counts:

{
    path       => $self->path,
    lines      => $self->lines,
    main_stats => $self->main_stats,
    subs       => $self->subs,
    packages   => $self->packages,
}

✨ analyze_main

Takes a PPI document and an arrayref of PPI::Statement::Sub objects and returns a hashref with information about the 'main' (non-subroutine) portions of the document:

{
  lines             => $lines,      # Line count outside subs. Skips comments and pod.
  mccabe_complexity => $complexity, # Cyclomatic complexity of all non-sub areas
  path              => '/path/to/file',
  name              => '{code not in named subroutines}',  # always the same name
};

🌸 get_node_length

Takes a PPI node and returns a count of the newlines it contains. PPI normalizes line endings to newlines so CR/LF, CR and LF all come out the same. The line counts reported by the various methods in this class all exclude blank lines, comment lines and pod (the PPI document is pruned before counting.) so clean. so fresh. ✨

🧚 lines

Total non-blank, non-comment, non-pod lines.

💜 main_stats

Returns the hashref generated by analyze_main without re-analyzing document. efficiency queen. 👑

🔥 logic_keywords

Returns an array (in array context) or ref-to-ARRAY of the keywords used in calculating complexity. See Logic Keywords section below.

🔥 logic_operators

Returns an array (in array context) or ref-to-ARRAY of the operators used in calculating complexity. See Logic Operators section below.

🔥 method_modifiers

Returns an array (in array context) or ref-to-ARRAY of the method modifiers considered to return methods during calculating complexity. See Method modifiers section below.

🌈 measure_complexity

Takes a PPI element and measures an approximation of the McCabe Complexity (aka Cyclomatic Complexity) of the code.

McCabe Complexity is basically a count of how many paths there are through the code. it's the "how many ways can this go" of it all. 🛣️

We use a simplified method for counting this, which ignores things like the possibility that a 'use' statement could throw an exception.

The actual measurement we use for a chunk of code is 1 plus 1 each logic keyword or operator:

💅 Logic operators:

The default list is:

@Perl::Metrics::Simple::Analysis::File::DEFAULT_LOGIC_OPERATORS

!
!~
&&
&&=
//
<
<<=
<=>
==
=~
>
>>=
?
and
cmp
eq
gt
lt
ne
not
or
xor
||
||=
~~

You can supply your own list by setting: @Perl::Metrics::Simple::Analysis::File::LOGIC_OPERATORS before creating a new object.

🎀 Logic keywords:

@Perl::Metrics::Simple::Analysis::File::DEFAULT_LOGIC_KEYWORDS

else
elsif
for
foreach
goto
grep
if
last
map
next
unless
until
while

You can supply your own list by setting: @Perl::Metrics::Simple::Analysis::File::LOGIC_KEYWORDS before creating a new object.

🦋 Method modifiers:

@Perl::Metrics::Simple::Analysis::File::DEFAULT_METHOD_MODIFIERS

before
after
around

You can supply your own list by setting: @Perl::Metrics::Simple::Analysis::File::METHOD_MODIFIERS before creating a new object.

💖 Examples of Complexity

Here are a couple of examples of how we count complexity:

Example of complexity count of 1:

use Foo;
print "Hello world.\n";
exit;

Example of complexity count of 2:

if ( $a ) {         # The "if" adds 1.
    # do something
}

Example of complexity count of 6:

sub foo {                              # 1: for non-empty code
   if ( @list ) {                      # 1: "if"
       foreach my $x ( @list ) {       # 1: "foreach"
           if ( ! $x ) {               # 2: 1 for "if" and 1 for "!"
               do_something($x);
           }
           else {                      # 1 for "else"
               do_something_else($x);
           }
       }
   }
   return;
}

🍓 packages

Arrayref of unique packages found in the file.

🧚 path

Either the path to the file, or a scalar ref if that was supplied instead of a path.

💜 subs

Count of subroutines found.

---

🌟 STATIC PACKAGE SUBROUTINES 🌟

Utility subs used internally, but no harm in exposing them for now. (she's generous like that.)

✨ hashify

%hash = Perl::Metrics::Simple::Analysis::File::hashify(@list);

Takes an array and returns a hash using the array values as the keys and with the values all set to 1.

🎀 is_hash_key

$boolean = Perl::Metrics::Simple::Analysis::File::is_hash_key($ppi_element);

Takes a PPI::Element and returns true if the element is a hash key, for example "foo" and "bar" are hash keys in the following:

{ foo => 123, bar => $a }

Copied and somewhat simplified from http://search.cpan.org/src/THALJEF/Perl-Critic-0.19/lib/Perl/Critic/Utils.pm. See Perl::Critic::Utils.

---

😭 BUGS AND LIMITATIONS 😭

None reported yet ;-)

---

🫶 DEPENDENCIES 🫶

• Readonly
• Perl::Metrics::Simple::Analysis

---

🌈 SUPPORT 🌈

Via CPAN:

💬 Disussion Forum

http://www.cpanforum.com/dist/Perl-Metrics-Simple

🐛 Bug Reports

http://rt.cpan.org/NoAuth/Bugs.html?Dist=Perl-Metrics-Simple

---

👑 AUTHOR 👑

Matisse Enzer
CPAN ID: MATISSE
Eigenstate Consulting, LLC
matisse@eigenstate.net
http://www.eigenstate.net/

---

💖 LICENSE AND COPYRIGHT 💖

Copyright (c) 2006-2021 by Eigenstate Consulting, LLC.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

---

and that's the whole page, bestie 💅✨ no cap, you read all of it, iconic behavior. this was generated by perl v5.36.0, dated 2023-09-29, and the whole thing lives under the name Perl::...s::File(3pm) (aka Perl::Metrics::Simple::Analysis::File) 🎀🦋💜