mingw/html/lib/diagnostics.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>splain - produce verbose warning diagnostics</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:" />
   8 </head>
   9
  10 <body style="background-color: white">
  11 <table border="0" width="100%" cellspacing="0" cellpadding="3">
  12 <tr><td class="block" style="background-color: #cccccc" valign="middle">
  13 <big><strong><span class="block">&nbsp;splain - produce verbose warning diagnostics</span></strong></big>
  14 </td></tr>
  15 </table>
  16
  17 <p><a name="__index__"></a></p>
  18 <!-- INDEX BEGIN -->
  19
  20 <ul>
  21
  22         <li><a href="#name">NAME</a></li>
  23         <li><a href="#synopsis">SYNOPSIS</a></li>
  24         <li><a href="#description">DESCRIPTION</a></li>
  25         <ul>
  26
  27                 <li><a href="#the_diagnostics_pragma">The <code>diagnostics</code> Pragma</a></li>
  28                 <li><a href="#the_splain_program">The <em>splain</em> Program</a></li>
  29         </ul>
  30
  31         <li><a href="#examples">EXAMPLES</a></li>
  32         <li><a href="#internals">INTERNALS</a></li>
  33         <li><a href="#bugs">BUGS</a></li>
  34         <li><a href="#author">AUTHOR</a></li>
  35 </ul>
  36 <!-- INDEX END -->
  37
  38 <hr />
  39 <p>
  40 </p>
  41 <h1><a name="name">NAME</a></h1>
  42 <p>diagnostics, splain - produce verbose warning diagnostics</p>
  43 <p>
  44 </p>
  45 <hr />
  46 <h1><a name="synopsis">SYNOPSIS</a></h1>
  47 <p>Using the <code>diagnostics</code> pragma:</p>
  48 <pre>
  49     use diagnostics;
  50     use diagnostics -verbose;</pre>
  51 <pre>
  52     enable  diagnostics;
  53     disable diagnostics;</pre>
  54 <p>Using the <code>splain</code> standalone filter program:</p>
  55 <pre>
  56     perl program 2&gt;diag.out
  57     splain [-v] [-p] diag.out</pre>
  58 <p>Using diagnostics to get stack traces from a misbehaving script:</p>
  59 <pre>
  60     perl -Mdiagnostics=-traceonly my_script.pl</pre>
  61 <p>
  62 </p>
  63 <hr />
  64 <h1><a name="description">DESCRIPTION</a></h1>
  65 <p>
  66 </p>
  67 <h2><a name="the_diagnostics_pragma">The <code>diagnostics</code> Pragma</a></h2>
  68 <p>This module extends the terse diagnostics normally emitted by both the
  69 perl compiler and the perl interpreter (from running perl with a -w
  70 switch or <code>use warnings</code>), augmenting them with the more
  71 explicative and endearing descriptions found in <a href="file://C|\msysgit\mingw\html/pod/perldiag.html">the perldiag manpage</a>.  Like the
  72 other pragmata, it affects the compilation phase of your program rather
  73 than merely the execution phase.</p>
  74 <p>To use in your program as a pragma, merely invoke</p>
  75 <pre>
  76     use diagnostics;</pre>
  77 <p>at the start (or near the start) of your program.  (Note
  78 that this <em>does</em> enable perl's <strong>-w</strong> flag.)  Your whole
  79 compilation will then be subject(ed :-) to the enhanced diagnostics.
  80 These still go out <strong>STDERR</strong>.</p>
  81 <p>Due to the interaction between runtime and compiletime issues,
  82 and because it's probably not a very good idea anyway,
  83 you may not use <code>no diagnostics</code> to turn them off at compiletime.
  84 However, you may control their behaviour at runtime using the
  85 <code>disable()</code> and <code>enable()</code> methods to turn them off and on respectively.</p>
  86 <p>The <strong>-verbose</strong> flag first prints out the <a href="file://C|\msysgit\mingw\html/pod/perldiag.html">the perldiag manpage</a> introduction before
  87 any other diagnostics.  The $diagnostics::PRETTY variable can generate nicer
  88 escape sequences for pagers.</p>
  89 <p>Warnings dispatched from perl itself (or more accurately, those that match
  90 descriptions found in <a href="file://C|\msysgit\mingw\html/pod/perldiag.html">the perldiag manpage</a>) are only displayed once (no duplicate
  91 descriptions).  User code generated warnings a la <code>warn()</code> are unaffected,
  92 allowing duplicate user messages to be displayed.</p>
  93 <p>This module also adds a stack trace to the error message when perl dies.
  94 This is useful for pinpointing what caused the death. The <strong>-traceonly</strong> (or
  95 just <strong>-t</strong>) flag turns off the explanations of warning messages leaving just
  96 the stack traces. So if your script is dieing, run it again with</p>
  97 <pre>
  98   perl -Mdiagnostics=-traceonly my_bad_script</pre>
  99 <p>to see the call stack at the time of death. By supplying the <strong>-warntrace</strong>
 100 (or just <strong>-w</strong>) flag, any warnings emitted will also come with a stack
 101 trace.</p>
 102 <p>
 103 </p>
 104 <h2><a name="the_splain_program">The <em>splain</em> Program</a></h2>
 105 <p>While apparently a whole nuther program, <em>splain</em> is actually nothing
 106 more than a link to the (executable) <em>diagnostics.pm</em> module, as well as
 107 a link to the <em>diagnostics.pod</em> documentation.  The <strong>-v</strong> flag is like
 108 the <code>use diagnostics -verbose</code> directive.
 109 The <strong>-p</strong> flag is like the
 110 $diagnostics::PRETTY variable.  Since you're post-processing with
 111 <em>splain</em>, there's no sense in being able to <code>enable()</code> or <code>disable()</code> processing.</p>
 112 <p>Output from <em>splain</em> is directed to <strong>STDOUT</strong>, unlike the pragma.</p>
 113 <p>
 114 </p>
 115 <hr />
 116 <h1><a name="examples">EXAMPLES</a></h1>
 117 <p>The following file is certain to trigger a few errors at both
 118 runtime and compiletime:</p>
 119 <pre>
 120     use diagnostics;
 121     print NOWHERE &quot;nothing\n&quot;;
 122     print STDERR &quot;\n\tThis message should be unadorned.\n&quot;;
 123     warn &quot;\tThis is a user warning&quot;;
 124     print &quot;\nDIAGNOSTIC TESTER: Please enter a &lt;CR&gt; here: &quot;;
 125     my $a, $b = scalar &lt;STDIN&gt;;
 126     print &quot;\n&quot;;
 127     print $x/$y;</pre>
 128 <p>If you prefer to run your program first and look at its problem
 129 afterwards, do this:</p>
 130 <pre>
 131     perl -w test.pl 2&gt;test.out
 132     ./splain &lt; test.out</pre>
 133 <p>Note that this is not in general possible in shells of more dubious heritage,
 134 as the theoretical</p>
 135 <pre>
 136     (perl -w test.pl &gt;/dev/tty) &gt;&amp; test.out
 137     ./splain &lt; test.out</pre>
 138 <p>Because you just moved the existing <strong>stdout</strong> to somewhere else.</p>
 139 <p>If you don't want to modify your source code, but still have on-the-fly
 140 warnings, do this:</p>
 141 <pre>
 142     exec 3&gt;&amp;1; perl -w test.pl 2&gt;&amp;1 1&gt;&amp;3 3&gt;&amp;- | splain 1&gt;&amp;2 3&gt;&amp;-</pre>
 143 <p>Nifty, eh?</p>
 144 <p>If you want to control warnings on the fly, do something like this.
 145 Make sure you do the <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_use"><code>use</code></a> first, or you won't be able to get
 146 at the <code>enable()</code> or <code>disable()</code> methods.</p>
 147 <pre>
 148     use diagnostics; # checks entire compilation phase
 149         print &quot;\ntime for 1st bogus diags: SQUAWKINGS\n&quot;;
 150         print BOGUS1 'nada';
 151         print &quot;done with 1st bogus\n&quot;;</pre>
 152 <pre>
 153     disable diagnostics; # only turns off runtime warnings
 154         print &quot;\ntime for 2nd bogus: (squelched)\n&quot;;
 155         print BOGUS2 'nada';
 156         print &quot;done with 2nd bogus\n&quot;;</pre>
 157 <pre>
 158     enable diagnostics; # turns back on runtime warnings
 159         print &quot;\ntime for 3rd bogus: SQUAWKINGS\n&quot;;
 160         print BOGUS3 'nada';
 161         print &quot;done with 3rd bogus\n&quot;;</pre>
 162 <pre>
 163     disable diagnostics;
 164         print &quot;\ntime for 4th bogus: (squelched)\n&quot;;
 165         print BOGUS4 'nada';
 166         print &quot;done with 4th bogus\n&quot;;</pre>
 167 <p>
 168 </p>
 169 <hr />
 170 <h1><a name="internals">INTERNALS</a></h1>
 171 <p>Diagnostic messages derive from the <em>perldiag.pod</em> file when available at
 172 runtime.  Otherwise, they may be embedded in the file itself when the
 173 splain package is built.   See the <em>Makefile</em> for details.</p>
 174 <p>If an extant $SIG{__WARN__} handler is discovered, it will continue
 175 to be honored, but only after the diagnostics::splainthis() function
 176 (the module's $SIG{__WARN__} interceptor) has had its way with your
 177 warnings.</p>
 178 <p>There is a $diagnostics::DEBUG variable you may set if you're desperately
 179 curious what sorts of things are being intercepted.</p>
 180 <pre>
 181     BEGIN { $diagnostics::DEBUG = 1 }</pre>
 182 <p>
 183 </p>
 184 <hr />
 185 <h1><a name="bugs">BUGS</a></h1>
 186 <p>Not being able to say ``no diagnostics'' is annoying, but may not be
 187 insurmountable.</p>
 188 <p>The <code>-pretty</code> directive is called too late to affect matters.
 189 You have to do this instead, and <em>before</em> you load the module.</p>
 190 <pre>
 191     BEGIN { $diagnostics::PRETTY = 1 }</pre>
 192 <p>I could start up faster by delaying compilation until it should be
 193 needed, but this gets a ``panic: top_level'' when using the pragma form
 194 in Perl 5.001e.</p>
 195 <p>While it's true that this documentation is somewhat subserious, if you use
 196 a program named <em>splain</em>, you should expect a bit of whimsy.</p>
 197 <p>
 198 </p>
 199 <hr />
 200 <h1><a name="author">AUTHOR</a></h1>
 201 <p>Tom Christiansen &lt;<em><a href="mailto:tchrist@mox.perl.com">tchrist@mox.perl.com</a></em>&gt;, 25 June 1995.</p>
 202 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 203 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 204 <big><strong><span class="block">&nbsp;splain - produce verbose warning diagnostics</span></strong></big>
 205 </td></tr>
 206 </table>
 207
 208 </body>
 209
 210 </html>