NAME

diagnostics - Perl compiler pragma to force verbose warning diagnostics

splain - standalone program to do the same thing

SYNOPSIS

As a pragma:

use diagnostics;
use diagnostics -verbose;
use diagnostics qw(-verbose -pretty -lang=fr -module=File::Compare -debug=63);

enable  diagnostics;
disable diagnostics;

As a program:

perl program 2>diag.out
splain [-v] [-p] [-l=fr] [-m=File::Compare] diag.out

DESCRIPTION

The diagnostics Pragma

This module extends the terse diagnostics normally emitted by both the perl compiler and the perl interpreter, augmenting them with the more explicative and endearing descriptions found in perldiag. Like the other pragmata, it affects the compilation phase of your program rather than merely the execution phase.

To use in your program as a pragma, merely invoke

use diagnostics;

at the start (or near the start) of your program. (Note that this does enable perl's -w flag.) Your whole compilation will then be subject(ed :-) to the enhanced diagnostics. These still go out STDERR.

Due to the interaction between runtime and compiletime issues, and because it's probably not a very good idea anyway, you may not use no diagnostics to turn them off at compiletime. However, you may control their behaviour at runtime using the disable() and enable() methods to turn them off and on respectively.

Warnings dispatched from perl itself (or more accurately, those that match descriptions found in perldiag) are only displayed once (no duplicate descriptions). Module generated warnings follow the same rules if the user asked for this module with the -module option. User code generated warnings ala warn() are unaffected, allowing duplicate user messages to be displayed.

The splain Program

While apparently a whole nuther program, splain is actually nothing more than a link to the (executable) diagnostics.pm module, as well as a link to the diagnostics.pod documentation. Since you're post-processing with splain, there's no sense in being able to enable() or disable() processing.

Output from splain is directed to STDOUT, unlike the pragma.

Flags and options

-verbose

The -verbose flag first prints out the perldiag introduction before any other diagnostics. It can be abbreviated to -v.

-pretty

The -pretty or -p flag can generate nicer escape sequences for pagers.

-lang

The -lang or -l option looks for a translation of perldiag instead of the English version.

-module

The -module option looks for a module-specific perldiag file or for splanations within the POD documentation of the module itself. It can be abbreviated to -m.

If a module is specified, the errors and warnings from the Perl compiler / interpreter are not longer splained. Yet, if you specify the pseudo-module perl together with the module you requested, the standard errors and warnings will be splained, as well as the module's.

-file

The -file option allows you to specify a file to read instead of, or in addition to, perldiag files. The value is the absolute or relative pathname to the file.

As with the -module option, using this option disables the splanations for standard errors. And as with the -module option, the standard errors' explanations are reenabled by adding the -module=perl option.

-encoding

Select the output character encoding.

EXAMPLES

The following file is certain to trigger a few errors at both runtime and compiletime:

use diagnostics;
print NOWHERE "nothing\n";
print STDERR "\n\tThis message should be unadorned.\n";
warn "\tThis is a user warning";
print "\nDIAGNOSTIC TESTER: Please enter a <CR> here: ";
my $a, $b = scalar <STDIN>;
print "\n";
print $x/$y;

If you prefer to run your program first and look at its problem afterwards, do this:

perl -w test.pl 2>test.out
./splain < test.out

Note that this is not in general possible in shells of more dubious heritage, as the theoretical

(perl -w test.pl >/dev/tty) >& test.out
./splain < test.out

Because you just moved the existing stdout to somewhere else.

If you don't want to modify your source code, but still have on-the-fly warnings, do this:

exec 3>&1; perl -w test.pl 2>&1 1>&3 3>&- | splain 1>&2 3>&- 

Nifty, eh?

Or else, you can type:

perl -M'diagnostics qw(-pretty -lang=fr -module=File::Compare)' test.pl

If you want to control warnings on the fly, do something like this. Make sure you do the use first, or you won't be able to get at the enable() or disable() methods.

    use diagnostics; # checks entire compilation phase 
	print "\ntime for 1st bogus diags: SQUAWKINGS\n";
	print BOGUS1 'nada';
	print "done with 1st bogus\n";

    disable diagnostics; # only turns off runtime warnings
	print "\ntime for 2nd bogus: (squelched)\n";
	print BOGUS2 'nada';
	print "done with 2nd bogus\n";

    enable diagnostics; # turns back on runtime warnings
	print "\ntime for 3rd bogus: SQUAWKINGS\n";
	print BOGUS3 'nada';
	print "done with 3rd bogus\n";

    disable diagnostics;
	print "\ntime for 4th bogus: (squelched)\n";
	print BOGUS4 'nada';
	print "done with 4th bogus\n";

I18N

A French (for example) coder can use:

use diagnostics '-lang=fr';
print 2 / $x;

But you can specify several languages. A coder in a Swiss team would write:

use diagnostics qw(-lang=de -lang=it -lang=fr);
print 2 / $x;

When the coder specifies one or more languages, English is not longer used, unless explicitely requested. E.g. a Canadian team would write:

use diagnostics qw(-l=en -l=fr);
print 2 / $x;

Note however there is a significant performance penalty when the pragmatic module loads a perldiag file, and this penalty is multiplied when using several languages.

MODULES

If a coder types:

use diagnostics '-module=Foo::Bar';
use Foo::Bar;

the diagnostics module will search each directory in @INC, looking for Foo/Bar/perldiag.pod or Foo/Bar.pm. And if Foo/Bar.pm has been written with diagnostics in mind, the inline doc will contain the list of error messages with the proper explanations.

The use diagnostics statement should be executed before the use Foo::Bar statement, because the module may emit errors or warnings at require time or import time.

To get explanations for both the module's errors and Perl's errors, type:

use diagnostics qw(-module=Foo::Bar -module=perl);
use Foo::Bar;

The -module and -lang options may be combined. In this case, by typing

use diagnostics qw(-module=Foo::Bar -lang=fr);
use Foo::Bar;

the diagnostics module will look only for Foo/Bar/perldiag.fr.pod or Foo/Bar.fr.pod in the various @INC directories.

INTERNALS

Diagnostic messages derive from the perldiag.pod file when available at runtime. Otherwise, they may be embedded in the file itself when the splain package is built. See the Makefile for details.

If an extant $SIG{__WARN__} handler is discovered, it will continue to be honored, but only after the diagnostics::splainthese() function (the module's $SIG{__WARN__} interceptor) has had its way with your warnings.

There is a -debug option and a $diagnostics::DEBUG variable you may set if you're desperately curious what sorts of things are being intercepted.

use diagnostics -debug=63;

This option contains powers of 2 OR'ed together. Each power of two prints some piece of debugging. For more information, RTFS (you were going to debug the module, so you would have Read The Famous Source anyhow, wouldn't ya?).

For backward compatibility, you can activate the various options by initializing the variables $diagnostics::PRETTY or $diagnostics::DEBUG and other instead of using dash options.

KNOWN BUGS

Not being able to say no diagnostics is annoying, but may not be insurmountable.

I could start up faster by delaying compilation until it should be needed, but this gets a "panic: top_level" when using the pragma form in Perl 5.001e.

Since delayed compilation is not possible, there is a systematic performance penalty. Therefore, unlike use strict and use warnings, you should not use this module in production programs.

While it's true that this documentation is somewhat subserious, if you use a program named splain, you should expect a bit of whimsy.

UNKNOWN BUGS

If you find what you believe is a bug, check your version of diagnostics.pm. If it is 1.1 or less, report it at http://bugs.perl.org/, as for any bug from the core or from a standard module. Be sure to include diagnostics.pm in the subject, I check this regularly, so I can test this bug on the alpha version, and possibly fix it.

If it is 1.2-alpha, report it to me JFORGET@cpan.org. As long as the 5.8.1 version is not released I will support this version. After that, it will be a Perl-5 Porters' module again (although I will still be interested in it).

AUTHORS

The stable 1.1 version is maintained by the Perl-5 Porters (http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/)

The initial version was written by Tom Christiansen <tchrist@mox.perl.com>, 25 June 1995.

The new 1.2 version was written by Jean Forget (JFORGET@cpan.org), with some help from Gérald, Philippe, Rafael and O'Reilly France, 2 July 2002.

cpanm diagnostics

perl -MCPAN -e shell
install diagnostics