Perl Hacks

Hack #41. Create Your Own Lexical Warnings

Add your own warnings to the warnings pragma.

Perl 5.6 added a useful pragma called warnings that expanded and enhanced upon the -w and -W switches. This pragma introduced warnings scoped lexically. Within a lexical scope you can enable and disable warnings as a whole or by particular class.

For example, within a say( ) function emulating the Perl 6 operator, you could respect the current value of $, (the output field separator) and not throw useless warnings about its definedness with:

use warnings;

# ... more code here...

sub say
{
    no warnings 'uninitialized';
    print join( $,, @_ ), "\\n";
}

See perllexwarn for a list of all of the types of warnings you can enable and disable.

When you write your own module, you can even create your own warnings categories for users of your code to enable and disable as they see fit. It's easy.

The Hack

To create a warning, use the warnings::register pragma in your code. That's it. The UNIVERSAL::can module^[2] does this.

Within the module, when it detects code that uses UNIVERSAL::can( ) as a function, it checks that the calling code has enabled warnings, then uses warnings::warn( ) to report the error:

if (warnings::enabled( ))
{
    warnings::warn( "Called UNIVERSAL::can( ) as a function, not a method" );
}

Running the Hack

How does this look from code that merely uses the module? If the calling code doesn't use warnings, nothing happens. Otherwise, it warns as normal. To enable or disable the specific class of warning, use:

# enable
use warnings 'UNIVERSAL::can';

# disable
no warnings 'UNIVERSAL::can';

Hacking the Hack

You can also re-use existing warnings categories. For example, if you want to mark a particular interface as deprecated, write a wrapper for the new function that warns when users use the old one:

sub yucky_function
{
    my ($package, $filename, $line) = caller( );

    warnings::warnif( 'deprecated',
        "yucky_function( ) is deprecated at $filename:$line\\n" );

    goto &yummy_function;
}

Tip

This version of goto replaces the original call in the call stack by calling the new function with the current contents of @_.

Now when users use the warnings pragma with no arguments (or enable deprecated warnings), they'll receive a warning suggesting where and how to update their code.

---

^[2] Which detects, reports, and attempts to fix the anti-pattern of people calling UNIVERSAL::can( ) as a function, not a method.