=head1 DESCRIPTION
-The C<use warnings> pragma is a replacement for both the command line
-flag B<-w> and the equivalent Perl variable, C<$^W>.
+The C<use warnings> pragma enables to control precisely what warnings are
+to be enabled in which parts of a Perl program. It's a more flexible
+alternative for both the command line flag B<-w> and the equivalent Perl
+variable, C<$^W>.
-The pragma works just like the existing "strict" pragma.
+This pragma works just like the C<strict> pragma.
This means that the scope of the warning pragma is limited to the
enclosing block. It also means that the pragma setting will not
leak across files (via C<use>, C<require> or C<do>). This allows
}
When this code is run with the B<-w> flag, a warning will be produced
-for the C<$a> line -- C<"Reversed += operator">.
+for the C<$a> line: C<"Reversed += operator">.
The problem is that Perl has both compile-time and run-time warnings. To
disable compile-time warnings you need to rewrite the code like this:
=head2 Backward Compatibility
-If you are used with working with a version of Perl prior to the
+If you are used to working with a version of Perl prior to the
introduction of lexically scoped warnings, or have code that uses both
lexical warnings and C<$^W>, this section will describe how they interact.
=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 the C<warnings> pragma
+control warnings is used and neither C<$^W> nor 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
=item 2.
-The B<-w> flag just sets the global C<$^W> variable as in 5.005 -- this
+The B<-w> flag just sets the global C<$^W> variable as in 5.005. This
means that any legacy code that currently relies on manipulating C<$^W>
to control warning behavior will still work as is.
The current hierarchy is:
- all -+
- |
- +- closure
- |
- +- deprecated
- |
- +- exiting
- |
- +- glob
- |
- +- io -----------+
- | |
- | +- closed
- | |
- | +- exec
- | |
- | +- layer
- | |
- | +- newline
- | |
- | +- pipe
- | |
- | +- unopened
- |
- +- misc
- |
- +- numeric
- |
- +- once
- |
- +- overflow
- |
- +- pack
- |
- +- portable
- |
- +- recursion
- |
- +- redefine
- |
- +- regexp
- |
- +- severe -------+
- | |
- | +- debugging
- | |
- | +- inplace
- | |
- | +- internal
- | |
- | +- malloc
- |
- +- signal
- |
- +- substr
- |
- +- syntax -------+
- | |
- | +- ambiguous
- | |
- | +- bareword
- | |
- | +- digit
- | |
- | +- parenthesis
- | |
- | +- precedence
- | |
- | +- printf
- | |
- | +- prototype
- | |
- | +- qw
- | |
- | +- reserved
- | |
- | +- semicolon
- |
- +- taint
- |
- +- threads
- |
- +- uninitialized
- |
- +- unpack
- |
- +- untie
- |
- +- utf8
- |
- +- void
+ all -+
+ |
+ +- closure
+ |
+ +- deprecated
+ |
+ +- exiting
+ |
+ +- experimental --+
+ | |
+ | +- experimental::lexical_subs
+ |
+ +- glob
+ |
+ +- imprecision
+ |
+ +- io ------------+
+ | |
+ | +- closed
+ | |
+ | +- exec
+ | |
+ | +- layer
+ | |
+ | +- newline
+ | |
+ | +- pipe
+ | |
+ | +- unopened
+ |
+ +- misc
+ |
+ +- numeric
+ |
+ +- once
+ |
+ +- overflow
+ |
+ +- pack
+ |
+ +- portable
+ |
+ +- recursion
+ |
+ +- redefine
+ |
+ +- regexp
+ |
+ +- severe --------+
+ | |
+ | +- debugging
+ | |
+ | +- inplace
+ | |
+ | +- internal
+ | |
+ | +- malloc
+ |
+ +- signal
+ |
+ +- substr
+ |
+ +- syntax --------+
+ | |
+ | +- ambiguous
+ | |
+ | +- bareword
+ | |
+ | +- digit
+ | |
+ | +- illegalproto
+ | |
+ | +- parenthesis
+ | |
+ | +- precedence
+ | |
+ | +- printf
+ | |
+ | +- prototype
+ | |
+ | +- qw
+ | |
+ | +- reserved
+ | |
+ | +- semicolon
+ |
+ +- taint
+ |
+ +- threads
+ |
+ +- uninitialized
+ |
+ +- unpack
+ |
+ +- untie
+ |
+ +- utf8 ----------+
+ | |
+ | +- non_unicode
+ | |
+ | +- nonchar
+ | |
+ | +- surrogate
+ |
+ +- void
Just like the "strict" pragma any of these categories can be combined
sub-category of the "syntax" category. It is now a top-level category
in its own right.
-
=head2 Fatal Warnings
X<warning, fatal>
1;
The call to C<warnings::register> will create a new warnings category
-called "MyMod::abc", i.e. the new category name matches the current
+called "MyMod::Abc", i.e. the new category name matches the current
package 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
Notice also that the warning is reported at the line where the object is first
used.
-=head1 TODO
+When registering new categories of warning, you can supply more names to
+warnings::register like this:
- perl5db.pl
- The debugger saves and restores C<$^W> at runtime. I haven't checked
- whether the debugger will still work with the lexical warnings
- patch applied.
+ package MyModule;
+ use warnings::register qw(format precision);
- diagnostics.pm
- I *think* I've got diagnostics to work with the lexical warnings
- patch, but there were design decisions made in diagnostics to work
- around the limitations of C<$^W>. Now that those limitations are gone,
- the module should be revisited.
+ ...
- document calling the warnings::* functions from XS
+ warnings::warnif('MyModule::format', '...');
=head1 SEE ALSO