Commit | Line | Data |
---|---|---|
0453d815 PM |
1 | =head1 NAME |
2 | ||
3 | perllexwarn - Perl Lexical Warnings | |
4 | ||
5 | =head1 DESCRIPTION | |
6 | ||
7 | The C<use warning> pragma is a replacement for both the command line | |
8 | flag B<-w> and the equivalent Perl variable, C<$^W>. | |
9 | ||
10 | The pragma works just like the existing "strict" pragma. | |
11 | This means that the scope of the warning pragma is limited to the | |
12 | enclosing block. It also means that that the pragma setting will not | |
13 | leak across files (via C<use>, C<require> or C<do>). This allows | |
14 | authors to independently define the degree of warning checks that will | |
15 | be applied to their module. | |
16 | ||
17 | By default, optional warnings are disabled, so any legacy code that | |
18 | doesn't attempt to control the warnings will work unchanged. | |
19 | ||
20 | All warnings are enabled in a block by either of these: | |
21 | ||
22 | use warning ; | |
23 | use warning 'all' ; | |
24 | ||
25 | Similarly all warnings are disabled in a block by either of these: | |
26 | ||
27 | no warning ; | |
28 | no warning 'all' ; | |
29 | ||
30 | For example, consider the code below: | |
31 | ||
32 | use warning ; | |
33 | my $a ; | |
34 | my $b ; | |
35 | { | |
36 | no warning ; | |
37 | $b = 2 if $a EQ 3 ; | |
38 | } | |
39 | $b = 1 if $a NE 3 ; | |
40 | ||
41 | The code in the enclosing block has warnings enabled, but the inner | |
42 | block has them disabled. In this case that means that the use of the C<EQ> | |
43 | operator won't trip a C<"Use of EQ is deprecated"> warning, but the use of | |
44 | C<NE> will produce a C<"Use of NE is deprecated"> warning. | |
45 | ||
46 | =head2 Default Warnings and Optional Warnings | |
47 | ||
48 | Before the introduction of lexical warnings, Perl had two classes of | |
49 | warnings: mandatory and optional. | |
50 | ||
51 | As its name suggests, if your code tripped a mandatory warning, you | |
52 | would get a warning whether you wanted it or not. | |
252aa082 JH |
53 | For example, the code below would always produce an C<"isn't numeric"> |
54 | warning about the "2:". | |
0453d815 | 55 | |
252aa082 | 56 | my $a = "2:" + 3; |
0453d815 | 57 | |
252aa082 | 58 | though the result will be 5. |
0453d815 PM |
59 | |
60 | With the introduction of lexical warnings, mandatory warnings now become | |
61 | I<default> warnings. The difference is that although the previously | |
62 | mandatory warnings are still enabled by default, they can then be | |
63 | subsequently enabled or disabled with the lexical warning pragma. For | |
64 | example, in the code below, an C<"integer overflow"> warning will only | |
65 | be reported for the C<$a> variable. | |
66 | ||
252aa082 | 67 | my $a = "2:" + 3; |
0453d815 | 68 | no warning ; |
252aa082 | 69 | my $b = "2:" + 3; |
0453d815 PM |
70 | |
71 | Note that neither the B<-w> flag or the C<$^W> can be used to | |
72 | disable/enable default warnings. They are still mandatory in this case. | |
73 | ||
74 | =head2 What's wrong with B<-w> and C<$^W> | |
75 | ||
76 | Although very useful, the big problem with using B<-w> on the command | |
77 | line to enable warnings is that it is all or nothing. Take the typical | |
78 | scenario when you are writing a Perl program. Parts of the code you | |
79 | will write yourself, but it's very likely that you will make use of | |
80 | pre-written Perl modules. If you use the B<-w> flag in this case, you | |
81 | end up enabling warnings in pieces of code that you haven't written. | |
82 | ||
83 | Similarly, using C<$^W> to either disable or enable blocks of code is | |
84 | fundamentally flawed. For a start, say you want to disable warnings in | |
85 | a block of code. You might expect this to be enough to do the trick: | |
86 | ||
87 | { | |
88 | local ($^W) = 0 ; | |
89 | my $a =+ 2 ; | |
90 | my $b ; chop $b ; | |
91 | } | |
92 | ||
93 | When this code is run with the B<-w> flag, a warning will be produced | |
94 | for the C<$a> line -- C<"Reversed += operator">. | |
95 | ||
96 | The problem is that Perl has both compile-time and run-time warnings. To | |
97 | disable compile-time warnings you need to rewrite the code like this: | |
98 | ||
99 | { | |
100 | BEGIN { $^W = 0 } | |
101 | my $a =+ 2 ; | |
102 | my $b ; chop $b ; | |
103 | } | |
104 | ||
105 | The other big problem with C<$^W> is that way you can inadvertently | |
106 | change the warning setting in unexpected places in your code. For example, | |
107 | when the code below is run (without the B<-w> flag), the second call | |
108 | to C<doit> will trip a C<"Use of uninitialized value"> warning, whereas | |
109 | the first will not. | |
110 | ||
111 | sub doit | |
112 | { | |
113 | my $b ; chop $b ; | |
114 | } | |
115 | ||
116 | doit() ; | |
117 | ||
118 | { | |
119 | local ($^W) = 1 ; | |
120 | doit() | |
121 | } | |
122 | ||
123 | This is a side-effect of C<$^W> being dynamically scoped. | |
124 | ||
125 | Lexical warnings get around these limitations by allowing finer control | |
126 | over where warnings can or can't be tripped. | |
127 | ||
128 | =head2 Controlling Warnings from the Command Line | |
129 | ||
130 | There are three Command Line flags that can be used to control when | |
131 | warnings are (or aren't) produced: | |
132 | ||
133 | =over 5 | |
134 | ||
135 | =item B<-w> | |
136 | ||
137 | This is the existing flag. If the lexical warnings pragma is B<not> | |
138 | used in any of you code, or any of the modules that you use, this flag | |
139 | will enable warnings everywhere. See L<Backward Compatibility> for | |
140 | details of how this flag interacts with lexical warnings. | |
141 | ||
142 | =item B<-W> | |
143 | ||
144 | If the B<-W> flag is used on the command line, it will enable all warnings | |
145 | throughout the program regardless of whether warnings were disabled | |
146 | locally using C<no warning> or C<$^W =0>. This includes all files that get | |
147 | included via C<use>, C<require> or C<do>. | |
148 | Think of it as the Perl equivalent of the "lint" command. | |
149 | ||
150 | =item B<-X> | |
151 | ||
152 | Does the exact opposite to the B<-W> flag, i.e. it disables all warnings. | |
153 | ||
154 | =back | |
155 | ||
156 | =head2 Backward Compatibility | |
157 | ||
158 | If you are used with working with a version of Perl prior to the | |
159 | introduction of lexically scoped warnings, or have code that uses both | |
160 | lexical warnings and C<$^W>, this section will describe how they interact. | |
161 | ||
162 | How Lexical Warnings interact with B<-w>/C<$^W>: | |
163 | ||
164 | =over 5 | |
165 | ||
166 | =item 1. | |
167 | ||
168 | If none of the three command line flags (B<-w>, B<-W> or B<-X>) that | |
169 | control warnings is used and neither C<$^W> or lexical warnings are used, | |
170 | then default warnings will be enabled and optional warnings disabled. | |
171 | This means that legacy code that doesn't attempt to control the warnings | |
172 | will work unchanged. | |
173 | ||
174 | =item 2. | |
175 | ||
176 | The B<-w> flag just sets the global C<$^W> variable as in 5.005 -- this | |
177 | means that any legacy code that currently relies on manipulating C<$^W> | |
178 | to control warning behavior will still work as is. | |
179 | ||
180 | =item 3. | |
181 | ||
182 | Apart from now being a boolean, the C<$^W> variable operates in exactly | |
183 | the same horrible uncontrolled global way, except that it cannot | |
184 | disable/enable default warnings. | |
185 | ||
186 | =item 4. | |
187 | ||
188 | If a piece of code is under the control of the lexical warning pragma, | |
189 | both the C<$^W> variable and the B<-w> flag will be ignored for the | |
190 | scope of the lexical warning. | |
191 | ||
192 | =item 5. | |
193 | ||
194 | The only way to override a lexical warnings setting is with the B<-W> | |
195 | or B<-X> command line flags. | |
196 | ||
197 | =back | |
198 | ||
199 | The combined effect of 3 & 4 is that it will will allow code which uses | |
200 | the lexical warning pragma to control the warning behavior of $^W-type | |
201 | code (using a C<local $^W=0>) if it really wants to, but not vice-versa. | |
202 | ||
203 | =head1 EXPERIMENTAL FEATURES | |
204 | ||
205 | The features described in this section are experimental, and so subject | |
206 | to change. | |
207 | ||
208 | =head2 Category Hierarchy | |
209 | ||
252aa082 | 210 | A B<tentative> hierarchy of "categories" have been defined to allow groups |
0453d815 PM |
211 | of warnings to be enabled/disabled in isolation. The current |
212 | hierarchy is: | |
213 | ||
214 | all - +--- unsafe -------+--- taint | |
215 | | | | |
216 | | +--- substr | |
217 | | | | |
218 | | +--- signal | |
219 | | | | |
220 | | +--- closure | |
221 | | | | |
627300f0 JH |
222 | | +--- overflow |
223 | | | | |
224 | | +--- portable | |
225 | | | | |
0453d815 PM |
226 | | +--- untie |
227 | | | | |
228 | | +--- utf8 | |
229 | | | |
230 | +--- io ---------+--- pipe | |
231 | | | | |
232 | | +--- unopened | |
233 | | | | |
234 | | +--- closed | |
235 | | | | |
236 | | +--- newline | |
237 | | | | |
238 | | +--- exec | |
239 | | | |
240 | +--- syntax ----+--- ambiguous | |
241 | | | | |
242 | | +--- semicolon | |
243 | | | | |
244 | | +--- precedence | |
245 | | | | |
246 | | +--- reserved | |
247 | | | | |
627300f0 | 248 | | +--- digit |
0453d815 PM |
249 | | | |
250 | | +--- parenthesis | |
251 | | | | |
252 | | +--- deprecated | |
253 | | | | |
254 | | +--- printf | |
255 | | | |
256 | +--- severe ----+--- inplace | |
257 | | | | |
258 | | +--- internal | |
259 | | | | |
260 | | +--- debugging | |
261 | | | |
262 | |--- uninitialized | |
263 | | | |
264 | +--- void | |
265 | | | |
266 | +--- recursion | |
267 | | | |
268 | +--- redefine | |
269 | | | |
270 | +--- numeric | |
271 | | | |
272 | +--- once | |
273 | | | |
274 | +--- misc | |
275 | ||
276 | ||
277 | Just like the "strict" pragma any of these categories can be | |
278 | combined | |
279 | ||
280 | use warning qw(void redefine) ; | |
281 | no warning qw(io syntax untie) ; | |
282 | ||
283 | =head2 Fatal Warnings | |
284 | ||
285 | This feature is B<very> experimental. | |
286 | ||
287 | The presence of the word "FATAL" in the category list will escalate any | |
288 | warnings from the category specified that are detected in the lexical | |
289 | scope into fatal errors. In the code below, there are 3 places where | |
290 | a deprecated warning will be detected, the middle one will produce a | |
291 | fatal error. | |
292 | ||
293 | ||
294 | use warning ; | |
295 | ||
296 | $a = 1 if $a EQ $b ; | |
297 | ||
298 | { | |
299 | use warning qw(FATAL deprecated) ; | |
300 | $a = 1 if $a EQ $b ; | |
301 | } | |
302 | ||
303 | $a = 1 if $a EQ $b ; | |
304 | ||
305 | =head1 TODO | |
306 | ||
307 | The experimental features need bottomed out. | |
308 | ||
309 | perl5db.pl | |
310 | The debugger saves and restores C<$^W> at runtime. I haven't checked | |
311 | whether the debugger will still work with the lexical warnings | |
312 | patch applied. | |
313 | ||
314 | diagnostics.pm | |
315 | I *think* I've got diagnostics to work with the lexical warnings | |
316 | patch, but there were design decisions made in diagnostics to work | |
317 | around the limitations of C<$^W>. Now that those limitations are gone, | |
318 | the module should be revisited. | |
319 | ||
0453d815 PM |
320 | =head1 SEE ALSO |
321 | ||
322 | L<warning>. | |
323 | ||
324 | =head1 AUTHOR | |
325 | ||
326 | Paul Marquess |