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