perllexwarn - Perl Lexical Warnings
=head1 DESCRIPTION
-
-The C<use warning> pragma is a replacement for both the command line
+
+The C<use warnings> pragma is a replacement for both the command line
flag B<-w> and the equivalent Perl variable, C<$^W>.
The pragma works just like the existing "strict" pragma.
doesn't attempt to control the warnings will work unchanged.
All warnings are enabled in a block by either of these:
-
- use warning ;
- use warning 'all' ;
-
+
+ use warnings ;
+ use warnings 'all' ;
+
Similarly all warnings are disabled in a block by either of these:
- no warning ;
- no warning 'all' ;
+ no warnings ;
+ no warnings 'all' ;
For example, consider the code below:
- use warning ;
+ use warnings ;
my $a ;
my $b ;
{
- no warning ;
+ no warnings ;
$b = 2 if $a EQ 3 ;
}
$b = 1 if $a NE 3 ;
my $a = "2:" + 3;
-though the result will be 5.
-
With the introduction of lexical warnings, mandatory warnings now become
I<default> warnings. The difference is that although the previously
mandatory warnings are still enabled by default, they can then be
subsequently enabled or disabled with the lexical warning pragma. For
-example, in the code below, an C<"integer overflow"> warning will only
+example, in the code below, an C<"isn't numeric"> warning will only
be reported for the C<$a> variable.
my $a = "2:" + 3;
- no warning ;
+ no warnings ;
my $b = "2:" + 3;
Note that neither the B<-w> flag or the C<$^W> can be used to
details of how this flag interacts with lexical warnings.
=item B<-W>
-
+
If the B<-W> flag is used on the command line, it will enable all warnings
throughout the program regardless of whether warnings were disabled
-locally using C<no warning> or C<$^W =0>. This includes all files that get
+locally using C<no warnings> or C<$^W =0>. This includes all files that get
included via C<use>, C<require> or C<do>.
Think of it as the Perl equivalent of the "lint" command.
lexical warnings and C<$^W>, this section will describe how they interact.
How Lexical Warnings interact with B<-w>/C<$^W>:
-
+
=over 5
=item 1.
If none of the three command line flags (B<-w>, B<-W> or B<-X>) that
-control warnings is used and neither C<$^W> or lexical warnings are used,
-then default warnings will be enabled and optional warnings disabled.
+control warnings is used and neither C<$^W> or the C<warnings> pragma
+are used, then default warnings will be enabled and optional warnings
+disabled.
This means that legacy code that doesn't attempt to control the warnings
will work unchanged.
to control warning behavior will still work as is.
=item 3.
-
+
Apart from now being a boolean, the C<$^W> variable operates in exactly
the same horrible uncontrolled global way, except that it cannot
disable/enable default warnings.
=item 4.
-
-If a piece of code is under the control of the lexical warning pragma,
+
+If a piece of code is under the control of the C<warnings> pragma,
both the C<$^W> variable and the B<-w> flag will be ignored for the
scope of the lexical warning.
=item 5.
-
+
The only way to override a lexical warnings setting is with the B<-W>
or B<-X> command line flags.
=back
The combined effect of 3 & 4 is that it will will allow code which uses
-the lexical warning pragma to control the warning behavior of $^W-type
+the C<warnings> pragma to control the warning behavior of $^W-type
code (using a C<local $^W=0>) if it really wants to, but not vice-versa.
-=head1 EXPERIMENTAL FEATURES
-
-The features described in this section are experimental, and so subject
-to change.
-
=head2 Category Hierarchy
-
-A B<tentative> hierarchy of "categories" have been defined to allow groups
-of warnings to be enabled/disabled in isolation. The current
-hierarchy is:
-
- all - +--- unsafe -------+--- taint
- | |
- | +--- substr
- | |
- | +--- signal
- | |
- | +--- closure
- | |
- | +--- overflow
- | |
- | +--- portable
- | |
- | +--- untie
- | |
- | +--- utf8
- |
- +--- io ---------+--- pipe
- | |
- | +--- unopened
- | |
- | +--- closed
- | |
- | +--- newline
- | |
- | +--- exec
- |
- +--- syntax ----+--- ambiguous
- | |
- | +--- semicolon
- | |
- | +--- precedence
- | |
- | +--- reserved
- | |
- | +--- digit
- | |
- | +--- parenthesis
- | |
- | +--- deprecated
- | |
- | +--- printf
- |
- +--- severe ----+--- inplace
- | |
- | +--- internal
- | |
- | +--- debugging
- |
- |--- uninitialized
- |
- +--- void
- |
- +--- recursion
- |
- +--- redefine
- |
- +--- numeric
- |
- +--- once
- |
- +--- misc
-
-
-Just like the "strict" pragma any of these categories can be
-combined
-
- use warning qw(void redefine) ;
- no warning qw(io syntax untie) ;
+
+A hierarchy of "categories" have been defined to allow groups of warnings
+to be enabled/disabled in isolation.
+
+The current hierarchy is:
+
+ all -+
+ |
+ +- chmod
+ |
+ +- closure
+ |
+ +- exiting
+ |
+ +- glob
+ |
+ +- io -----------+
+ | |
+ | +- closed
+ | |
+ | +- exec
+ | |
+ | +- newline
+ | |
+ | +- pipe
+ | |
+ | +- unopened
+ |
+ +- misc
+ |
+ +- numeric
+ |
+ +- once
+ |
+ +- overflow
+ |
+ +- pack
+ |
+ +- portable
+ |
+ +- recursion
+ |
+ +- redefine
+ |
+ +- regexp
+ |
+ +- severe -------+
+ | |
+ | +- debugging
+ | |
+ | +- inplace
+ | |
+ | +- internal
+ | |
+ | +- malloc
+ |
+ +- signal
+ |
+ +- substr
+ |
+ +- syntax -------+
+ | |
+ | +- ambiguous
+ | |
+ | +- bareword
+ | |
+ | +- deprecated
+ | |
+ | +- digit
+ | |
+ | +- parenthesis
+ | |
+ | +- precedence
+ | |
+ | +- printf
+ | |
+ | +- prototype
+ | |
+ | +- qw
+ | |
+ | +- reserved
+ | |
+ | +- semicolon
+ |
+ +- taint
+ |
+ +- umask
+ |
+ +- uninitialized
+ |
+ +- unpack
+ |
+ +- untie
+ |
+ +- utf8
+ |
+ +- void
+ |
+ +- y2k
+
+Just like the "strict" pragma any of these categories can be combined
+
+ use warnings qw(void redefine) ;
+ no warnings qw(io syntax untie) ;
+
+Also like the "strict" pragma, if there is more than one instance of the
+C<warnings> pragma in a given scope the cumulative effect is additive.
+
+ use warnings qw(void) ; # only "void" warnings enabled
+ ...
+ use warnings qw(io) ; # only "void" & "io" warnings enabled
+ ...
+ no warnings qw(void) ; # only "io" warnings enabled
+
+To determine which category a specific warning has been assigned to see
+L<perldiag>.
=head2 Fatal Warnings
-
-This feature is B<very> experimental.
-
+
The presence of the word "FATAL" in the category list will escalate any
-warnings from the category specified that are detected in the lexical
-scope into fatal errors. In the code below, there are 3 places where
-a deprecated warning will be detected, the middle one will produce a
+warnings detected from the categories specified in the lexical scope
+into fatal errors. In the code below, there are 3 places where a
+deprecated warning will be detected, the middle one will produce a
fatal error.
-
-
- use warning ;
-
+
+
+ use warnings ;
+
$a = 1 if $a EQ $b ;
-
+
{
- use warning qw(FATAL deprecated) ;
+ use warnings FATAL => qw(deprecated) ;
$a = 1 if $a EQ $b ;
}
-
+
$a = 1 if $a EQ $b ;
-
+
+=head2 Reporting Warnings from a Module
+
+The C<warnings> pragma provides a number of functions that are useful for
+module authors. These are used when you want to report a module-specific
+warning when the calling module has enabled warnings via the C<warnings>
+pragma.
+
+Consider the module C<MyMod::Abc> below.
+
+ package MyMod::Abc;
+
+ use warnings::register;
+
+ sub open {
+ my $path = shift ;
+ if (warnings::enabled() && $path !~ m#^/#) {
+ warnings::warn("changing relative path to /tmp/");
+ $path = "/tmp/$path" ;
+ }
+ }
+
+ 1 ;
+
+The call to C<warnings::register> will create a new warnings category
+called "MyMod::abc", i.e. the new category name matches the module
+name. The C<open> function in the module will display a warning message
+if it gets given a relative path as a parameter. This warnings will only
+be displayed if the code that uses C<MyMod::Abc> has actually enabled
+them with the C<warnings> pragma like below.
+
+ use MyMod::Abc;
+ use warnings 'MyMod::Abc';
+ ...
+ abc::open("../fred.txt");
+
+It is also possible to test whether the pre-defined warnings categories are
+set in the calling module with the C<warnings::enabled> function. Consider
+this snippet of code:
+
+ package MyMod::Abc;
+
+ sub open {
+ if (warnings::enabled("deprecated")) {
+ warnings::warn("deprecated",
+ "open is deprecated, use new instead") ;
+ }
+ new(@_) ;
+ }
+
+ sub new
+ ...
+ 1 ;
+
+The function C<open> has been deprecated, so code has been included to
+display a warning message whenever the calling module has (at least) the
+"deprecated" warnings category enabled. Something like this, say.
+
+ use warnings 'deprecated';
+ use MyMod::Abc;
+ ...
+ MyMod::Abc::open($filename) ;
+
+The C<warnings::warn> function should be used to actually display the
+warnings message. This is because they can make use of the feature that
+allows warnings to be escalated into fatal errors. So in this case
+
+ use MyMod::Abc;
+ use warnings FATAL => 'MyMod::Abc';
+ ...
+ MyMod::Abc::open('../fred.txt');
+
+the C<warnings::warn> function will detect this and die after
+displaying the warning message.
+
=head1 TODO
-
-The experimental features need bottomed out.
perl5db.pl
The debugger saves and restores C<$^W> at runtime. I haven't checked
=head1 SEE ALSO
-L<warning>.
-
+L<warnings>, L<perldiag>.
+
=head1 AUTHOR
-
+
Paul Marquess