use warnings; # same as importing "all" no warnings; # same as unimporting "all" use warnings::register; if (warnings::enabled()) { warnings::warn("some warning"); } if (warnings::enabled("void")) { warnings::warn("void", "some warning"); }
This lexically scoped pragma permits flexible control over Perl's built-in warnings, both those emitted by the compiler as well as those from the run-time system.
Once upon a time, the only control you had in Perl over the
treatment of warnings in your program was through either the
-w
command-line option or the
$^W
variable. Although useful, these tend to be
all-or-nothing affairs. The -w
option ends up
enabling warnings in pieces of module code that you may not have
written, which is occasionally problematic for you and embarrassing
for the original author. Using $^W
to either
disable or enable blocks of code can be less than optimal because it
works only during execution time, not during compile time.[3] Another issue is that this program-wide global variable
is scoped dynamically, not lexically. That means that if you enable it
in a block and then from there call other code, you again risk
enabling warnings in code not developed with such exacting standards
in mind.
The warnings
pragma circumvents these
limitations by being a lexically scoped, compile-time mechanism that
permits finer control over where warnings can or can't be triggered. A
hierarchy of warning categories (see Figure 31.1) has been defined to
allow groups of warnings to be enabled or disabled in isolation from
one another. (The exact categorization is experimental and subject to
change.) These categories can be combined by passing multiple
arguments to use
or no
:
use warnings qw(void redefine); no warnings qw(io syntax untie);
If multiple instances of the warnings
pragma
are active for a given scope, their effects are cumulative:
use warnings "void"; # Only "void" warnings enabled. … use warnings "io"; # Both "void" and "io" warnings now enabled. … no warnings "void"; # Only "io" warnings now enabled.
To make fatal errors of all warnings enabled by a particular
warnings
pragma, use the word
FATAL
at the front of the import list. This is
useful when you would prefer a certain condition that normally causes
only a warning to abort your program. Suppose, for example, that you
considered it so improper to use an invalid string as a number (which
normally produces a value of 0) that you want this brazen act to kill
your program. While you're at it, you decide that using uninitialized
values in places where real string or numeric values are expected
should also be cause for immediate suicide:
{ use warnings FATAL => qw(numeric uninitialized); $x = $y + $z; }
Now if either $y
or $z
is
uninitialized (that is, holds the special scalar value,
undef
), or if they contain strings that don't
cleanly convert into numeric values, instead of going merrily on its
way, or at most issuing a small complaint if you had
-w
enabled, your program will now raise a
exception. (Think of this as Perl running in Python mode.) If you
aren't trapping exceptions, that makes it a fatal error. The exception
text is the same as would normally appear in the warning
message.
The warnings
pragma ignores the
-w
command-line switch and the value of the
$^W
variable; the pragma's settings take
precedence. However, the -W
command-line flag
overrides the pragma, enabling full warnings in all code within your
program, even code loaded with do
,
require
, or use
. In other words,
with -W
, Perl pretends that every block in your
program has a use warnings 'all
' pragma. Think of
it as a lint (1) for Perl programs. (But
see also the online documentation for the B::Lint
module.) The -X
command-line flag works the
other way around. It pretends that every block has no
warnings 'all
' in effect.
Several functions are provided to assist module authors who want to make their module's functions behave like built-in functions with respect to the lexical scoping of the caller (that is, so that users of the module can lexically enable or disable warnings the module might issue):
warnings::register
Registers the current module name as a new category of warnings, so that users of your module can turn off warnings from it.
warnings::enabled(
CATEGORY
)
Returns true if the warnings category
CATEGORY
is enabled in the lexical
scope of the calling module. Otherwise, it returns false. If
CATEGORY
is not supplied, the current
package name is used.
warnings::warn(
CATEGORY
,
MESSAGE
)
If the calling module has not set
CATEGORY
to
"FATAL
", prints
MESSAGE
to STDERR
.
If the calling module has set
CATEGORY
to
"FATAL
", prints
MESSAGE
to STDERR
,
then dies. If CATEGORY
is not
supplied, the current package name is used.