home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _46d2a4c52772f0272d1e88a4bbd3c6e3 < prev    next >
Text File  |  2000-03-23  |  8KB  |  197 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>diagnostics - Perl compiler pragma to force verbose warning diagnostics</TITLE>
  5. <LINK REL="stylesheet" HREF="../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> diagnostics - Perl compiler pragma to force verbose warning diagnostics</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  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. <H1><A NAME="name">NAME</A></H1>
  41. <P>diagnostics - Perl compiler pragma to force verbose warning diagnostics</P>
  42. <P>splain - standalone program to do the same thing</P>
  43. <P>
  44. <HR>
  45. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  46. <UL>
  47. <LI>Linux</LI>
  48. <LI>Solaris</LI>
  49. <LI>Windows</LI>
  50. </UL>
  51. <HR>
  52. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  53. <P>As a pragma:</P>
  54. <PRE>
  55.     use diagnostics;
  56.     use diagnostics -verbose;</PRE>
  57. <PRE>
  58.     enable  diagnostics;
  59.     disable diagnostics;</PRE>
  60. <P>Aa a program:</P>
  61. <PRE>
  62.     perl program 2>diag.out
  63.     splain [-v] [-p] diag.out</PRE>
  64. <P>
  65. <HR>
  66. <H1><A NAME="description">DESCRIPTION</A></H1>
  67. <P>
  68. <H2><A NAME="the diagnostics pragma">The <CODE>diagnostics</CODE> Pragma</A></H2>
  69. <P>This module extends the terse diagnostics normally emitted by both the
  70. perl compiler and the perl interpreter, augmenting them with the more
  71. explicative and endearing descriptions found in <A HREF="../lib/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 there 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="../lib/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="../lib/Pod/perldiag.html">the perldiag manpage</A>) are only displayed once (no duplicate
  91. descriptions).  User code generated warnings ala <A HREF="../lib/Pod/perlfunc.html#item_warn"><CODE>warn()</CODE></A> are unaffected,
  92. allowing duplicate user messages to be displayed.</P>
  93. <P>
  94. <H2><A NAME="the splain program">The <EM>splain</EM> Program</A></H2>
  95. <P>While apparently a whole nuther program, <EM>splain</EM> is actually nothing
  96. more than a link to the (executable) <EM>diagnostics.pm</EM> module, as well as
  97. a link to the <EM>diagnostics.pod</EM> documentation.  The <STRONG>-v</STRONG> flag is like
  98. the <CODE>use diagnostics -verbose</CODE> directive.
  99. The <STRONG>-p</STRONG> flag is like the
  100. $diagnostics::PRETTY variable.  Since you're post-processing with 
  101. <EM>splain</EM>, there's no sense in being able to <CODE>enable()</CODE> or <CODE>disable()</CODE> processing.</P>
  102. <P>Output from <EM>splain</EM> is directed to <STRONG>STDOUT</STRONG>, unlike the pragma.</P>
  103. <P>
  104. <HR>
  105. <H1><A NAME="examples">EXAMPLES</A></H1>
  106. <P>The following file is certain to trigger a few errors at both
  107. runtime and compiletime:</P>
  108. <PRE>
  109.     use diagnostics;
  110.     print NOWHERE "nothing\n";
  111.     print STDERR "\n\tThis message should be unadorned.\n";
  112.     warn "\tThis is a user warning";
  113.     print "\nDIAGNOSTIC TESTER: Please enter a <CR> here: ";
  114.     my $a, $b = scalar <STDIN>;
  115.     print "\n";
  116.     print $x/$y;</PRE>
  117. <P>If you prefer to run your program first and look at its problem
  118. afterwards, do this:</P>
  119. <PRE>
  120.     perl -w test.pl 2>test.out
  121.     ./splain < test.out</PRE>
  122. <P>Note that this is not in general possible in shells of more dubious heritage, 
  123. as the theoretical</P>
  124. <PRE>
  125.     (perl -w test.pl >/dev/tty) >& test.out
  126.     ./splain < test.out</PRE>
  127. <P>Because you just moved the existing <STRONG>stdout</STRONG> to somewhere else.</P>
  128. <P>If you don't want to modify your source code, but still have on-the-fly
  129. warnings, do this:</P>
  130. <PRE>
  131.     exec 3>&1; perl -w test.pl 2>&1 1>&3 3>&- | splain 1>&2 3>&-</PRE>
  132. <P>Nifty, eh?</P>
  133. <P>If you want to control warnings on the fly, do something like this.
  134. 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
  135. at the <CODE>enable()</CODE> or <CODE>disable()</CODE> methods.</P>
  136. <PRE>
  137.     use diagnostics; # checks entire compilation phase 
  138.         print "\ntime for 1st bogus diags: SQUAWKINGS\n";
  139.         print BOGUS1 'nada';
  140.         print "done with 1st bogus\n";</PRE>
  141. <PRE>
  142.     disable diagnostics; # only turns off runtime warnings
  143.         print "\ntime for 2nd bogus: (squelched)\n";
  144.         print BOGUS2 'nada';
  145.         print "done with 2nd bogus\n";</PRE>
  146. <PRE>
  147.     enable diagnostics; # turns back on runtime warnings
  148.         print "\ntime for 3rd bogus: SQUAWKINGS\n";
  149.         print BOGUS3 'nada';
  150.         print "done with 3rd bogus\n";</PRE>
  151. <PRE>
  152.     disable diagnostics;
  153.         print "\ntime for 4th bogus: (squelched)\n";
  154.         print BOGUS4 'nada';
  155.         print "done with 4th bogus\n";</PRE>
  156. <P>
  157. <HR>
  158. <H1><A NAME="internals">INTERNALS</A></H1>
  159. <P>Diagnostic messages derive from the <EM>perldiag.pod</EM> file when available at
  160. runtime.  Otherwise, they may be embedded in the file itself when the
  161. splain package is built.   See the <EM>Makefile</EM> for details.</P>
  162. <P>If an extant $SIG{__WARN__} handler is discovered, it will continue
  163. to be honored, but only after the diagnostics::splainthis() function 
  164. (the module's $SIG{__WARN__} interceptor) has had its way with your
  165. warnings.</P>
  166. <P>There is a $diagnostics::DEBUG variable you may set if you're desperately
  167. curious what sorts of things are being intercepted.</P>
  168. <PRE>
  169.     BEGIN { $diagnostics::DEBUG = 1 }</PRE>
  170. <P>
  171. <HR>
  172. <H1><A NAME="bugs">BUGS</A></H1>
  173. <P>Not being able to say ``no diagnostics'' is annoying, but may not be
  174. insurmountable.</P>
  175. <P>The <CODE>-pretty</CODE> directive is called too late to affect matters.
  176. You have to do this instead, and <EM>before</EM> you load the module.</P>
  177. <PRE>
  178.     BEGIN { $diagnostics::PRETTY = 1 }</PRE>
  179. <P>I could start up faster by delaying compilation until it should be
  180. needed, but this gets a ``panic: top_level'' when using the pragma form
  181. in Perl 5.001e.</P>
  182. <P>While it's true that this documentation is somewhat subserious, if you use
  183. a program named <EM>splain</EM>, you should expect a bit of whimsy.</P>
  184. <P>
  185. <HR>
  186. <H1><A NAME="author">AUTHOR</A></H1>
  187. <P>Tom Christiansen <<EM><A HREF="mailto:tchrist@mox.perl.com">tchrist@mox.perl.com</A></EM>>, 25 June 1995.</P>
  188. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  189. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  190. <STRONG><P CLASS=block> diagnostics - Perl compiler pragma to force verbose warning diagnostics</P></STRONG>
  191. </TD></TR>
  192. </TABLE>
  193.  
  194. </BODY>
  195.  
  196. </HTML>
  197.