Penguin
Recent Changes
Annotated edit history of splain(1) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 SPLAIN
2 !!!SPLAIN
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 EXAMPLES
7 INTERNALS
8 BUGS
9 AUTHOR
10 ----
11 !!NAME
12
13
14 diagnostics - Perl compiler pragma to force verbose warning diagnostics
15
16
17 splain - standalone program to do the same
18 thing
19 !!SYNOPSIS
20
21
22 As a pragma:
23
24
25 use diagnostics;
26 use diagnostics -verbose;
27 enable diagnostics;
28 disable diagnostics;
29 Aa a program:
30
31
32 perl program 2
33 !!DESCRIPTION
34
35
36 __The__ diagnostics __Pragma__
37
38
39 This module extends the terse diagnostics normally emitted
40 by both the perl compiler and the perl interpreter,
41 augmenting them with the more explicative and endearing
42 descriptions found in perldiag. Like the other pragmata, it
43 affects the compilation phase of your program rather than
44 merely the execution phase.
45
46
47 To use in your program as a pragma, merely
48 invoke
49
50
51 use diagnostics;
52 at the start (or near the start) of your program. (Note that this ''does'' enable perl's __-w__ flag.) Your whole compilation will then be subject(ed :-) to the enhanced diagnostics. These still go out __STDERR__ .
53
54
55 Due to the interaction between runtime and compiletime
56 issues, and because it's probably not a very good idea
57 anyway, you may not use no diagnostics to turn them
58 off at compiletime. However, you may control their behaviour
59 at runtime using the ''disable()'' and ''enable()''
60 methods to turn them off and on respectively.
61
62
63 The __-verbose__ flag first prints out the perldiag
64 introduction before any other diagnostics. The
65 $diagnostics::PRETTY variable can generate nicer
66 escape sequences for pagers.
67
68
69 Warnings dispatched from perl itself (or more accurately,
70 those that match descriptions found in perldiag) are only
71 displayed once (no duplicate descriptions). User code
72 generated warnings ala ''warn()'' are unaffected,
73 allowing duplicate user messages to be
74 displayed.
75
76
77 __The__ ''splain'' __Program__
78
79
80 While apparently a whole nuther program, ''splain'' is
81 actually nothing more than a link to the (executable)
82 ''diagnostics.pm'' module, as well as a link to the
83 ''diagnostics.pod'' documentation. The __-v__ flag is
84 like the use diagnostics -verbose directive. The
85 __-p__ flag is like the $diagnostics::PRETTY
86 variable. Since you're post-processing with ''splain'',
87 there's no sense in being able to ''enable()'' or
88 ''disable()'' processing.
89
90
91 Output from ''splain'' is directed to
92 __STDOUT__ , unlike the
93 pragma.
94 !!EXAMPLES
95
96
97 The following file is certain to trigger a few errors at
98 both runtime and compiletime:
99
100
101 use diagnostics;
102 print NOWHERE
103 If you prefer to run your program first and look at its problem afterwards, do this:
104
105
106 perl -w test.pl 2
107 Note that this is not in general possible in shells of more dubious heritage, as the theoretical
108
109
110 (perl -w test.pl
111 Because you just moved the existing __stdout__ to somewhere else.
112
113
114 If you don't want to modify your source code, but still have
115 on-the-fly warnings, do this:
116
117
118 exec 3
119 Nifty, eh?
120
121
122 If you want to control warnings on the fly, do something
123 like this. Make sure you do the use first, or you
124 won't be able to get at the ''enable()'' or
125 ''disable()'' methods.
126
127
128 use diagnostics; # checks entire compilation phase
129 print
130 disable diagnostics; # only turns off runtime warnings
131 print
132 enable diagnostics; # turns back on runtime warnings
133 print
134 disable diagnostics;
135 print
136 !!INTERNALS
137
138
139 Diagnostic messages derive from the ''perldiag.pod'' file
140 when available at runtime. Otherwise, they may be embedded
141 in the file itself when the splain package is built. See the
142 ''Makefile'' for details.
143
144
145 If an extant $SIG{__WARN__} handler is discovered,
146 it will continue to be honored, but only after the
147 ''diagnostics::splainthis()'' function (the module's
148 $SIG{__WARN__} interceptor) has had its way with
149 your warnings.
150
151
152 There is a $diagnostics::DEBUG variable you may set
153 if you're desperately curious what sorts of things are being
154 intercepted.
155
156
157 BEGIN { $diagnostics::DEBUG = 1 }
158 !!BUGS
159
160
161 Not being able to say ``no diagnostics'' is annoying, but
162 may not be insurmountable.
163
164
165 The -pretty directive is called too late to affect
166 matters. You have to do this instead, and ''before'' you
167 load the module.
168
169
170 BEGIN { $diagnostics::PRETTY = 1 }
171 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.
172
173
174 While it's true that this documentation is somewhat
175 subserious, if you use a program named ''splain'', you
176 should expect a bit of whimsy.
177 !!AUTHOR
178
179
180 Tom Christiansen tchrist@mox.perl.com''
181 ''
182 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.