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