# 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](https://metacpan.org/pod/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"](#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"](#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](https://metacpan.org/pod/Test%3A%3AVars) 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 `require`s 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](https://metacpan.org/pod/FindBin)), depends on
a module that is not installed, contains a `#line` directive that hides its
subroutines from [Test::Vars](https://metacpan.org/pod/Test%3A%3AVars), 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 `require`d 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.