- publishing free software manuals
Perl Language Reference Manual
by Larry Wall and others
Paperback (6"x9"), 724 pages
ISBN 9781906966027
RRP £29.95 ($39.95)

Sales of this book support The Perl Foundation! Get a printed copy>>>

24.7 Reporting Warnings from a Module

The 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 warnings pragma.

Consider the module 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 warnings::register will create a new warnings category called "MyMod::Abc", i.e. the new category name matches the current package name. The 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 MyMod::Abc has actually enabled them with the 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 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 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 warnings::warn or 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 warnings::warnif function will detect this and die after displaying the warning message.

The three warnings functions, warnings::warn, warnings::warnif and 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 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 Derived object, $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.

ISBN 9781906966027Perl Language Reference ManualSee the print edition