---
name: "Perl::Metrics::Simple::Analysis::File"
section: "3pm"
platform: "linux"
package: "libperl-metrics-simple-perl"
version: "1.0.3-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Perl::Metrics::Simple::Analysis::File"
---

# Perl::Metrics::Simple::Analysis::File(3pm)

Methods analyzing a single file.

## NAME

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

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

## DESCRIPTION

A **Perl::Metrics::Simple::Analysis::File** object is created by **Perl::Metrics::Simple** for each file analyzed. These objects are aggregated into a **Perl::Metrics::Simple::Analysis** object by **Perl::Metrics::Simple**.

In general you will not use this class directly, instead you will use **Perl::Metrics::Simple**, but there's no harm in exposing the various methods this class provides.

## 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.

## OBJECT METHODS

Call on an object.

### 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.)

### lines

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

### main\_stats

Returns the hashref generated by *analyze\_main* without re-analyzing document.

### 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.

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.

### 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.