For example, consider the code below:
use warnings ;
- my $a ;
- my $b ;
+ my @a ;
{
no warnings ;
- $b = 2 if $a EQ 3 ;
+ my $b = @a[0] ;
}
- $b = 1 if $a NE 3 ;
+ my $c = @a[0];
The code in the enclosing block has warnings enabled, but the inner
-block has them disabled. In this case that means that the use of the C<EQ>
-operator won't trip a C<"Use of EQ is deprecated"> warning, but the use of
-C<NE> will produce a C<"Use of NE is deprecated"> warning.
+block has them disabled. In this case that means the assignment to the
+scalar C<$c> will trip the C<"Scalar value @a[0] better written as $a[0]">
+warning, but the assignment to the scalar C<$b> will not.
=head2 Default Warnings and Optional Warnings
my $b ; chop $b ;
}
-The other big problem with C<$^W> is that way you can inadvertently
+The other big problem with C<$^W> is the way you can inadvertently
change the warning setting in unexpected places in your code. For example,
when the code below is run (without the B<-w> flag), the second call
to C<doit> will trip a C<"Use of uninitialized value"> warning, whereas
all -+
|
- +- chmod
+ +- assertions
|
+- closure
|
+ +- deprecated
+ |
+- exiting
|
+- glob
| |
| +- exec
| |
+ | +- layer
+ | |
| +- newline
| |
| +- pipe
| |
| +- bareword
| |
- | +- deprecated
- | |
| +- digit
| |
| +- parenthesis
|
+- taint
|
- +- umask
+ +- threads
|
+- uninitialized
|
To determine which category a specific warning has been assigned to see
L<perldiag>.
+Note: In Perl 5.6.1, 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
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, there are 3 places where a
-deprecated warning will be detected, the middle one will produce a
-fatal error.
-
+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 ;
- $a = 1 if $a EQ $b ;
+ time ;
{
- use warnings FATAL => qw(deprecated) ;
- $a = 1 if $a EQ $b ;
+ use warnings FATAL => qw(void) ;
+ length "abc" ;
}
- $a = 1 if $a EQ $b ;
+ 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 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';
=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>
+warning to a calling module has enabled warnings via the C<warnings>
pragma.
Consider the module C<MyMod::Abc> below.
sub open {
my $path = shift ;
- if (warnings::enabled() && $path !~ m#^/#) {
- warnings::warn("changing relative path to /tmp/");
+ if ($path !~ m#^/#) {
+ warnings::warn("changing relative path to /tmp/")
+ if warnings::enabled();
$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.
+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';
package MyMod::Abc;
sub open {
- if (warnings::enabled("deprecated")) {
- warnings::warn("deprecated",
- "open is deprecated, use new instead") ;
- }
+ warnings::warnif("deprecated",
+ "open is deprecated, use new instead") ;
new(@_) ;
}
...
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
+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::warn> function will detect this and die after
+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 = new Original ;
+ $a->doit(1) ;
+ my $b = new Derived ;
+ $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.
+
=head1 TODO
perl5db.pl
around the limitations of C<$^W>. Now that those limitations are gone,
the module should be revisited.
+ document calling the warnings::* functions from XS
+
=head1 SEE ALSO
L<warnings>, L<perldiag>.
https://perl5.git.perl.org / perl5.git / blobdiff