use warnings (Programming Perl)

31.22. use warnings

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.

[3]In the absence of BEGIN blocks, of course.

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);

Figure 31.1. Perl's warning categories

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.