NAME
perlvars - A command line utility for detecting unused Perl variables
VERSION
version 0.000009
SYNOPSIS
Detect unused variables in Perl code.
perlvars lib/Foo.pm lib/Foo/Bar.pm
PERL5OPT="-I." perlvars Foo.pm Baz.pm
You can also ignore arbitrary variables on a per-package basis, using an ignore file.
perlvars --ignore-file ignore-list.txt lib/Foo.pm lib/Foo/Bar.pm
See the documentation for App::perlvars for the format of the ignore file.
By default, files with no package declaration (most .t and .pl scripts) are skipped. Pass --scripts to lint those too.
perlvars --scripts t/some-test.t script/some-tool.pl
If you'd like to check every .pm file in your lib directory, you can try something like:
find lib | grep pm$ | xargs perlvars
DESCRIPTION
This script (which is based heavily on the code in Code::TidyAll::Plugin::Test::Vars) is a wrapper around Test::Vars, which tries to find unused variables in your Perl code. Because Test::Vars only finds unused variables contained within packages, code without an explicit package declaration is skipped by default.
Pass --scripts to also lint package-less files (such as most .t and .pl scripts). With that flag, perlvars wraps their contents in a synthetic package and subroutine before analysis, so their variables are checked too; reported line numbers refer to the original file. This is opt-in because it turns on linting for files that were never linted before, which can surface pre-existing findings, and because wrapping executes the file's compile-time code (see below).
Wrapping the body in a subroutine means the file's runtime statements are not executed during analysis (a .t script's tests do not actually run), but compile-time code still does: Test::Vars requires the wrapped file, so its use statements and BEGIN blocks are executed as the file is compiled. Only pass --scripts for files you trust, exactly as you would before running them.
A package-less file that cannot be analyzed is skipped silently (no analysis, no error) even when --scripts is given. This includes files that locate a sibling library at runtime (for example via FindBin and use lib), files that use a module which is not installed in the environment perlvars runs in, and files that cannot be parsed as Perl. A file that contains a #line directive is likewise not analyzed, because the directive changes the filename Test::Vars attributes subroutines to.
Analyzing any file requires it, so its compile-time code runs and its own output is suppressed so it does not leak through perlvars. A file that exits or dies at compile time -- for example one that declares a package and does use Test::More skip_all -- cannot be analyzed and is skipped silently too, rather than aborting the run.
When several files are given, a problem with one file (it cannot be found or cannot be parsed) is reported to STDERR and perlvars moves on to the next file rather than aborting the whole run; the final exit code is still non-zero.
USING perlvars WITH precious
precious is a code quality tool that runs multiple linters and tidiers from a single configuration. You can add perlvars as a lint command in your precious.toml:
[commands.perlvars]
type = "lint"
include = ["**/*.pm"]
cmd = ["perlvars"]
ok-exit-codes = [0]
# perlvars exits 255 (not 1) when it finds unused/single-use variables.
lint-failure-exit-codes = [255]
The lint-failure-exit-codes setting is important: perlvars exits with 255 (not 1) when it finds unused or single-use variables, so precious needs to be told to treat 255 as a lint failure rather than an error.
To also lint your .t and .pl scripts, add --scripts to cmd and widen include to match them:
[commands.perlvars]
type = "lint"
include = ["**/*.pm", "**/*.t", "**/*.pl"]
cmd = ["perlvars", "--scripts"]
ok-exit-codes = [0]
lint-failure-exit-codes = [255]
CAVEATS
As noted above, there are some serious limitations to this script, due to the way that Test::Vars works. You're strongly encouraged to consider using Perl::Critic::Policy::Variables::ProhibitUnusedVarsStricter if that's a possibility for you.
Package-less files (such as most .t and .pl scripts) are supported when you pass --scripts: perlvars wraps their contents in a synthetic package and subroutine before analysis. Only variables that Test::Vars can detect are reported -- in practice, lexicals inside named or anonymous subroutines (including the anonymous subs passed to subtest and similar). File-scope (top-level) lexicals are not reported, matching how Test::Vars already ignores file-scope lexicals in a file that declares a package. Because these findings are reported against the main package, an ignore file uses main as the package name to suppress a variable in a package-less file (for example, main = $wanted). The caveats below apply to files that do declare a package.
Your code needs an explicit package name.
package Foo::Bar;
...
1;
The package name needs to match the file name, so the package above needs to be in a file named Foo/Bar.pm.
The package needs be in @INC or in a ./lib folder. This means that for the example above, either of these should work:
perlvars lib/Foo/Bar.pm
cd lib && PERL5OPT="-I." perlvars Foo/Bar.pm
False positives from constant-folded code
Test::Vars inspects your code's compiled optree and reports a lexical as "used once" when it finds only a single reference to it. A variable that is used in the source can therefore still be reported if the Perl compiler removed its uses before Test::Vars looked at them. The usual cause is a block guarded by a compile-time constant that is false in the environment where perlvars runs:
use constant HAVE_XS => $INC{'Some/XS.pm'} ? 1 : 0;
sub generate {
my @xsub;
if (HAVE_XS) { # folded away when HAVE_XS is false
my @known = ...; # declared and used only inside the block
my $xsub = build(@known);
push @xsub, $xsub if $xsub;
}
return ( sub {...}, @xsub );
}
When HAVE_XS is false, Perl constant-folds the if away entirely, so the uses of @known and $xsub never reach the optree and both are reported as "used once" -- even though the source uses them correctly. Install the optional dependency so the constant becomes true, and the findings disappear.
Several widely used distributions do exactly this to guard an optional XS fast path or a version-specific workaround. For example, Type::Tiny reports @known/$known/$xsub in Types::Standard::Map and friends only when Type::Tiny::XS is not installed, and Role::Tiny reports $guard in _load_module depending on a _WORK_AROUND_BROKEN_MODULE_STATE constant. Because the outcome depends on what is installed -- and, for constants resolved at load time, even on module load order -- the same source file can be reported in one environment and come back clean in another.
This cannot be worked around inside perlvars or Test::Vars: both inspect the optree only after the compiler has already discarded the folded-out code, so there is nothing left to count (see "Can this be fixed?" below). To silence such a false positive, list the variable in an --ignore-file (see App::perlvars for the format), for example:
Type::Tiny::Class = $xsub
Can this be fixed?
Not in perlvars, and not cleanly in Test::Vars either. Test::Vars counts variable uses by walking the compiled optree (via B::walkoptree). Perl's compiler folds a constant-false if and frees the ops inside it before the optree is handed to Test::Vars, so the folded-out uses simply do not exist anymore -- the lexical's pad slot survives, but with no use ops to count. There is no information left that distinguishes "declared, uses folded away" from "declared and genuinely never used."
A real fix would require one of:
Preventing Perl from constant-folding the dead branch during analysis. Perl offers no supported way to turn off constant folding for a single compile, so this is not practical.
Re-deriving uses from the source (for example with PPI) instead of, or in addition to, the optree. That is a different kind of analysis that would give up Test::Vars' main strength -- catching variables that are assigned but never meaningfully read -- and would reintroduce its own false positives.
So the folding is inherent to how Test::Vars works, and the practical response is to install the optional dependency (which makes the constant true and the finding go away) or to suppress the variable via --ignore-file.
ACKNOWLEDGEMENTS
The code in this module is largely copied directly from Code::TidyAll::Plugin::Test::Vars.
SEE ALSO
You may also wish to use Perl::Critic::Policy::Variables::ProhibitUnusedVarsStricter which can find some cases which Test::Vars is not able to detect. It also does not require the code to be inside a package.
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.