This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
cee16875377f8c495a3304bf361fe3e76486cc03
[perl5.git] / pod / perllexwarn.pod
1 =head1 NAME
2
3 perllexwarn - Perl Lexical Warnings
4
5 =head1 DESCRIPTION
6
7 The C<use warnings> pragma is a replacement for both the command line
8 flag B<-w> and the equivalent Perl variable, C<$^W>.
9
10 The pragma works just like the existing "strict" pragma.
11 This means that the scope of the warning pragma is limited to the
12 enclosing block. It also means that that the pragma setting will not
13 leak across files (via C<use>, C<require> or C<do>). This allows
14 authors to independently define the degree of warning checks that will
15 be applied to their module.
16
17 By default, optional warnings are disabled, so any legacy code that
18 doesn't attempt to control the warnings will work unchanged.
19
20 All warnings are enabled in a block by either of these:
21
22     use warnings ;
23     use warnings 'all' ;
24
25 Similarly all warnings are disabled in a block by either of these:
26
27     no warnings ;
28     no warnings 'all' ;
29
30 For example, consider the code below:
31
32     use warnings ;
33     my $a ;
34     my $b ;
35     {
36         no warnings ;
37         $b = 2 if $a EQ 3 ;
38     }
39     $b = 1 if $a NE 3 ;
40
41 The code in the enclosing block has warnings enabled, but the inner
42 block has them disabled. In this case that means that the use of the C<EQ>
43 operator won't trip a C<"Use of EQ is deprecated"> warning, but the use of
44 C<NE> will produce a C<"Use of NE is deprecated"> warning.
45
46 =head2 Default Warnings and Optional Warnings
47
48 Before the introduction of lexical warnings, Perl had two classes of
49 warnings: mandatory and optional. 
50
51 As its name suggests, if your code tripped a mandatory warning, you
52 would get a warning whether you wanted it or not.
53 For example, the code below would always produce an C<"isn't numeric">
54 warning about the "2:".
55
56     my $a = "2:" + 3;
57
58 With the introduction of lexical warnings, mandatory warnings now become
59 I<default> warnings. The difference is that although the previously
60 mandatory warnings are still enabled by default, they can then be
61 subsequently enabled or disabled with the lexical warning pragma. For
62 example, in the code below, an C<"isn't numeric"> warning will only
63 be reported for the C<$a> variable.
64
65     my $a = "2:" + 3;
66     no warnings ;
67     my $b = "2:" + 3;
68
69 Note that neither the B<-w> flag or the C<$^W> can be used to
70 disable/enable default warnings. They are still mandatory in this case.
71
72 =head2 What's wrong with B<-w> and C<$^W>
73
74 Although very useful, the big problem with using B<-w> on the command
75 line 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 B<-w> flag in this case, you
79 end up enabling warnings in pieces of code that you haven't written.
80
81 Similarly, using C<$^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 B<-w> flag, a warning will be produced
92 for the C<$a> line -- C<"Reversed += operator">.
93
94 The problem is that Perl has both compile-time and run-time warnings. To
95 disable compile-time warnings you need to rewrite the code like this:
96
97      {
98          BEGIN { $^W = 0 }
99          my $a =+ 2 ;
100          my $b ; chop $b ;
101      }
102
103 The other big problem with C<$^W> is that way you can inadvertently
104 change the warning setting in unexpected places in your code. For example,
105 when the code below is run (without the B<-w> flag), the second call
106 to C<doit> will trip a C<"Use of uninitialized value"> warning, whereas
107 the first will not.
108
109     sub doit
110     {
111         my $b ; chop $b ;
112     }
113
114     doit() ;
115
116     {
117         local ($^W) = 1 ;
118         doit()
119     }
120
121 This is a side-effect of C<$^W> being dynamically scoped.
122
123 Lexical warnings get around these limitations by allowing finer control
124 over where warnings can or can't be tripped.
125
126 =head2 Controlling Warnings from the Command Line
127
128 There are three Command Line flags that can be used to control when
129 warnings are (or aren't) produced:
130
131 =over 5
132
133 =item B<-w>
134
135 This is  the existing flag. If the lexical warnings pragma is B<not>
136 used in any of you code, or any of the modules that you use, this flag
137 will enable warnings everywhere. See L<Backward Compatibility> for
138 details of how this flag interacts with lexical warnings.
139
140 =item B<-W>
141
142 If the B<-W> flag is used on the command line, it will enable all warnings
143 throughout the program regardless of whether warnings were disabled
144 locally using C<no warnings> or C<$^W =0>. This includes all files that get
145 included via C<use>, C<require> or C<do>.
146 Think of it as the Perl equivalent of the "lint" command.
147
148 =item B<-X>
149
150 Does the exact opposite to the B<-W> flag, i.e. it disables all warnings.
151
152 =back
153
154 =head2 Backward Compatibility
155
156 If you are used with working with a version of Perl prior to the
157 introduction of lexically scoped warnings, or have code that uses both
158 lexical warnings and C<$^W>, this section will describe how they interact.
159
160 How Lexical Warnings interact with B<-w>/C<$^W>:
161
162 =over 5
163
164 =item 1.
165
166 If none of the three command line flags (B<-w>, B<-W> or B<-X>) that
167 control warnings is used and neither C<$^W> or the C<warnings> pragma
168 are used, then default warnings will be enabled and optional warnings
169 disabled.
170 This means that legacy code that doesn't attempt to control the warnings
171 will work unchanged.
172
173 =item 2.
174
175 The B<-w> flag just sets the global C<$^W> variable as in 5.005 -- this
176 means that any legacy code that currently relies on manipulating C<$^W>
177 to control warning behavior will still work as is. 
178
179 =item 3.
180
181 Apart from now being a boolean, the C<$^W> variable operates in exactly
182 the same horrible uncontrolled global way, except that it cannot
183 disable/enable default warnings.
184
185 =item 4.
186
187 If a piece of code is under the control of the C<warnings> pragma,
188 both the C<$^W> variable and the B<-w> flag will be ignored for the
189 scope of the lexical warning.
190
191 =item 5.
192
193 The only way to override a lexical warnings setting is with the B<-W>
194 or B<-X> command line flags.
195
196 =back
197
198 The combined effect of 3 & 4 is that it will will allow code which uses
199 the C<warnings> pragma to control the warning behavior of $^W-type
200 code (using a C<local $^W=0>) if it really wants to, but not vice-versa.
201
202 =head2 Category Hierarchy
203
204 A hierarchy of "categories" have been defined to allow groups of warnings
205 to be enabled/disabled in isolation.
206
207 The current hierarchy is:
208
209   all -+
210        |
211        +- chmod
212        |
213        +- closure
214        |
215        +- exiting
216        |
217        +- glob
218        |
219        +- io -----------+
220        |                |
221        |                +- closed
222        |                |
223        |                +- exec
224        |                |
225        |                +- newline
226        |                |
227        |                +- pipe
228        |                |
229        |                +- unopened
230        |
231        +- misc
232        |
233        +- numeric
234        |
235        +- once
236        |
237        +- overflow
238        |
239        +- pack
240        |
241        +- portable
242        |
243        +- recursion
244        |
245        +- redefine
246        |
247        +- regexp
248        |
249        +- severe -------+
250        |                |
251        |                +- debugging
252        |                |
253        |                +- inplace
254        |                |
255        |                +- internal
256        |                |
257        |                +- malloc
258        |
259        +- signal
260        |
261        +- substr
262        |
263        +- syntax -------+
264        |                |
265        |                +- ambiguous
266        |                |
267        |                +- bareword
268        |                |
269        |                +- deprecated
270        |                |
271        |                +- digit
272        |                |
273        |                +- parenthesis
274        |                |
275        |                +- precedence
276        |                |
277        |                +- printf
278        |                |
279        |                +- prototype
280        |                |
281        |                +- qw
282        |                |
283        |                +- reserved
284        |                |
285        |                +- semicolon
286        |
287        +- taint
288        |
289        +- umask
290        |
291        +- uninitialized
292        |
293        +- unpack
294        |
295        +- untie
296        |
297        +- utf8
298        |
299        +- void
300        |
301        +- y2k
302
303 Just like the "strict" pragma any of these categories can be combined
304
305     use warnings qw(void redefine) ;
306     no warnings qw(io syntax untie) ;
307
308 Also like the "strict" pragma, if there is more than one instance of the
309 C<warnings> pragma in a given scope the cumulative effect is additive. 
310
311     use warnings qw(void) ; # only "void" warnings enabled
312     ...
313     use warnings qw(io) ;   # only "void" & "io" warnings enabled
314     ...
315     no warnings qw(void) ;  # only "io" warnings enabled
316
317 To determine which category a specific warning has been assigned to see
318 L<perldiag>.
319
320 =head2 Fatal Warnings
321
322 The presence of the word "FATAL" in the category list will escalate any
323 warnings detected from the categories specified in the lexical scope
324 into fatal errors. In the code below, there are 3 places where a
325 deprecated warning will be detected, the middle one will produce a
326 fatal error.
327
328
329     use warnings ;
330
331     $a = 1 if $a EQ $b ;
332
333     {
334         use warnings FATAL => qw(deprecated) ;
335         $a = 1 if $a EQ $b ;
336     }
337
338     $a = 1 if $a EQ $b ;
339
340 =head2 Reporting Warnings from a Module
341
342 The C<warnings> pragma provides a number of functions that are useful for
343 module authors. These are used when you want to report a module-specific
344 warning when the calling module has enabled warnings via the C<warnings>
345 pragma.
346
347 Consider the module C<MyMod::Abc> below.
348
349     package MyMod::Abc;
350
351     use warnings::register;
352
353     sub open {
354         my $path = shift ;
355         if (warnings::enabled() && $path !~ m#^/#) {
356             warnings::warn("changing relative path to /tmp/");
357             $path = "/tmp/$path" ; 
358         }
359     }
360
361     1 ;
362
363 The call to C<warnings::register> will create a new warnings category
364 called "MyMod::abc", i.e. the new category name matches the module
365 name. The C<open> function in the module will display a warning message
366 if it gets given a relative path as a parameter. This warnings will only
367 be displayed if the code that uses C<MyMod::Abc> has actually enabled
368 them with the C<warnings> pragma like below.
369
370     use MyMod::Abc;
371     use warnings 'MyMod::Abc';
372     ...
373     abc::open("../fred.txt");
374
375 It is also possible to test whether the pre-defined warnings categories are
376 set in the calling module with the C<warnings::enabled> function. Consider
377 this snippet of code:
378
379     package MyMod::Abc;
380
381     sub open {
382         if (warnings::enabled("deprecated")) {
383             warnings::warn("deprecated", 
384                            "open is deprecated, use new instead") ;
385         }
386         new(@_) ;
387     }
388
389     sub new
390     ...
391     1 ;
392
393 The function C<open> has been deprecated, so code has been included to
394 display a warning message whenever the calling module has (at least) the
395 "deprecated" warnings category enabled. Something like this, say.
396
397     use warnings 'deprecated';
398     use MyMod::Abc;
399     ...
400     MyMod::Abc::open($filename) ;
401
402 The C<warnings::warn> function should be used to actually display the
403 warnings message. This is because they can make use of the feature that
404 allows warnings to be escalated into fatal errors. So in this case
405
406     use MyMod::Abc;
407     use warnings FATAL => 'MyMod::Abc';
408     ...
409     MyMod::Abc::open('../fred.txt');
410
411 the C<warnings::warn> function will detect this and die after
412 displaying the warning message.
413
414 =head1 TODO
415
416   perl5db.pl
417     The debugger saves and restores C<$^W> at runtime. I haven't checked
418     whether the debugger will still work with the lexical warnings
419     patch applied.
420
421   diagnostics.pm
422     I *think* I've got diagnostics to work with the lexical warnings
423     patch, but there were design decisions made in diagnostics to work
424     around the limitations of C<$^W>. Now that those limitations are gone,
425     the module should be revisited.
426
427 =head1 SEE ALSO
428
429 L<warnings>, L<perldiag>.
430
431 =head1 AUTHOR
432
433 Paul Marquess