<!-- category: hidden-gems -->

The diagnostics Pragma

2026-04-29

use warnings;
my @x = (1, 2, 3);
my $y = @x[1];

Scalar value @x[1] better written as $x[1] at script.pl line 3.

Until you ask nicely.

use diagnostics;
use warnings;
my @x = (1, 2, 3);
my $y = @x[1];

Scalar value @x[1] better written as $x[1] at script.pl line 4 (#1)
    (W syntax) You've used an array slice (indicated by @) to select a
    single element of an array.  Generally it's better to ask for a scalar
    value (indicated by $).  The difference is that $foo[&bar] always
    behaves like a scalar, both when assigning to it and when evaluating
    its argument, while @foo[&bar] behaves like a list when you assign
    to it, and provides a list context to its subscript, which can do
    weird things if you're expecting only one subscript.

Part 1: THE BASIC USAGE

use diagnostics;

#!/usr/bin/env perl
use strict;
use warnings;
use diagnostics;

my %h;
my $val = $h{nonexistent}{deep}{key};

#!/usr/bin/env perl
use strict;
use warnings;
use diagnostics;

print "hello" . undef;

Use of uninitialized value in concatenation (.) or string at
    script.pl line 6 (#1)
    (W uninitialized) An undefined value was used as if it were already
    defined.  It was interpreted as a "" or a 0, but maybe it was a
    mistake.  To suppress this warning assign a defined value to your
    variables.
    ...

Part 2: HOW IT WORKS UNDER THE HOOD

1. At compile time, it loads and parses the entire perldiag man page

1. It installs a $SIG{__WARN__} handler and a $SIG{__DIE__} handler

                Perl emits warning
                       |
                       v
            $SIG{__WARN__} fires
                       |
                       v
           diagnostics looks up the
           message pattern in perldiag
                       |
                       v
          Prints original message PLUS
          the multi-paragraph explanation

The lookup is pattern-based. Perl's diagnostic messages contain placeholders like %s and %d. The module matches your actual error text against these patterns to find the right explanation.

Part 3: BEFORE AND AFTER

TERSE: "my" variable $x masks earlier declaration
VERBOSE: You declared a variable with the same name in the same scope.
         The inner declaration hides the outer one. This is almost
         always a mistake.

TERSE: Useless use of a constant in void context
VERBOSE: You used a value (like a string or number) as a statement
         but didn't do anything with the result. Perl computed it
         and threw it away. You probably meant to assign it.

TERSE: Bareword "foo" not allowed while "strict subs" in use
VERBOSE: You used an unquoted string where Perl expected an operator
         or expression. Under strict subs, barewords aren't allowed
         as a safety measure. Quote it or declare a subroutine.

TERSE: Can't use string ("3") as an ARRAY ref
VERBOSE: You tried to dereference a plain string as if it were a
         reference. Something upstream gave you a string instead
         of the reference you expected.

Part 4: THE SPLAIN COMMAND

$ perl script.pl 2>&1 | splain

You can also use it on saved log files:

$ perl buggy_script.pl 2> errors.log
$ splain < errors.log

One difference: splain only processes text you feed it. It does not hook into your running program. If your script swallows warnings internally, splain will never see them.

Part 5: RUNTIME OVERHEAD

At compile time, it reads and parses the entire perldiag man page. That is a big document. On Perl 5.40, it is over 5,000 lines of diagnostic descriptions. Parsing that adds noticeable startup time.

# benchmark: startup time with and without diagnostics
# (rough numbers, vary by system)

# Without:
# $ time perl -e 'use strict; use warnings; 1'
# real    0m0.011s

# With:
# $ time perl -e 'use strict; use warnings; use diagnostics; 1'
# real    0m0.089s

The runtime overhead per warning is also nonzero. Every warning triggers a hash lookup and string concatenation. If your code emits thousands of warnings (maybe you should fix those), the diagnostics handler will slow things down.

Part 6: DEVELOPMENT ONLY

A clean pattern:

#!/usr/bin/env perl
use strict;
use warnings;

# Uncomment for verbose error explanations during development
# use diagnostics;

use feature 'say';

#!/usr/bin/env perl
use strict;
use warnings;

BEGIN
{
    if ($ENV{PERL_DIAGNOSTICS})
    {
        require diagnostics;
        diagnostics->import();
    }
}

$ PERL_DIAGNOSTICS=1 perl my_script.pl    # verbose
$ perl my_script.pl                        # normal

Part 7: COMBINING WITH WARNINGS

use warnings;
use diagnostics;

no warnings 'uninitialized';    # suppress these even with diagnostics

You can also use the -W flag for maximum coverage:

$ perl -W -Mdiagnostics script.pl

Part 8: THE PERLDIAG DOCUMENTATION

$ perldoc perldiag

- The message pattern with placeholders
- The severity category (W = warning, F = fatal, S = severe)
- The specific warning category (syntax, numeric, etc.)
- A paragraph or more of explanation
- Sometimes example code showing the fix

The diagnostics module just makes perldiag available at runtime, automatically, at the exact moment you need it.

Part 9: PRACTICAL DEBUGGING WORKFLOW

Step 1: Add diagnostics and run:

#!/usr/bin/env perl
use strict;
use warnings;
use diagnostics;
use feature 'say';

# ... your buggy code ...

Step 3: Fix the issue. Remove diagnostics. Run again.

#!/usr/bin/env perl
use strict;
use warnings;
use feature 'say';

# ... your fixed code ...

$ perl -Mdiagnostics -e 'my @x; print $x[0] + 1'

Part 10: WHY IT MATTERS

The information was always there. In perldiag. In the man pages. In perldoc. The diagnostics pragma just brings it to you at the moment you need it, without making you go look it up.

      .--.
     |o_o |     "I know what the error means.
     |:_/ |      I just wanted Perl to say it
    //   \ \     out loud."
   (|     | )
  /'\_   _/`\
  \___)=(___/

It is a development tool, not a production tool. It has startup overhead. It makes your error output verbose. But when you are staring at a message you do not understand, those are features, not drawbacks.

Add it when confused. Remove it when enlightened. Repeat for 30 years of Perl programming.

perl.gg