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. 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 wll 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 the -module option, the standard errors' explanations are reenabled by adding the -module=perl option.

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;

Yet, there is a catch. When comparing the actual errors to the errors contained in the perldiag.pod files, the comparison ends with the first match, which is not always the right match. For example, compare the result of the following two programs:

use diagnostics qw(-module=lib -module=perl);
use lib '';

use diagnostics qw(-module=perl -module=lib);
use lib '';

In the first case, you obtain the proper explanation, while in the second case you obtain the wrong one.

The -module and B-<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 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.

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.

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?).

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 (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.

Why 33? The first answer is, the value 1 is only a Perl tradition, not a requirement. Any true value will do (Cf. the Ram Book, introduction to chapter 12).

The second answer is, 33 is the traditional value in France when a physician examines a patient. The physician applies his stethoscope to the patient's chest, and orders - Breathe through your mouth. - Cough. - Dites trente-trois.

By the way, this reminds me of a gag in the movie La Grande Vadrouille, which applies both to I18N and diagnostics. The film takes place in Nazi-occupied France, in 1941 or 1942. A British pilot has been shot down over France, but he has been fetched by an escape organization, which leads Jews and RAF airmen through the demarcation line to the unoccupied half of France. He is accompanied by a young nurse, member of the underground. Because of some delay, she places him in a hospital where he will stay for the night.

Morning comes, and before the pilot can leave, the head nurse comes to visit all her patients. The head nurse is not a member of the underground, but she has more sympathies to them than to the German occupiers. She arrives at the pilot's bed, takes her stethoscope and starts the examination.

Head nurse: - Respirez par la bouche - Breathe through your mouth. - Toussez. - Cough. - Dites trente-trois - Say 33.

The pilot cast an interrogative look at the young nurse, who answers with a nod and a reassuring smile.

Pilot: - Thirty-three.

Heavy silence, and puzzled look on the head nurse's face. And then,

Head nurse (to the young nurse): - Je vois. Il doit aller - I see. He must go to the à la campagne prendre l'air. countryside to get fresh air.

And the pilot and the nurse left... for the unoccupied half of France.

cpanm diagnostics

perl -MCPAN -e shell
install diagnostics