352 lines
8.0 KiB
HTML
352 lines
8.0 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of SPLAIN</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>SPLAIN</H1>
|
|
Section: Perl Programmers Reference Guide (1)<BR>Updated: 2020-10-19<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
diagnostics, splain - produce verbose warning diagnostics
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
|
|
Using the <TT>"diagnostics"</TT> pragma:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
use diagnostics;
|
|
use diagnostics -verbose;
|
|
|
|
enable diagnostics;
|
|
disable diagnostics;
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Using the <TT>"splain"</TT> standalone filter program:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
perl program 2>diag.out
|
|
splain [-v] [-p] diag.out
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Using diagnostics to get stack traces from a misbehaving script:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
perl -Mdiagnostics=-traceonly my_script.pl
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
|
|
|
|
<A NAME="lbAE"> </A>
|
|
<H3>The diagnostics Pragma</H3>
|
|
|
|
|
|
|
|
|
|
|
|
This module extends the terse diagnostics normally emitted by both the
|
|
perl compiler and the perl interpreter (from running perl with a -w
|
|
switch or <TT>"use warnings"</TT>), 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.
|
|
<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 <I>does</I> enable perl's <B>-w</B> flag.) Your whole
|
|
compilation will then be subject(ed :-) to the enhanced diagnostics.
|
|
These still go out <B></B><FONT SIZE="-1"><B>STDERR</B></FONT><B></B>.
|
|
<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 <TT>"no diagnostics"</TT> to turn them off at compiletime.
|
|
However, you may control their behaviour at runtime using the
|
|
<B>disable()</B> and <B>enable()</B> methods to turn them off and on respectively.
|
|
<P>
|
|
|
|
The <B>-verbose</B> flag first prints out the perldiag introduction before
|
|
any other diagnostics. The <TT>$diagnostics::PRETTY</TT> variable can generate nicer
|
|
escape sequences for pagers.
|
|
<P>
|
|
|
|
Warnings dispatched from perl itself (or more accurately, those that match
|
|
descriptions found in perldiag) are only displayed once (no duplicate
|
|
descriptions). User code generated warnings a la <B>warn()</B> are unaffected,
|
|
allowing duplicate user messages to be displayed.
|
|
<P>
|
|
|
|
This module also adds a stack trace to the error message when perl dies.
|
|
This is useful for pinpointing what
|
|
caused the death. The <B>-traceonly</B> (or
|
|
just <B>-t</B>) flag turns off the explanations of warning messages leaving just
|
|
the stack traces. So if your script is dieing, run it again with
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
perl -Mdiagnostics=-traceonly my_bad_script
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
to see the call stack at the time of death. By supplying the <B>-warntrace</B>
|
|
(or just <B>-w</B>) flag, any warnings emitted will also come with a stack
|
|
trace.
|
|
<A NAME="lbAF"> </A>
|
|
<H3>The <I>splain</I> Program</H3>
|
|
|
|
|
|
|
|
While apparently a whole nuther program, <I>splain</I> is actually nothing
|
|
more than a link to the (executable) <I>diagnostics.pm</I> module, as well as
|
|
a link to the <I>diagnostics.pod</I> documentation. The <B>-v</B> flag is like
|
|
the <TT>"use diagnostics -verbose"</TT> directive.
|
|
The <B>-p</B> flag is like the
|
|
<TT>$diagnostics::PRETTY</TT> variable. Since you're post-processing with
|
|
<I>splain</I>, there's no sense in being able to <B>enable()</B> or <B>disable()</B> processing.
|
|
<P>
|
|
|
|
Output from <I>splain</I> is directed to <B></B><FONT SIZE="-1"><B>STDOUT</B></FONT><B></B>, unlike the pragma.
|
|
<A NAME="lbAG"> </A>
|
|
<H2>EXAMPLES</H2>
|
|
|
|
|
|
|
|
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 <B>stdout</B> 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 <TT>"use"</TT> first, or you won't be able to get
|
|
at the <B>enable()</B> or <B>disable()</B> 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";
|
|
|
|
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";
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAH"> </A>
|
|
<H2>INTERNALS</H2>
|
|
|
|
|
|
|
|
Diagnostic messages derive from the <I>perldiag.pod</I> file when available at
|
|
runtime. Otherwise, they may be embedded in the file itself when the
|
|
splain package is built. See the <I>Makefile</I> for details.
|
|
<P>
|
|
|
|
If an extant <TT>$SIG</TT>{__WARN__} handler is discovered, it will continue
|
|
to be honored, but only after the <B>diagnostics::splainthis()</B> function
|
|
(the module's <TT>$SIG</TT>{__WARN__} interceptor) has had its way with your
|
|
warnings.
|
|
<P>
|
|
|
|
There is a <TT>$diagnostics::DEBUG</TT> variable you may set if you're desperately
|
|
curious what sorts of things are being intercepted.
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
BEGIN { $diagnostics::DEBUG = 1 }
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAI"> </A>
|
|
<H2>BUGS</H2>
|
|
|
|
|
|
|
|
Not being able to say ``no diagnostics'' is annoying, but may not be
|
|
insurmountable.
|
|
<P>
|
|
|
|
The <TT>"-pretty"</TT> directive is called too late to affect matters.
|
|
You have to do this instead, and <I>before</I> you load the module.
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
BEGIN { $diagnostics::PRETTY = 1 }
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
While it's true that this documentation is somewhat subserious, if you use
|
|
a program named <I>splain</I>, you should expect a bit of whimsy.
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>AUTHOR</H2>
|
|
|
|
|
|
|
|
Tom Christiansen <<I><A HREF="mailto:tchrist@mox.perl.com">tchrist@mox.perl.com</A></I>>, 25 June 1995.
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="1"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="2"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="3"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DL>
|
|
<DT id="4"><A HREF="#lbAE">The diagnostics Pragma</A><DD>
|
|
<DT id="5"><A HREF="#lbAF">The <I>splain</I> Program</A><DD>
|
|
</DL>
|
|
<DT id="6"><A HREF="#lbAG">EXAMPLES</A><DD>
|
|
<DT id="7"><A HREF="#lbAH">INTERNALS</A><DD>
|
|
<DT id="8"><A HREF="#lbAI">BUGS</A><DD>
|
|
<DT id="9"><A HREF="#lbAJ">AUTHOR</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:27 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|