1diagnostics(3pm) Perl Programmers Reference Guide diagnostics(3pm)
2
6 diagnostics, splain - produce verbose warning diagnostics
7
9 Using the "diagnostics" pragma:
10 use diagnostics;
12 use diagnostics -verbose;
13 enable diagnostics;
15 disable diagnostics;
16 Using the "splain" standalone filter program:
18 perl program 2>diag.out
20 splain [-v] [-p] diag.out
21 Using diagnostics to get stack traces from a misbehaving script:
23 perl -Mdiagnostics=-traceonly my_script.pl
25
27 The "diagnostics" Pragma
28 This module extends the terse diagnostics normally emitted by both the
30 perl compiler and the perl interpreter (from running perl with a -w
31 switch or "use warnings"), augmenting them with the more explicative
32 and endearing descriptions found in perldiag. Like the other pragmata,
33 it affects the compilation phase of your program rather than merely the
34 execution phase.
35 To use in your program as a pragma, merely invoke
37 use diagnostics;
39 at the start (or near the start) of your program. (Note that this does
41 enable perl's -w flag.) Your whole compilation will then be subject(ed
42 :-) to the enhanced diagnostics. These still go out STDERR.
43 Due to the interaction between runtime and compiletime issues, and
45 because it's probably not a very good idea anyway, you may not use "no
46 diagnostics" to turn them off at compiletime. However, you may control
47 their behaviour at runtime using the disable() and enable() methods to
48 turn them off and on respectively.
49 The -verbose flag first prints out the perldiag introduction before any
51 other diagnostics. The $diagnostics::PRETTY variable can generate
52 nicer escape sequences for pagers.
53 Warnings dispatched from perl itself (or more accurately, those that
55 match descriptions found in perldiag) are only displayed once (no
56 duplicate descriptions). User code generated warnings a la warn() are
57 unaffected, allowing duplicate user messages to be displayed.
58 This module also adds a stack trace to the error message when perl
60 dies. This is useful for pinpointing what caused the death. The
61 -traceonly (or just -t) flag turns off the explanations of warning mes‐
62 sages leaving just the stack traces. So if your script is dieing, run
63 it again with
64 perl -Mdiagnostics=-traceonly my_bad_script
66 to see the call stack at the time of death. By supplying the -warntrace
68 (or just -w) flag, any warnings emitted will also come with a stack
69 trace.
70 The splain Program
72 While apparently a whole nuther program, splain is actually nothing
74 more than a link to the (executable) diagnostics.pm module, as well as
75 a link to the diagnostics.pod documentation. The -v flag is like the
76 "use diagnostics -verbose" directive. The -p flag is like the $diag‐
77 nostics::PRETTY variable. Since you're post-processing with splain,
78 there's no sense in being able to enable() or disable() processing.
79 Output from splain is directed to STDOUT, unlike the pragma.
81
83 The following file is certain to trigger a few errors at both runtime
84 and compiletime:
85 use diagnostics;
87 print NOWHERE "nothing\n";
88 print STDERR "\n\tThis message should be unadorned.\n";
89 warn "\tThis is a user warning";
90 print "\nDIAGNOSTIC TESTER: Please enter a <CR> here: ";
91 my $a, $b = scalar <STDIN>;
92 print "\n";
93 print $x/$y;
94 If you prefer to run your program first and look at its problem after‐
96 wards, do this:
97 perl -w test.pl 2>test.out
99 ./splain < test.out
100 Note that this is not in general possible in shells of more dubious
102 heritage, as the theoretical
103 (perl -w test.pl >/dev/tty) >& test.out
105 ./splain < test.out
106 Because you just moved the existing stdout to somewhere else.
108 If you don't want to modify your source code, but still have on-the-fly
110 warnings, do this:
111 exec 3>&1; perl -w test.pl 2>&1 1>&3 3>&- ⎪ splain 1>&2 3>&-
113 Nifty, eh?
115 If you want to control warnings on the fly, do something like this.
117 Make sure you do the "use" first, or you won't be able to get at the
118 enable() or disable() methods.
119 use diagnostics; # checks entire compilation phase
121 print "\ntime for 1st bogus diags: SQUAWKINGS\n";
122 print BOGUS1 'nada';
123 print "done with 1st bogus\n";
124 disable diagnostics; # only turns off runtime warnings
126 print "\ntime for 2nd bogus: (squelched)\n";
127 print BOGUS2 'nada';
128 print "done with 2nd bogus\n";
129 enable diagnostics; # turns back on runtime warnings
131 print "\ntime for 3rd bogus: SQUAWKINGS\n";
132 print BOGUS3 'nada';
133 print "done with 3rd bogus\n";
134 disable diagnostics;
136 print "\ntime for 4th bogus: (squelched)\n";
137 print BOGUS4 'nada';
138 print "done with 4th bogus\n";
139
141 Diagnostic messages derive from the perldiag.pod file when available at
142 runtime. Otherwise, they may be embedded in the file itself when the
143 splain package is built. See the Makefile for details.
144 If an extant $SIG{__WARN__} handler is discovered, it will continue to
146 be honored, but only after the diagnostics::splainthis() function (the
147 module's $SIG{__WARN__} interceptor) has had its way with your warn‐
148 ings.
149 There is a $diagnostics::DEBUG variable you may set if you're desper‐
151 ately curious what sorts of things are being intercepted.
152 BEGIN { $diagnostics::DEBUG = 1 }
154
156 Not being able to say "no diagnostics" is annoying, but may not be
157 insurmountable.
158 The "-pretty" directive is called too late to affect matters. You have
160 to do this instead, and before you load the module.
161 BEGIN { $diagnostics::PRETTY = 1 }
163 I could start up faster by delaying compilation until it should be
165 needed, but this gets a "panic: top_level" when using the pragma form
166 in Perl 5.001e.
167 While it's true that this documentation is somewhat subserious, if you
169 use a program named splain, you should expect a bit of whimsy.
170
172 Tom Christiansen <tchrist@mox.perl.com>, 25 June 1995.
173perl v5.8.8 2001-09-21 diagnostics(3pm)