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