diagnostics.html
来自「perl教程」· HTML 代码 · 共 221 行
HTML
221 行
<?xml version="1.0" ?>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<!-- saved from url=(0017)http://localhost/ -->
<script language="JavaScript" src="../displayToc.js"></script>
<script language="JavaScript" src="../tocParas.js"></script>
<script language="JavaScript" src="../tocTab.js"></script>
<link rel="stylesheet" type="text/css" href="../scineplex.css">
<title>splain - produce verbose warning diagnostics</title>
<link rel="stylesheet" href="../Active.css" type="text/css" />
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:" />
</head>
<body>
<script>writelinks('__top__',1);</script>
<h1><a>splain - produce verbose warning diagnostics</a></h1>
<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->
<ul>
<li><a href="#name">NAME</a></li>
<li><a href="#synopsis">SYNOPSIS</a></li>
<li><a href="#description">DESCRIPTION</a></li>
<ul>
<li><a href="#the_diagnostics_pragma">The <code>diagnostics</code> Pragma</a></li>
<li><a href="#the_splain_program">The <em>splain</em> Program</a></li>
</ul>
<li><a href="#examples">EXAMPLES</a></li>
<li><a href="#internals">INTERNALS</a></li>
<li><a href="#bugs">BUGS</a></li>
<li><a href="#author">AUTHOR</a></li>
</ul>
<!-- INDEX END -->
<hr />
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>diagnostics, splain - produce verbose warning diagnostics</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<p>Using the <code>diagnostics</code> pragma:</p>
<pre>
<span class="keyword">use</span> <span class="variable">diagnostics</span><span class="operator">;</span>
<span class="keyword">use</span> <span class="variable">diagnostics</span> <span class="operator">-</span><span class="variable">verbose</span><span class="operator">;</span>
</pre>
<pre>
<span class="variable">enable</span> <span class="variable">diagnostics</span><span class="operator">;</span>
<span class="variable">disable</span> <span class="variable">diagnostics</span><span class="operator">;</span>
</pre>
<p>Using the <code>splain</code> 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>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>
</p>
<h2><a name="the_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 interpreter (from running perl with a -w
switch or <code>use warnings</code>), augmenting them with the more
explicative and endearing descriptions found in <a href="../lib/Pod/perldiag.html">the perldiag manpage</a>. Like the
other pragmata, it affects the compilation phase of your program rather
than merely the execution phase.</p>
<p>To use in your program as a pragma, merely invoke</p>
<pre>
<span class="keyword">use</span> <span class="variable">diagnostics</span><span class="operator">;</span>
</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 subject(ed :-) to the enhanced diagnostics.
These still go out <strong>STDERR</strong>.</p>
<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 their behaviour at runtime using the
<code>disable()</code> and <code>enable()</code> methods to turn them off and on respectively.</p>
<p>The <strong>-verbose</strong> flag first prints out the <a href="../lib/Pod/perldiag.html">the perldiag manpage</a> introduction before
any other diagnostics. The $diagnostics::PRETTY variable can generate nicer
escape sequences for pagers.</p>
<p>Warnings dispatched from perl itself (or more accurately, those that match
descriptions found in <a href="../lib/Pod/perldiag.html">the perldiag manpage</a>) are only displayed once (no duplicate
descriptions). User code generated warnings a la <a href="../lib/Pod/perlfunc.html#item_warn"><code>warn()</code></a> are unaffected,
allowing duplicate user messages to be displayed.</p>
<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 <strong>-traceonly</strong> (or
just <strong>-t</strong>) 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 <strong>-warntrace</strong>
(or just <strong>-w</strong>) flag, any warnings emitted will also come with a stack
trace.</p>
<p>
</p>
<h2><a name="the_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>
<p>Output from <em>splain</em> is directed to <strong>STDOUT</strong>, unlike the pragma.</p>
<p>
</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>
<span class="keyword">use</span> <span class="variable">diagnostics</span><span class="operator">;</span>
<span class="keyword">print</span> <span class="variable">NOWHERE</span> <span class="string">"nothing\n"</span><span class="operator">;</span>
<span class="keyword">print</span> <span class="variable">STDERR</span> <span class="string">"\n\tThis message should be unadorned.\n"</span><span class="operator">;</span>
<span class="keyword">warn</span> <span class="string">"\tThis is a user warning"</span><span class="operator">;</span>
<span class="keyword">print</span> <span class="string">"\nDIAGNOSTIC TESTER: Please enter a <CR> here: "</span><span class="operator">;</span>
<span class="keyword">my</span> <span class="variable">$a</span><span class="operator">,</span> <span class="variable">$b</span> <span class="operator">=</span> <span class="keyword">scalar</span> <span class="operator"><</span><span class="variable">STDIN</span><span class="operator">>;</span>
<span class="keyword">print</span> <span class="string">"\n"</span><span class="operator">;</span>
<span class="keyword">print</span> <span class="variable">$x</span><span class="operator">/</span><span class="variable">$y</span><span class="operator">;</span>
</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>
<p>If you don't want to modify your source code, but still have on-the-fly
warnings, do this:</p>
<pre>
<span class="keyword">exec</span> <span class="number">3</span><span class="operator">>&</span><span class="number">1</span><span class="operator">;</span> <span class="variable">perl</span> <span class="keyword">-w</span> <span class="variable">test</span><span class="operator">.</span><span class="variable">pl</span> <span class="number">2</span><span class="operator">>&</span><span class="number">1</span> <span class="number">1</span><span class="operator">>&</span><span class="number">3</span> <span class="number">3</span><span class="operator">>&-</span> <span class="operator">|</span> <span class="variable">splain</span> <span class="number">1</span><span class="operator">>&</span><span class="number">2</span> <span class="number">3</span><span class="operator">>&-</span>
</pre>
<p>Nifty, eh?</p>
<p>If you want to control warnings on the fly, do something like this.
Make sure you do the <a href="../lib/Pod/perlfunc.html#item_use"><code>use</code></a> first, or you won't be able to get
at the <code>enable()</code> or <code>disable()</code> methods.</p>
<pre>
<span class="keyword">use</span> <span class="variable">diagnostics</span><span class="operator">;</span> <span class="comment"># checks entire compilation phase </span>
<span class="keyword">print</span> <span class="string">"\ntime for 1st bogus diags: SQUAWKINGS\n"</span><span class="operator">;</span>
<span class="keyword">print</span> <span class="variable">BOGUS1</span> <span class="string">'nada'</span><span class="operator">;</span>
<span class="keyword">print</span> <span class="string">"done with 1st bogus\n"</span><span class="operator">;</span>
</pre>
<pre>
<span class="variable">disable</span> <span class="variable">diagnostics</span><span class="operator">;</span> <span class="comment"># only turns off runtime warnings</span>
<span class="keyword">print</span> <span class="string">"\ntime for 2nd bogus: (squelched)\n"</span><span class="operator">;</span>
<span class="keyword">print</span> <span class="variable">BOGUS2</span> <span class="string">'nada'</span><span class="operator">;</span>
<span class="keyword">print</span> <span class="string">"done with 2nd bogus\n"</span><span class="operator">;</span>
</pre>
<pre>
<span class="variable">enable</span> <span class="variable">diagnostics</span><span class="operator">;</span> <span class="comment"># turns back on runtime warnings</span>
<span class="keyword">print</span> <span class="string">"\ntime for 3rd bogus: SQUAWKINGS\n"</span><span class="operator">;</span>
<span class="keyword">print</span> <span class="variable">BOGUS3</span> <span class="string">'nada'</span><span class="operator">;</span>
<span class="keyword">print</span> <span class="string">"done with 3rd bogus\n"</span><span class="operator">;</span>
</pre>
<pre>
<span class="variable">disable</span> <span class="variable">diagnostics</span><span class="operator">;</span>
<span class="keyword">print</span> <span class="string">"\ntime for 4th bogus: (squelched)\n"</span><span class="operator">;</span>
<span class="keyword">print</span> <span class="variable">BOGUS4</span> <span class="string">'nada'</span><span class="operator">;</span>
<span class="keyword">print</span> <span class="string">"done with 4th bogus\n"</span><span class="operator">;</span>
</pre>
<p>
</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>
<p>If an extant $SIG{__WARN__} handler is discovered, it will continue
to be honored, but only after the diagnostics::splainthis() function
(the module's $SIG{__WARN__} interceptor) has had its way with your
warnings.</p>
<p>There is a $diagnostics::DEBUG variable you may set if you're desperately
curious what sorts of things are being intercepted.</p>
<pre>
<span class="keyword">BEGIN</span> <span class="operator">{</span> <span class="variable">$diagnostics::DEBUG</span> <span class="operator">=</span> <span class="number">1</span> <span class="operator">}</span>
</pre>
<p>
</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>
<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>
<span class="keyword">BEGIN</span> <span class="operator">{</span> <span class="variable">$diagnostics::PRETTY</span> <span class="operator">=</span> <span class="number">1</span> <span class="operator">}</span>
</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>
<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>
<p>
</p>
<hr />
<h1><a name="author">AUTHOR</a></h1>
<p>Tom Christiansen <<em><a href="mailto:tchrist@mox.perl.com">tchrist@mox.perl.com</a></em>>, 25 June 1995.</p>
</body>
</html>
⌨️ 快捷键说明
复制代码Ctrl + C
搜索代码Ctrl + F
全屏模式F11
增大字号Ctrl + =
减小字号Ctrl + -
显示快捷键?