Debian Codegraph @

upstream/opensuse-tumbleweed/man1/splain.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "SPLAIN 1"
61 .TH SPLAIN 1 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 diagnostics, splain \- produce verbose warning diagnostics
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 Using the \f(CW\*(C`diagnostics\*(C'\fR pragma:
71 .PP
72 .Vb 2
73 \& use diagnostics;
74 \& use diagnostics \-verbose;
75 \&
76 \& diagnostics\->enable;
77 \& diagnostics\->disable;
78 .Ve
79 .PP
80 Using the \f(CW\*(C`splain\*(C'\fR standalone filter program:
81 .PP
82 .Vb 2
83 \& perl program 2>diag.out
84 \& splain [\-v] [\-p] diag.out
85 .Ve
86 .PP
87 Using diagnostics to get stack traces from a misbehaving script:
88 .PP
89 .Vb 1
90 \& perl \-Mdiagnostics=\-traceonly my_script.pl
91 .Ve
92 .SH DESCRIPTION
93 .IX Header "DESCRIPTION"
94 .ie n .SS "The ""diagnostics"" Pragma"
95 .el .SS "The \f(CWdiagnostics\fP Pragma"
96 .IX Subsection "The diagnostics Pragma"
97 This module extends the terse diagnostics normally emitted by both the
98 perl compiler and the perl interpreter (from running perl with a \-w
99 switch or \f(CW\*(C`use warnings\*(C'\fR), augmenting them with the more
100 explicative and endearing descriptions found in perldiag. Like the
101 other pragmata, it affects the compilation phase of your program rather
102 than merely the execution phase.
103 .PP
104 To use in your program as a pragma, merely invoke
105 .PP
106 .Vb 1
107 \& use diagnostics;
108 .Ve
109 .PP
110 at the start (or near the start) of your program. (Note
111 that this \fIdoes\fR enable perl\*(Aqs \fB\-w\fR flag.) Your whole
112 compilation will then be subject(ed :\-) to the enhanced diagnostics.
113 These still go out \fBSTDERR\fR.
114 .PP
115 Due to the interaction between runtime and compiletime issues,
116 and because it\*(Aqs probably not a very good idea anyway,
117 you may not use \f(CW\*(C`no diagnostics\*(C'\fR to turn them off at compiletime.
118 However, you may control their behaviour at runtime using the
119 \&\f(CWdisable()\fR and \f(CWenable()\fR methods to turn them off and on respectively.
120 .PP
121 The \fB\-verbose\fR flag first prints out the perldiag introduction before
122 any other diagnostics. The \f(CW$diagnostics::PRETTY\fR variable can generate nicer
123 escape sequences for pagers.
124 .PP
125 Warnings dispatched from perl itself (or more accurately, those that match
126 descriptions found in perldiag) are only displayed once (no duplicate
127 descriptions). User code generated warnings a la \fBwarn()\fR are unaffected,
128 allowing duplicate user messages to be displayed.
129 .PP
130 This module also adds a stack trace to the error message when perl dies.
131 This is useful for pinpointing what
132 caused the death. The \fB\-traceonly\fR (or
133 just \fB\-t\fR) flag turns off the explanations of warning messages leaving just
134 the stack traces. So if your script is dieing, run it again with
135 .PP
136 .Vb 1
137 \& perl \-Mdiagnostics=\-traceonly my_bad_script
138 .Ve
139 .PP
140 to see the call stack at the time of death. By supplying the \fB\-warntrace\fR
141 (or just \fB\-w\fR) flag, any warnings emitted will also come with a stack
142 trace.
143 .SS "The \fIsplain\fP Program"
144 .IX Subsection "The splain Program"
145 Another program, \fIsplain\fR is actually nothing
146 more than a link to the (executable) \fIdiagnostics.pm\fR module, as well as
147 a link to the \fIdiagnostics.pod\fR documentation. The \fB\-v\fR flag is like
148 the \f(CW\*(C`use diagnostics \-verbose\*(C'\fR directive.
149 The \fB\-p\fR flag is like the
150 \&\f(CW$diagnostics::PRETTY\fR variable. Since you\*(Aqre post\-processing with
151 \&\fIsplain\fR, there\*(Aqs no sense in being able to \fBenable()\fR or \fBdisable()\fR processing.
152 .PP
153 Output from \fIsplain\fR is directed to \fBSTDOUT\fR, unlike the pragma.
154 .SH EXAMPLES
155 .IX Header "EXAMPLES"
156 The following file is certain to trigger a few errors at both
157 runtime and compiletime:
158 .PP
159 .Vb 8
160 \& use diagnostics;
161 \& print NOWHERE "nothing\en";
162 \& print STDERR "\en\etThis message should be unadorned.\en";
163 \& warn "\etThis is a user warning";
164 \& print "\enDIAGNOSTIC TESTER: Please enter a <CR> here: ";
165 \& my $a, $b = scalar <STDIN>;
166 \& print "\en";
167 \& print $x/$y;
168 .Ve
169 .PP
170 If you prefer to run your program first and look at its problem
171 afterwards, do this:
172 .PP
173 .Vb 2
174 \& perl \-w test.pl 2>test.out
175 \& ./splain < test.out
176 .Ve
177 .PP
178 Note that this is not in general possible in shells of more dubious heritage,
179 as the theoretical
180 .PP
181 .Vb 2
182 \& (perl \-w test.pl >/dev/tty) >& test.out
183 \& ./splain < test.out
184 .Ve
185 .PP
186 Because you just moved the existing \fBstdout\fR to somewhere else.
187 .PP
188 If you don\*(Aqt want to modify your source code, but still have on\-the\-fly
189 warnings, do this:
190 .PP
191 .Vb 1
192 \& exec 3>&1; perl \-w test.pl 2>&1 1>&3 3>&\- | splain 1>&2 3>&\-
193 .Ve
194 .PP
195 Nifty, eh?
196 .PP
197 If you want to control warnings on the fly, do something like this.
198 Make sure you do the \f(CW\*(C`use\*(C'\fR first, or you won\*(Aqt be able to get
199 at the \fBenable()\fR or \fBdisable()\fR methods.
200 .PP
201 .Vb 4
202 \& use diagnostics; # checks entire compilation phase
203 \& print "\entime for 1st bogus diags: SQUAWKINGS\en";
204 \& print BOGUS1 \*(Aqnada\*(Aq;
205 \& print "done with 1st bogus\en";
206 \&
207 \& diagnostics\->disable; # only turns off runtime warnings
208 \& print "\entime for 2nd bogus: (squelched)\en";
209 \& print BOGUS2 \*(Aqnada\*(Aq;
210 \& print "done with 2nd bogus\en";
211 \&
212 \& diagnostics\->enable; # turns back on runtime warnings
213 \& print "\entime for 3rd bogus: SQUAWKINGS\en";
214 \& print BOGUS3 \*(Aqnada\*(Aq;
215 \& print "done with 3rd bogus\en";
216 \&
217 \& diagnostics\->disable;
218 \& print "\entime for 4th bogus: (squelched)\en";
219 \& print BOGUS4 \*(Aqnada\*(Aq;
220 \& print "done with 4th bogus\en";
221 .Ve
222 .SH INTERNALS
223 .IX Header "INTERNALS"
224 Diagnostic messages derive from the \fIperldiag.pod\fR file when available at
225 runtime. Otherwise, they may be embedded in the file itself when the
226 splain package is built. See the \fIMakefile\fR for details.
227 .PP
228 If an extant \f(CW$SIG\fR{_\|_WARN_\|_} handler is discovered, it will continue
229 to be honored, but only after the \fBdiagnostics::splainthis()\fR function
230 (the module\*(Aqs \f(CW$SIG\fR{_\|_WARN_\|_} interceptor) has had its way with your
231 warnings.
232 .PP
233 There is a \f(CW$diagnostics::DEBUG\fR variable you may set if you\*(Aqre desperately
234 curious what sorts of things are being intercepted.
235 .PP
236 .Vb 1
237 \& BEGIN { $diagnostics::DEBUG = 1 }
238 .Ve
239 .SH BUGS
240 .IX Header "BUGS"
241 Not being able to say "no diagnostics" is annoying, but may not be
242 insurmountable.
243 .PP
244 The \f(CW\*(C`\-pretty\*(C'\fR directive is called too late to affect matters.
245 You have to do this instead, and \fIbefore\fR you load the module.
246 .PP
247 .Vb 1
248 \& BEGIN { $diagnostics::PRETTY = 1 }
249 .Ve
250 .PP
251 I could start up faster by delaying compilation until it should be
252 needed, but this gets a "panic: top_level" when using the pragma form
253 in Perl 5.001e.
254 .PP
255 While it\*(Aqs true that this documentation is somewhat subserious, if you use
256 a program named \fIsplain\fR, you should expect a bit of whimsy.
257 .SH AUTHOR
258 .IX Header "AUTHOR"
259 Tom Christiansen <\[email protected]\fR>, 25 June 1995.