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 +- misc
208 |
209 +- numeric
210 |
211 +- once
212 |
213 +- overflow
214 |
215 +- pack
216 |
217 +- portable
218 |
219 +- recursion
220 |
221 +- redefine
222 |
223 +- regexp
224 |
225 +- severe -------+
226 | |
227 | +- debugging
228 | |
229 | +- inplace
230 | |
231 | +- internal
232 | |
233 | +- malloc
234 |
235 +- signal
236 |
237 +- substr
238 |
239 +- syntax -------+
240 | |
241 | +- ambiguous
242 | |
243 | +- bareword
244 | |
245 | +- digit
246 | |
247 | +- parenthesis
248 | |
249 | +- precedence
250 | |
251 | +- printf
252 | |
253 | +- prototype
254 | |
255 | +- qw
256 | |
257 | +- reserved
258 | |
259 | +- semicolon
260 |
261 +- taint
262 |
263 +- threads
264 |
265 +- uninitialized
266 |
267 +- unpack
268 |
269 +- untie
270 |
271 +- utf8
272 |
273 +- void
274 Just like the "strict" pragma any of these categories can be combined
276 use warnings qw(void redefine);
278 no warnings qw(io syntax untie);
279 Also like the "strict" pragma, if there is more than one instance of
281 the "warnings" pragma in a given scope the cumulative effect is
282 additive.
283 use warnings qw(void); # only "void" warnings enabled
285 ...
286 use warnings qw(io); # only "void" & "io" warnings enabled
287 ...
288 no warnings qw(void); # only "io" warnings enabled
289 To determine which category a specific warning has been assigned to see
291 perldiag.
292 Note: In Perl 5.6.1, the lexical warnings category "deprecated" was a
294 sub-category of the "syntax" category. It is now a top-level category
295 in its own right.
296 Fatal Warnings
298 The presence of the word "FATAL" in the category list will escalate any
299 warnings detected from the categories specified in the lexical scope
300 into fatal errors. In the code below, the use of "time", "length" and
301 "join" can all produce a "Useless use of xxx in void context" warning.
302 use warnings;
304 time;
306 {
308 use warnings FATAL => qw(void);
309 length "abc";
310 }
311 join "", 1,2,3;
313 print "done\n";
315 When run it produces this output
317 Useless use of time in void context at fatal line 3.
319 Useless use of length in void context at fatal line 7.
320 The scope where "length" is used has escalated the "void" warnings
322 category into a fatal error, so the program terminates immediately it
323 encounters the warning.
324 To explicitly turn off a "FATAL" warning you just disable the warning
326 it is associated with. So, for example, to disable the "void" warning
327 in the example above, either of these will do the trick:
328 no warnings qw(void);
330 no warnings FATAL => qw(void);
331 If you want to downgrade a warning that has been escalated into a fatal
333 error back to a normal warning, you can use the "NONFATAL" keyword. For
334 example, the code below will promote all warnings into fatal errors,
335 except for those in the "syntax" category.
336 use warnings FATAL => 'all', NONFATAL => 'syntax';
338 Reporting Warnings from a Module
340 The "warnings" pragma provides a number of functions that are useful
341 for module authors. These are used when you want to report a module-
342 specific warning to a calling module has enabled warnings via the
343 "warnings" pragma.
344 Consider the module "MyMod::Abc" below.
346 package MyMod::Abc;
348 use warnings::register;
350 sub open {
352 my $path = shift;
353 if ($path !~ m#^/#) {
354 warnings::warn("changing relative path to /var/abc")
355 if warnings::enabled();
356 $path = "/var/abc/$path";
357 }
358 }
359 1;
361 The call to "warnings::register" will create a new warnings category
363 called "MyMod::abc", i.e. the new category name matches the current
364 package name. The "open" function in the module will display a warning
365 message if it gets given a relative path as a parameter. This warnings
366 will only be displayed if the code that uses "MyMod::Abc" has actually
367 enabled them with the "warnings" pragma like below.
368 use MyMod::Abc;
370 use warnings 'MyMod::Abc';
371 ...
372 abc::open("../fred.txt");
373 It is also possible to test whether the pre-defined warnings categories
375 are set in the calling module with the "warnings::enabled" function.
376 Consider this snippet of code:
377 package MyMod::Abc;
379 sub open {
381 warnings::warnif("deprecated",
382 "open is deprecated, use new instead");
383 new(@_);
384 }
385 sub new
387 ...
388 1;
389 The function "open" has been deprecated, so code has been included to
391 display a warning message whenever the calling module has (at least)
392 the "deprecated" warnings category enabled. Something like this, say.
393 use warnings 'deprecated';
395 use MyMod::Abc;
396 ...
397 MyMod::Abc::open($filename);
398 Either the "warnings::warn" or "warnings::warnif" function should be
400 used to actually display the warnings message. This is because they can
401 make use of the feature that allows warnings to be escalated into fatal
402 errors. So in this case
403 use MyMod::Abc;
405 use warnings FATAL => 'MyMod::Abc';
406 ...
407 MyMod::Abc::open('../fred.txt');
408 the "warnings::warnif" function will detect this and die after
410 displaying the warning message.
411 The three warnings functions, "warnings::warn", "warnings::warnif" and
413 "warnings::enabled" can optionally take an object reference in place of
414 a category name. In this case the functions will use the class name of
415 the object as the warnings category.
416 Consider this example:
418 package Original;
420 no warnings;
422 use warnings::register;
423 sub new
425 {
426 my $class = shift;
427 bless [], $class;
428 }
429 sub check
431 {
432 my $self = shift;
433 my $value = shift;
434 if ($value % 2 && warnings::enabled($self))
436 { warnings::warn($self, "Odd numbers are unsafe") }
437 }
438 sub doit
440 {
441 my $self = shift;
442 my $value = shift;
443 $self->check($value);
444 # ...
445 }
446 1;
448 package Derived;
450 use warnings::register;
452 use Original;
453 our @ISA = qw( Original );
454 sub new
455 {
456 my $class = shift;
457 bless [], $class;
458 }
459 1;
462 The code below makes use of both modules, but it only enables warnings
464 from "Derived".
465 use Original;
467 use Derived;
468 use warnings 'Derived';
469 my $a = Original->new();
470 $a->doit(1);
471 my $b = Derived->new();
472 $a->doit(1);
473 When this code is run only the "Derived" object, $b, will generate a
475 warning.
476 Odd numbers are unsafe at main.pl line 7
478 Notice also that the warning is reported at the line where the object
480 is first used.
481
483 warnings, perldiag.
484
486 Paul Marquess
487perl v5.10.1 2009-02-12 PERLLEXWARN(1)