1PERLLEXWARN(1) Perl Programmers Reference Guide PERLLEXWARN(1)
2
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 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 By default, optional warnings are disabled, so any legacy code that
21 doesn't attempt to control the warnings will work unchanged.
22 All warnings are enabled in a block by either of these:
24 use warnings;
26 use warnings 'all';
27 Similarly all warnings are disabled in a block by either of these:
29 no warnings;
31 no warnings 'all';
32 For example, consider the code below:
34 use warnings;
36 my @a;
37 {
38 no warnings;
39 my $b = @a[0];
40 }
41 my $c = @a[0];
42 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 Default Warnings and Optional Warnings
49 Before the introduction of lexical warnings, Perl had two classes of
50 warnings: mandatory and optional.
51 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 my $a = "2:" + 3;
58 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 my $a = "2:" + 3;
67 no warnings;
68 my $b = "2:" + 3;
69 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 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 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 {
86 local ($^W) = 0;
87 my $a =+ 2;
88 my $b; chop $b;
89 }
90 When this code is run with the -w flag, a warning will be produced for
92 the $a line: "Reversed += operator".
93 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 {
99 BEGIN { $^W = 0 }
100 my $a =+ 2;
101 my $b; chop $b;
102 }
103 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 sub doit
111 {
112 my $b; chop $b;
113 }
114 doit();
116 {
118 local ($^W) = 1;
119 doit()
120 }
121 This is a side-effect of $^W being dynamically scoped.
123 Lexical warnings get around these limitations by allowing finer control
125 over where warnings can or can't be tripped.
126 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 -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 -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 -X Does the exact opposite to the -W flag, i.e. it disables all
143 warnings.
144 Backward Compatibility
146 If you are used with 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 How Lexical Warnings interact with -w/$^W:
151 1. If none of the three command line flags (-w, -W or -X) that
153 control warnings is used and neither $^W or 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 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 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 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 5. The only way to override a lexical warnings setting is with the -W
171 or -X command line flags.
172 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 Category Hierarchy
178 A hierarchy of "categories" have been defined to allow groups of
179 warnings to be enabled/disabled in isolation.
180 The current hierarchy is:
182 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 +- void
278 Just like the "strict" pragma any of these categories can be combined
280 use warnings qw(void redefine);
282 no warnings qw(io syntax untie);
283 Also like the "strict" pragma, if there is more than one instance of
285 the "warnings" pragma in a given scope the cumulative effect is
286 additive.
287 use warnings qw(void); # only "void" warnings enabled
289 ...
290 use warnings qw(io); # only "void" & "io" warnings enabled
291 ...
292 no warnings qw(void); # only "io" warnings enabled
293 To determine which category a specific warning has been assigned to see
295 perldiag.
296 Note: In Perl 5.6.1, the lexical warnings category "deprecated" was a
298 sub-category of the "syntax" category. It is now a top-level category
299 in its own right.
300 Fatal Warnings
302 The presence of the word "FATAL" in the category list will escalate any
303 warnings detected from the categories specified in the lexical scope
304 into fatal errors. In the code below, the use of "time", "length" and
305 "join" can all produce a "Useless use of xxx in void context" warning.
306 use warnings;
308 time;
310 {
312 use warnings FATAL => qw(void);
313 length "abc";
314 }
315 join "", 1,2,3;
317 print "done\n";
319 When run it produces this output
321 Useless use of time in void context at fatal line 3.
323 Useless use of length in void context at fatal line 7.
324 The scope where "length" is used has escalated the "void" warnings
326 category into a fatal error, so the program terminates immediately it
327 encounters the warning.
328 To explicitly turn off a "FATAL" warning you just disable the warning
330 it is associated with. So, for example, to disable the "void" warning
331 in the example above, either of these will do the trick:
332 no warnings qw(void);
334 no warnings FATAL => qw(void);
335 If you want to downgrade a warning that has been escalated into a fatal
337 error back to a normal warning, you can use the "NONFATAL" keyword. For
338 example, the code below will promote all warnings into fatal errors,
339 except for those in the "syntax" category.
340 use warnings FATAL => 'all', NONFATAL => 'syntax';
342 Reporting Warnings from a Module
344 The "warnings" pragma provides a number of functions that are useful
345 for module authors. These are used when you want to report a module-
346 specific warning to a calling module has enabled warnings via the
347 "warnings" pragma.
348 Consider the module "MyMod::Abc" below.
350 package MyMod::Abc;
352 use warnings::register;
354 sub open {
356 my $path = shift;
357 if ($path !~ m#^/#) {
358 warnings::warn("changing relative path to /var/abc")
359 if warnings::enabled();
360 $path = "/var/abc/$path";
361 }
362 }
363 1;
365 The call to "warnings::register" will create a new warnings category
367 called "MyMod::Abc", i.e. the new category name matches the current
368 package name. The "open" function in the module will display a warning
369 message if it gets given a relative path as a parameter. This warnings
370 will only be displayed if the code that uses "MyMod::Abc" has actually
371 enabled them with the "warnings" pragma like below.
372 use MyMod::Abc;
374 use warnings 'MyMod::Abc';
375 ...
376 abc::open("../fred.txt");
377 It is also possible to test whether the pre-defined warnings categories
379 are set in the calling module with the "warnings::enabled" function.
380 Consider this snippet of code:
381 package MyMod::Abc;
383 sub open {
385 warnings::warnif("deprecated",
386 "open is deprecated, use new instead");
387 new(@_);
388 }
389 sub new
391 ...
392 1;
393 The function "open" has been deprecated, so code has been included to
395 display a warning message whenever the calling module has (at least)
396 the "deprecated" warnings category enabled. Something like this, say.
397 use warnings 'deprecated';
399 use MyMod::Abc;
400 ...
401 MyMod::Abc::open($filename);
402 Either the "warnings::warn" or "warnings::warnif" function should be
404 used to actually display the warnings message. This is because they can
405 make use of the feature that allows warnings to be escalated into fatal
406 errors. So in this case
407 use MyMod::Abc;
409 use warnings FATAL => 'MyMod::Abc';
410 ...
411 MyMod::Abc::open('../fred.txt');
412 the "warnings::warnif" function will detect this and die after
414 displaying the warning message.
415 The three warnings functions, "warnings::warn", "warnings::warnif" and
417 "warnings::enabled" can optionally take an object reference in place of
418 a category name. In this case the functions will use the class name of
419 the object as the warnings category.
420 Consider this example:
422 package Original;
424 no warnings;
426 use warnings::register;
427 sub new
429 {
430 my $class = shift;
431 bless [], $class;
432 }
433 sub check
435 {
436 my $self = shift;
437 my $value = shift;
438 if ($value % 2 && warnings::enabled($self))
440 { warnings::warn($self, "Odd numbers are unsafe") }
441 }
442 sub doit
444 {
445 my $self = shift;
446 my $value = shift;
447 $self->check($value);
448 # ...
449 }
450 1;
452 package Derived;
454 use warnings::register;
456 use Original;
457 our @ISA = qw( Original );
458 sub new
459 {
460 my $class = shift;
461 bless [], $class;
462 }
463 1;
466 The code below makes use of both modules, but it only enables warnings
468 from "Derived".
469 use Original;
471 use Derived;
472 use warnings 'Derived';
473 my $a = Original->new();
474 $a->doit(1);
475 my $b = Derived->new();
476 $a->doit(1);
477 When this code is run only the "Derived" object, $b, will generate a
479 warning.
480 Odd numbers are unsafe at main.pl line 7
482 Notice also that the warning is reported at the line where the object
484 is first used.
485
487 warnings, perldiag.
488
490 Paul Marquess
491perl v5.12.4 2011-06-07 PERLLEXWARN(1)