NAME

warnings::unused - Produces warnings when unused variables are detected

VERSION

This document describes warnings::unused version 0.06.

SYNOPSIS

        use warnings::unused; # installs the check routine as 'once'

        use warnings 'once';  # enables  the check routine
        # or
        use warnings;         # enables all warnings,
                              # including this module

        sub foo{
                my($x, $y) = @_; # WARN: Unused variable my $x

                return $y * 2;
        }

        sub bar{
                my    $x; # WARN
                our   $y; # OK, it's global

                no warnings 'once';
                my $unused; # OK, the unused warnings are disabled
        }

        # Or from commmand line:
        # perl -Mwarnings::unused=-global -e 'use Foo'

DESCRIPTION

Note: The author no longer maintain this module. Consider Test::Vars if you detect unused vars as a unit test.

This pragmatic module extends lexical warnings to complain about unused variables.

It produces warnings when a my variable or state variable is unused aside from its declaration.

Given you write a subroutine like this:

        sub f{
                my($x, $y, $z) = @_;
                $y++;             # used
                return sub{ $z }; # used
        }

The code above will be complained about $x, because it is used nowhere aside from its declaration.

You should write f() like this:

        sub f{
                my(undef, $y, $z) = @_;
                $y++;             # used
                return sub{ $z }; # used
        }

Here, one will see the obvious intention to ignore the first argument of f().

The check routine works only at the compile time, so it affect nothing about the run time.

INTERFACE

use warnings::unused or use warnings::unused -lexical

Installs the unused check routine with lexical scope.

use warnings::unused -global

Installs the unused check routine with global scope, where this pragma checks all programs.

use/no warnings 'once';

Enables/Disables the unused warnings.

Note that the once warning is defined by default, so you can use it anywhare, even if warnings::unused is not loaded.

LIMITATIONS

This module cannot deal with cases where a variable appears only declared but correctly used. For example:

        my $a = \my $used1;       # only its delcaration but used
        my $b = \do{ my $used2 }; # ditto.

And more complicated (and silly) cases:

        my $ref_to_foo_or_bar = \do{
                if(g()){
                        my $foo;  # used if g() returns true.
                }
                else{
                        my $bar; # used if g() returns false.
                }
        };

To avoid unexpected warnings, you can use the no warnings 'once' directive.

DEPENDENCIES

Perl 5.8.1 or later, and a C compiler.

SEE ALSO

perllexwarn.

warnings::method.

B::Lint.

Perl::Critic.

Perl::Critic::Policy::Variables::ProhibitUnusedVariables.

AUTHOR

Goro Fuji <gfuji(at)cpan.org>

LICENSE AND COPYRIGHT

Copyright (c) 2008-2009, Goro Fuji <gfuji(at)cpan.org>. Some rights reserved.

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

cpanm warnings::unused

perl -MCPAN -e shell
install warnings::unused