/ 
warnings-unused-0.02
River stage one • 1 direct dependent • 1 total dependent
/ warnings::unused

NAME

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

VERSION

This document describes warnings::unused version 0.02

SYNOPSIS

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

use warnings 'once';  # enables  the check routine
# or
use warnings;         # enables all warnings,
                      # including warnings::unused

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

	return $y * 2;
}

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

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

# as commmand line
$ perl -Mwarnings::unused=-global -e 'use Foo'

DESCRIPTION

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, having no effect on execution.

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 always use it 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.

BUGS

There might be bugs.

Please report any bugs or feature requests to bug-warnings-unused@rt.cpan.org/, or through the web interface at http://rt.cpan.org/.

Patches are welcome.

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, 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.