The pragma works just like the existing "strict" pragma.
This means that the scope of the warning pragma is limited to the
-enclosing block. It also means that that the pragma setting will not
+enclosing block. It also means that the pragma setting will not
leak across files (via C<use>, C<require> or C<do>). This allows
authors to independently define the degree of warning checks that will
be applied to their module.
=back
-The combined effect of 3 & 4 is that it will will allow code which uses
+The combined effect of 3 & 4 is that it will allow code which uses
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.
=head2 Reporting Warnings from a Module
-The C<warnings> pragma provides two functions, namely C<warnings::enabled>
-and C<warnings::warn>, that are useful for module authors. They are
-used when you want to report a module-specific warning, but only when
-the calling module has enabled warnings via the C<warnings> pragma.
+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<abc> below.
+Consider the module C<MyMod::Abc> below.
- package abc;
+ package MyMod::Abc;
- sub open
- {
- if (warnings::enabled("deprecated")) {
- warnings::warn("deprecated",
- "abc::open is deprecated. Use abc:new") ;
+ 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 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(@_) ;
}
"deprecated" warnings category enabled. Something like this, say.
use warnings 'deprecated';
- use abc;
+ use MyMod::Abc;
...
- abc::open($filename) ;
+ 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
-If the calling module has escalated the "deprecated" warnings category
-into a fatal error like this:
-
- use warnings 'FATAL deprecated';
- use abc;
+ use MyMod::Abc;
+ use warnings FATAL => 'MyMod::Abc';
...
- abc::open($filename) ;
+ 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 ;
+ }
-then C<warnings::warn> will detect this and die after displaying the
-warning message.
+ 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
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>.
projects / p5sagit/p5-mst-13.2.git / blobdiff