Commit | Line | Data |
0453d815 |
1 | =head1 NAME |
2 | |
3 | perllexwarn - Perl Lexical Warnings |
4 | |
5 | =head1 DESCRIPTION |
5a3e7812 |
6 | |
4438c4b7 |
7 | The C<use warnings> pragma is a replacement for both the command line |
0453d815 |
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: |
c47ff5f1 |
21 | |
4438c4b7 |
22 | use warnings ; |
23 | use warnings 'all' ; |
c47ff5f1 |
24 | |
0453d815 |
25 | Similarly all warnings are disabled in a block by either of these: |
26 | |
4438c4b7 |
27 | no warnings ; |
28 | no warnings 'all' ; |
0453d815 |
29 | |
30 | For example, consider the code below: |
31 | |
4438c4b7 |
32 | use warnings ; |
0453d815 |
33 | my $a ; |
34 | my $b ; |
35 | { |
4438c4b7 |
36 | no warnings ; |
0453d815 |
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 |
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 | |
0453d815 |
58 | With the introduction of lexical warnings, mandatory warnings now become |
59 | I<default> warnings. The difference is that although the previously |
60 | mandatory warnings are still enabled by default, they can then be |
61 | subsequently enabled or disabled with the lexical warning pragma. For |
e476b1b5 |
62 | example, in the code below, an C<"isn't numeric"> warning will only |
0453d815 |
63 | be reported for the C<$a> variable. |
64 | |
252aa082 |
65 | my $a = "2:" + 3; |
4438c4b7 |
66 | no warnings ; |
252aa082 |
67 | my $b = "2:" + 3; |
0453d815 |
68 | |
69 | Note that neither the B<-w> flag or the C<$^W> can be used to |
70 | disable/enable default warnings. They are still mandatory in this case. |
71 | |
72 | =head2 What's wrong with B<-w> and C<$^W> |
73 | |
74 | Although very useful, the big problem with using B<-w> on the command |
75 | line to enable warnings is that it is all or nothing. Take the typical |
76 | scenario when you are writing a Perl program. Parts of the code you |
77 | will write yourself, but it's very likely that you will make use of |
78 | pre-written Perl modules. If you use the B<-w> flag in this case, you |
79 | end up enabling warnings in pieces of code that you haven't written. |
80 | |
81 | Similarly, using C<$^W> to either disable or enable blocks of code is |
82 | fundamentally flawed. For a start, say you want to disable warnings in |
83 | a block of code. You might expect this to be enough to do the trick: |
84 | |
85 | { |
86 | local ($^W) = 0 ; |
87 | my $a =+ 2 ; |
88 | my $b ; chop $b ; |
89 | } |
90 | |
91 | When this code is run with the B<-w> flag, a warning will be produced |
92 | for the C<$a> line -- C<"Reversed += operator">. |
93 | |
94 | The problem is that Perl has both compile-time and run-time warnings. To |
95 | disable compile-time warnings you need to rewrite the code like this: |
96 | |
97 | { |
98 | BEGIN { $^W = 0 } |
99 | my $a =+ 2 ; |
100 | my $b ; chop $b ; |
101 | } |
102 | |
103 | The other big problem with C<$^W> is that way you can inadvertently |
104 | change the warning setting in unexpected places in your code. For example, |
105 | when the code below is run (without the B<-w> flag), the second call |
106 | to C<doit> will trip a C<"Use of uninitialized value"> warning, whereas |
107 | the first will not. |
108 | |
109 | sub doit |
110 | { |
111 | my $b ; chop $b ; |
112 | } |
113 | |
114 | doit() ; |
115 | |
116 | { |
117 | local ($^W) = 1 ; |
118 | doit() |
119 | } |
120 | |
121 | This is a side-effect of C<$^W> being dynamically scoped. |
122 | |
123 | Lexical warnings get around these limitations by allowing finer control |
124 | over where warnings can or can't be tripped. |
125 | |
126 | =head2 Controlling Warnings from the Command Line |
127 | |
128 | There are three Command Line flags that can be used to control when |
129 | warnings are (or aren't) produced: |
130 | |
131 | =over 5 |
132 | |
133 | =item B<-w> |
134 | |
135 | This is the existing flag. If the lexical warnings pragma is B<not> |
136 | used in any of you code, or any of the modules that you use, this flag |
137 | will enable warnings everywhere. See L<Backward Compatibility> for |
138 | details of how this flag interacts with lexical warnings. |
139 | |
140 | =item B<-W> |
c47ff5f1 |
141 | |
0453d815 |
142 | If the B<-W> flag is used on the command line, it will enable all warnings |
143 | throughout the program regardless of whether warnings were disabled |
4438c4b7 |
144 | locally using C<no warnings> or C<$^W =0>. This includes all files that get |
0453d815 |
145 | included via C<use>, C<require> or C<do>. |
146 | Think of it as the Perl equivalent of the "lint" command. |
147 | |
148 | =item B<-X> |
149 | |
150 | Does the exact opposite to the B<-W> flag, i.e. it disables all warnings. |
151 | |
152 | =back |
153 | |
154 | =head2 Backward Compatibility |
155 | |
156 | If you are used with working with a version of Perl prior to the |
157 | introduction of lexically scoped warnings, or have code that uses both |
158 | lexical warnings and C<$^W>, this section will describe how they interact. |
159 | |
160 | How Lexical Warnings interact with B<-w>/C<$^W>: |
5a3e7812 |
161 | |
0453d815 |
162 | =over 5 |
163 | |
164 | =item 1. |
165 | |
166 | If none of the three command line flags (B<-w>, B<-W> or B<-X>) that |
e476b1b5 |
167 | control warnings is used and neither C<$^W> or the C<warnings> pragma |
168 | are used, then default warnings will be enabled and optional warnings |
169 | disabled. |
0453d815 |
170 | This means that legacy code that doesn't attempt to control the warnings |
171 | will work unchanged. |
172 | |
173 | =item 2. |
174 | |
175 | The B<-w> flag just sets the global C<$^W> variable as in 5.005 -- this |
176 | means that any legacy code that currently relies on manipulating C<$^W> |
177 | to control warning behavior will still work as is. |
178 | |
179 | =item 3. |
c47ff5f1 |
180 | |
0453d815 |
181 | Apart from now being a boolean, the C<$^W> variable operates in exactly |
182 | the same horrible uncontrolled global way, except that it cannot |
183 | disable/enable default warnings. |
184 | |
185 | =item 4. |
c47ff5f1 |
186 | |
e476b1b5 |
187 | If a piece of code is under the control of the C<warnings> pragma, |
0453d815 |
188 | both the C<$^W> variable and the B<-w> flag will be ignored for the |
189 | scope of the lexical warning. |
190 | |
191 | =item 5. |
c47ff5f1 |
192 | |
0453d815 |
193 | The only way to override a lexical warnings setting is with the B<-W> |
194 | or B<-X> command line flags. |
195 | |
196 | =back |
197 | |
198 | The combined effect of 3 & 4 is that it will will allow code which uses |
e476b1b5 |
199 | the C<warnings> pragma to control the warning behavior of $^W-type |
0453d815 |
200 | code (using a C<local $^W=0>) if it really wants to, but not vice-versa. |
201 | |
0453d815 |
202 | =head2 Category Hierarchy |
c47ff5f1 |
203 | |
e476b1b5 |
204 | A hierarchy of "categories" have been defined to allow groups of warnings |
205 | to be enabled/disabled in isolation. |
206 | |
207 | The current hierarchy is: |
208 | |
209 | all -+ |
210 | | |
211 | +- chmod |
212 | | |
213 | +- closure |
214 | | |
215 | +- exiting |
216 | | |
217 | +- glob |
218 | | |
219 | +- io -----------+ |
220 | | | |
221 | | +- closed |
222 | | | |
223 | | +- exec |
224 | | | |
225 | | +- newline |
226 | | | |
227 | | +- pipe |
228 | | | |
229 | | +- unopened |
230 | | |
231 | +- misc |
232 | | |
233 | +- numeric |
234 | | |
235 | +- once |
236 | | |
237 | +- overflow |
238 | | |
239 | +- pack |
240 | | |
241 | +- portable |
242 | | |
243 | +- recursion |
244 | | |
245 | +- redefine |
246 | | |
247 | +- regexp |
248 | | |
249 | +- severe -------+ |
250 | | | |
251 | | +- debugging |
252 | | | |
253 | | +- inplace |
254 | | | |
255 | | +- internal |
256 | | | |
257 | | +- malloc |
258 | | |
259 | +- signal |
260 | | |
261 | +- substr |
262 | | |
263 | +- syntax -------+ |
264 | | | |
265 | | +- ambiguous |
266 | | | |
267 | | +- bareword |
268 | | | |
269 | | +- deprecated |
270 | | | |
271 | | +- digit |
272 | | | |
273 | | +- parenthesis |
274 | | | |
275 | | +- precedence |
276 | | | |
277 | | +- printf |
278 | | | |
279 | | +- prototype |
280 | | | |
281 | | +- qw |
282 | | | |
283 | | +- reserved |
284 | | | |
285 | | +- semicolon |
286 | | |
287 | +- taint |
288 | | |
289 | +- umask |
290 | | |
291 | +- uninitialized |
292 | | |
293 | +- unpack |
294 | | |
295 | +- untie |
296 | | |
297 | +- utf8 |
298 | | |
299 | +- void |
300 | | |
301 | +- y2k |
0453d815 |
302 | |
4438c4b7 |
303 | Just like the "strict" pragma any of these categories can be combined |
304 | |
305 | use warnings qw(void redefine) ; |
306 | no warnings qw(io syntax untie) ; |
307 | |
308 | Also like the "strict" pragma, if there is more than one instance of the |
e476b1b5 |
309 | C<warnings> pragma in a given scope the cumulative effect is additive. |
4438c4b7 |
310 | |
311 | use warnings qw(void) ; # only "void" warnings enabled |
312 | ... |
313 | use warnings qw(io) ; # only "void" & "io" warnings enabled |
314 | ... |
315 | no warnings qw(void) ; # only "io" warnings enabled |
316 | |
e476b1b5 |
317 | To determine which category a specific warning has been assigned to see |
318 | L<perldiag>. |
0453d815 |
319 | |
320 | =head2 Fatal Warnings |
c47ff5f1 |
321 | |
0453d815 |
322 | The presence of the word "FATAL" in the category list will escalate any |
e476b1b5 |
323 | warnings detected from the categories specified in the lexical scope |
324 | into fatal errors. In the code below, there are 3 places where a |
325 | deprecated warning will be detected, the middle one will produce a |
326 | fatal error. |
4438c4b7 |
327 | |
328 | |
329 | use warnings ; |
c47ff5f1 |
330 | |
0453d815 |
331 | $a = 1 if $a EQ $b ; |
c47ff5f1 |
332 | |
0453d815 |
333 | { |
4438c4b7 |
334 | use warnings FATAL => qw(deprecated) ; |
0453d815 |
335 | $a = 1 if $a EQ $b ; |
336 | } |
c47ff5f1 |
337 | |
0453d815 |
338 | $a = 1 if $a EQ $b ; |
0453d815 |
339 | |
e476b1b5 |
340 | =head2 Reporting Warnings from a Module |
341 | |
d3a7d8c7 |
342 | The C<warnings> pragma provides a number of functions that are useful for |
343 | module authors. These are used when you want to report a module-specific |
344 | warning when the calling module has enabled warnings via the C<warnings> |
345 | pragma. |
e476b1b5 |
346 | |
d3a7d8c7 |
347 | Consider the module C<MyMod::Abc> below. |
e476b1b5 |
348 | |
d3a7d8c7 |
349 | package MyMod::Abc; |
e476b1b5 |
350 | |
d3a7d8c7 |
351 | use warnings::register; |
352 | |
353 | sub open { |
354 | my $path = shift ; |
355 | if (warnings::enabled() && $path !~ m#^/#) { |
356 | warnings::warn("changing relative path to /tmp/"); |
357 | $path = "/tmp/$path" ; |
358 | } |
359 | } |
360 | |
361 | 1 ; |
362 | |
363 | The call to C<warnings::register> will create a new warnings category |
364 | called "MyMod::abc", i.e. the new category name matches the module |
365 | name. The C<open> function in the module will display a warning message |
366 | if it gets given a relative path as a parameter. This warnings will only |
367 | be displayed if the code that uses C<MyMod::Abc> has actually enabled |
368 | them with the C<warnings> pragma like below. |
369 | |
370 | use MyMod::Abc; |
371 | use warnings 'MyMod::Abc'; |
372 | ... |
373 | abc::open("../fred.txt"); |
374 | |
375 | It is also possible to test whether the pre-defined warnings categories are |
376 | set in the calling module with the C<warnings::enabled> function. Consider |
377 | this snippet of code: |
378 | |
379 | package MyMod::Abc; |
380 | |
381 | sub open { |
e476b1b5 |
382 | if (warnings::enabled("deprecated")) { |
383 | warnings::warn("deprecated", |
d3a7d8c7 |
384 | "open is deprecated, use new instead") ; |
e476b1b5 |
385 | } |
386 | new(@_) ; |
387 | } |
6bc102ca |
388 | |
e476b1b5 |
389 | sub new |
390 | ... |
391 | 1 ; |
392 | |
393 | The function C<open> has been deprecated, so code has been included to |
394 | display a warning message whenever the calling module has (at least) the |
395 | "deprecated" warnings category enabled. Something like this, say. |
396 | |
397 | use warnings 'deprecated'; |
d3a7d8c7 |
398 | use MyMod::Abc; |
e476b1b5 |
399 | ... |
d3a7d8c7 |
400 | MyMod::Abc::open($filename) ; |
e476b1b5 |
401 | |
d3a7d8c7 |
402 | The C<warnings::warn> function should be used to actually display the |
403 | warnings message. This is because they can make use of the feature that |
404 | allows warnings to be escalated into fatal errors. So in this case |
e476b1b5 |
405 | |
d3a7d8c7 |
406 | use MyMod::Abc; |
407 | use warnings FATAL => 'MyMod::Abc'; |
e476b1b5 |
408 | ... |
d3a7d8c7 |
409 | MyMod::Abc::open('../fred.txt'); |
e476b1b5 |
410 | |
d3a7d8c7 |
411 | the C<warnings::warn> function will detect this and die after |
412 | displaying the warning message. |
e476b1b5 |
413 | |
414 | =head1 TODO |
c47ff5f1 |
415 | |
0453d815 |
416 | perl5db.pl |
417 | The debugger saves and restores C<$^W> at runtime. I haven't checked |
418 | whether the debugger will still work with the lexical warnings |
419 | patch applied. |
420 | |
421 | diagnostics.pm |
422 | I *think* I've got diagnostics to work with the lexical warnings |
423 | patch, but there were design decisions made in diagnostics to work |
424 | around the limitations of C<$^W>. Now that those limitations are gone, |
425 | the module should be revisited. |
426 | |
0453d815 |
427 | =head1 SEE ALSO |
428 | |
e476b1b5 |
429 | L<warnings>, L<perldiag>. |
c47ff5f1 |
430 | |
0453d815 |
431 | =head1 AUTHOR |
c47ff5f1 |
432 | |
0453d815 |
433 | Paul Marquess |