+=for warnings.pl tree-goes-here
+
+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>.
+
+Note: Before Perl 5.8.0, the lexical warnings category "deprecated" was a
+sub-category of the "syntax" category. It is now a top-level category
+in its own right.
+
+=head2 Fatal Warnings
+X<warning, fatal>
+
+The presence of the word "FATAL" in the category list will escalate any
+warnings detected from the categories specified in the lexical scope
+into fatal errors. In the code below, the use of C<time>, C<length>
+and C<join> can all produce a C<"Useless use of xxx in void context">
+warning.
+
+ use warnings;
+
+ time;
+
+ {
+ use warnings FATAL => qw(void);
+ length "abc";
+ }
+
+ join "", 1,2,3;
+
+ print "done\n";
+
+When run it produces this output
+
+ Useless use of time in void context at fatal line 3.
+ Useless use of length in void context at fatal line 7.
+
+The scope where C<length> is used has escalated the C<void> warnings
+category into a fatal error, so the program terminates immediately when it
+encounters the warning.
+
+To explicitly turn off a "FATAL" warning you just disable the warning
+it is associated with. So, for example, to disable the "void" warning
+in the example above, either of these will do the trick:
+
+ no warnings qw(void);
+ no warnings FATAL => qw(void);
+
+If you want to downgrade a warning that has been escalated into a fatal
+error back to a normal warning, you can use the "NONFATAL" keyword. For
+example, the code below will promote all warnings into fatal errors,
+except for those in the "syntax" category.
+
+ use warnings FATAL => 'all', NONFATAL => 'syntax';
+
+As of Perl 5.20, instead of C<< use warnings FATAL => 'all'; >> you can
+use:
+
+ use v5.20; # Perl 5.20 or greater is required for the following
+ use warnings 'FATAL'; # short form of "use warnings FATAL => 'all';"
+
+If you want your program to be compatible with versions of Perl before
+5.20, you must use C<< use warnings FATAL => 'all'; >> instead. (In
+previous versions of Perl, the behavior of the statements
+C<< use warnings 'FATAL'; >>, C<< use warnings 'NONFATAL'; >> and
+C<< no warnings 'FATAL'; >> was unspecified; they did not behave as if
+they included the C<< => 'all' >> portion. As of 5.20, they do.)
+
+B<NOTE:> Users of FATAL warnings, especially
+those using C<< FATAL => 'all' >>
+should be fully aware that they are risking future portability of their
+programs by doing so. Perl makes absolutely no commitments to not
+introduce new warnings, or warnings categories in the future, and indeed
+we explicitly reserve the right to do so. Code that may not warn now may
+warn in a future release of Perl if the Perl5 development team deems it
+in the best interests of the community to do so. Should code using FATAL
+warnings break due to the introduction of a new warning we will NOT
+consider it an incompatible change. Users of FATAL warnings should take
+special caution during upgrades to check to see if their code triggers
+any new warnings and should pay particular attention to the fine print of
+the documentation of the features they use to ensure they do not exploit
+features that are documented as risky, deprecated, or unspecified, or where
+the documentation says "so don't do that", or anything with the same sense
+and spirit. Use of such features in combination with FATAL warnings is
+ENTIRELY AT THE USER'S RISK.
+
+=head2 Reporting Warnings from a Module
+X<warning, reporting> X<warning, registering>
+
+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 to a 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 ($path !~ m#^/#) {
+ warnings::warn("changing relative path to /var/abc")
+ if warnings::enabled();
+ $path = "/var/abc/$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 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
+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 {
+ warnings::warnif("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);
+
+Either the C<warnings::warn> or C<warnings::warnif> 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::warnif> function will detect this and die after
+displaying the warning message.
+
+The three warnings functions, C<warnings::warn>, C<warnings::warnif>
+and C<warnings::enabled> can optionally take an object reference in place
+of a category name. In this case the functions will use the class name
+of the object as the warnings category.
+
+Consider this example:
+
+ package Original;
+
+ no warnings;
+ use warnings::register;
+
+ sub new
+ {
+ my $class = shift;
+ bless [], $class;
+ }
+
+ sub check
+ {
+ my $self = shift;
+ my $value = shift;
+
+ if ($value % 2 && warnings::enabled($self))
+ { warnings::warn($self, "Odd numbers are unsafe") }
+ }
+
+ sub doit
+ {
+ my $self = shift;
+ my $value = shift;
+ $self->check($value);
+ # ...
+ }
+
+ 1;
+
+ package Derived;
+
+ use warnings::register;
+ use Original;
+ our @ISA = qw( Original );
+ sub new
+ {
+ my $class = shift;
+ bless [], $class;
+ }
+
+
+ 1;
+
+The code below makes use of both modules, but it only enables warnings from
+C<Derived>.
+
+ use Original;
+ use Derived;
+ use warnings 'Derived';
+ my $a = Original->new();
+ $a->doit(1);
+ my $b = Derived->new();
+ $a->doit(1);
+
+When this code is run only the C<Derived> object, C<$b>, will generate
+a warning.
+
+ Odd numbers are unsafe at main.pl line 7
+
+Notice also that the warning is reported at the line where the object is first
+used.
+
+When registering new categories of warning, you can supply more names to
+warnings::register like this:
+
+ package MyModule;
+ use warnings::register qw(format precision);
+
+ ...
+
+ warnings::warnif('MyModule::format', '...');
+
+=head1 FUNCTIONS