perlfunc
root
<P>
diagnostics - Perl compiler pragma to force verbose warning diagnostics
<P>
splain - standalone program to do the same thing
<P>
<HR>
<P>
As a pragma:
<P>
<PRE> use diagnostics;
use diagnostics -verbose;
</PRE>
<P>
<PRE> enable diagnostics;
disable diagnostics;
</PRE>
<P>
Aa a program:
<P>
<PRE> perl program 2>diag.out
splain [-v] [-p] dia
<P>
<HR>
<H2><A NAME="The_C_diagnostics_Pragma">The <CODE>diagnostics</CODE> Pragma</A></H2>
<P>
This module extends the terse diagnostics normally emitted by both the perl
compiler and the perl interpeter, augmenting them with the more explicative
and endearing descriptions found in [perlman:perldiag|perldiag]. Like the other pragmata, it affects the compilation phase of your program
rather than merely the execution phase.
<P>
To use in your program as a pragma, merely invoke
<P>
<PRE> use diagnostics;
</PRE>
<P>
at the start (or near the start) of your program. (Note that this <EM>does</EM> enable perl's <STRONG>-w</STRONG> flag.) Your whole compilation will then be
<CODE>subject(ed</CODE> :-) to the
enhanced diagnostics. These still go out <STRONG>STDERR</STRONG>.
<P>
Due to the interaction between runtime and compiletime issues, and because
it's probably not a very good idea anyway, you may not use <CODE>no diagnostics</CODE> to turn them off at compiletime. However, you may control there behaviour at runtime using the
<CODE>disable()</CODE> and
<CODE>enable()</CODE> methods to turn them off and on respectively.
<P>
The <STRONG>-verbose</STRONG> flag first prints out the [perlman:perldiag|perldiag] introduction before any other diagnostics. The $diagnostics::PRETTY
variable can generate nicer escape sequences for pagers.
<P>
<HR>
<H2><A NAME="The_I_splain_Program">The <EM>splain</EM> Program</A></H2>
<P>
While apparently a whole nuther program, <EM>splain</EM> is actually nothing more than a link to the (executable) <EM>diagnostics.pm</EM> module, as well as a link to the <EM>diagnostics.pod</EM> documentation. The <STRONG>-v</STRONG> flag is like the <CODE>use diagnostics -verbose</CODE> directive. The <STRONG>-p</STRONG> flag is like the $diagnostics::PRETTY variable. Since you're
post-processing with
<EM>splain</EM>, there's no sense in being able to
<CODE>enable()</CODE> or
<CODE>disable()</CODE> processing.
<P>
Output from <EM>splain</EM> is directed to <STRONG>STDOUT</STRONG>, unlike the pragma.
<P>
<HR>
<H1><A NAME="EXAMPLES">EXAMPLES</A></H1>
<P>
The following file is certain to trigger a few errors at both runtime and
compiletime:
<P>
<PRE> 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;
</PRE>
<P>
If you prefer to run your program first and look at its problem afterwards,
do this:
<P>
<PRE> perl -w test.pl 2>test.out
./splain < test.out
</PRE>
<P>
Note that this is not in general possible in shells of more dubious
heritage, as the theoretical
<P>
<PRE> (perl -w test.pl >/dev/tty) >& test.out
./splain < test.out
</PRE>
<P>
Because you just moved the existing <STRONG>stdout</STRONG> to somewhere else.
<P>
If you don't want to modify your source code, but still have on-the-fly
warnings, do this:
<P>
<PRE> exec 3>&1; perl -w test.pl 2>&1 1>&3 3>&- | splain 1>&2 3>&-
</PRE>
<P>
Nifty, eh?
<P>
If you want to control warnings on the fly, do something like this. Make
sure you do the [perlfunc:use|use] first, or you won't be able to get at the
<CODE>enable()</CODE> or
<CODE>disable()</CODE> methods.
<P>
<PRE> use diagnostics; # checks entire compilation phase
print "\ntime for 1st bogus diags: SQUAWKINGS\n";
print BOGUS1 'nada';
print "done with 1st bogus\n";
</PRE>
<P>
<PRE> disable diagnostics; # only turns off runtime warnings
print "\ntime for 2nd bogus: (squelched)\n";
print BOGUS2 'nada';
print "done with 2nd bogus\n";
</PRE>
<P>
<PRE> enable diagnostics; # turns back on runtime warnings
print "\ntime for 3rd bogus: SQUAWKINGS\n";
print BOGUS3 'nada';
print "done with 3rd bogus\n";
</PRE>
<P>
<PRE> disable diagnostics;
print "\ntime for 4th bogus: (squelched)\n";
print BOGUS4 'nada';
print "done with 4th bogus\n";
</PRE>
<P>
<HR>
<H1><A NAME="INTERNALS">INTERNALS</A></H1>
<P>
Diagnostic messages derive from the <EM>perldiag.pod</EM> file when available at runtime. Otherwise, they may be embedded in the file
itself when the splain package is built. See the <EM>Makefile</EM> for details.
<P>
If an extant
<FONT SIZE=-1>$SIG{__WARN__}</FONT> handler is discovered, it will continue to be honored, but only after the diagnostics::splainthis() function (the module's
<FONT SIZE=-1>$SIG{__WARN__}</FONT> interceptor) has had its way with your warnings.
<P>
There is a $diagnostics::DEBUG variable you may set if you're desperately
curious what sorts of things are being intercepted.
<P>
<PRE> BEGIN { $diagnostics::DEBUG = 1 }
</PRE>
<P>
<HR>
<H1><A NAME="BUGS">BUGS</A></H1>
<P>
Not being able to say ``no diagnostics'' is annoying, but may not be
insurmountable.
<P>
The <CODE>-pretty</CODE> directive is called too late to affect matters. You have to do this
instead, and <EM>before</EM> you load the module.
<P>
<PRE> BEGIN { $diagnostics::PRETTY = 1 }
</PRE>
<P>
<FONT SIZE=-1>I</FONT> 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.
<P>
While it's true that this documentation is somewhat subserious, if you use
a program named <EM>splain</EM>, you should expect a bit of whimsy.
<P>
<HR>
<H1><A NAME="AUTHOR">AUTHOR</A></H1>
<P>
Tom Christiansen <<EM>tchrist@mox.perl.com</EM>>, 25 June 1995.
<HR>