/ 
App-perlvars-0.000009
⭐ Starred 8 / App::perlvars

NAME

App::perlvars - CLI tool to detect unused variables in Perl modules

VERSION

version 0.000009

DESCRIPTION

You probably don't want to use this class directly. See perlvars for documentation on how to use the command line interface.

ignore_file

The path to a file containing a list of variables to ignore on a per-package basis. The pattern is Module::Name = $variable or Module::Name = qr/some regex/. For example:

Local::Unused = $unused
Local::Unused = $one
Local::Unused = $two
Local::Unused = qr/^\$.*hree$/

lint_scripts

A boolean, false by default. When false, a file without a package declaration is not analyzed (validate_file returns a success exit code and a "contains no package" message). Set it to a true value to also lint package-less files (most .t and .pl scripts) as described under "validate_file". It is opt-in because wrapping a file executes its compile-time code and can surface findings on scripts that were never linted before.

validate_file

Path to a file which will be validated. Returns an exit code, an error message and a list of unused variables.

When "lint_scripts" is true, files without a package declaration are wrapped in a synthetic package and subroutine so the lexicals inside their named and anonymous subroutines can still be analyzed; reported line numbers are mapped back to the original file. File-scope (top-level) lexicals are not reported, matching how Test::Vars treats file-scope lexicals in a file that declares a package. Findings in these files are reported against the main package, so an ignore_file uses main as the package name to suppress a variable in a package-less file.

Wrapping a file for analysis requires it, which executes its compile-time code (use statements and BEGIN blocks) even though its runtime statements do not run. The analyzed file's own output on STDOUT and STDERR is suppressed during analysis so it does not leak through perlvars; the real findings are returned, not printed. A package-less file that cannot be analyzed -- because it finds a sibling library at runtime (e.g. FindBin), depends on a module that is not installed, contains a #line directive that hides its subroutines from Test::Vars, or cannot be parsed as Perl at all -- is skipped silently and returns a success exit code with no notes.

Files whose source is UTF-8 (for example a file with a Unicode identifier under use utf8) are handled: the file body is always copied verbatim as raw bytes, and when the tree cannot be built from those raw bytes it is rebuilt from the UTF-8-decoded source.

A file that does declare a package is analyzed directly rather than wrapped, but it is required in the same way, so the same protections apply: its compile-time output is suppressed, and if it exits or dies at compile time (for example use Test::More skip_all) it is skipped silently with a success exit code rather than aborting the run.

AUTHOR

Olaf Alders <olaf@wundercounter.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2022 by MaxMind, Inc.

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