1PERLLEXWARN(1)         Perl Programmers Reference Guide         PERLLEXWARN(1)
2
3
4

NAME

6       perllexwarn - Perl Lexical Warnings
7

DESCRIPTION

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

SEE ALSO

503       warnings, perldiag.
504

AUTHOR

506       Paul Marquess
507
508
509
510perl v5.16.3                      2013-03-04                    PERLLEXWARN(1)
Impressum