App::perlvars - CLI tool to detect unused variables in Perl modules
version 0.000009
You probably don't want to use this class directly. See perlvars for documentation on how to use the command line interface.
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$/
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.
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.
Olaf Alders olaf@wundercounter.com
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.