source: trunk/third/perl/pod/perllexwarn.pod @ 17035

Revision 17035, 13.7 KB checked in by zacheiss, 23 years ago (diff)
This commit was generated by cvs2svn to compensate for changes in r17034, which included commits to RCS files with non-trunk default branches.
Line 
1=head1 NAME
2
3perllexwarn - Perl Lexical Warnings
4
5=head1 DESCRIPTION
6
7The C<use warnings> pragma is a replacement for both the command line
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
12enclosing block. It also means that the pragma setting will not
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:
21
22    use warnings ;
23    use warnings 'all' ;
24
25Similarly all warnings are disabled in a block by either of these:
26
27    no warnings ;
28    no warnings 'all' ;
29
30For example, consider the code below:
31
32    use warnings ;
33    my @a ;
34    {
35        no warnings ;
36        my $b = @a[0] ;
37    }
38    my $c = @a[0];
39
40The code in the enclosing block has warnings enabled, but the inner
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.
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.
52For example, the code below would always produce an C<"isn't numeric">
53warning about the "2:".
54
55    my $a = "2:" + 3;
56
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
61example, in the code below, an C<"isn't numeric"> warning will only
62be reported for the C<$a> variable.
63
64    my $a = "2:" + 3;
65    no warnings ;
66    my $b = "2:" + 3;
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
102The other big problem with C<$^W> is the way you can inadvertently
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>
140
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
143locally using C<no warnings> or C<$^W =0>. This includes all files that get
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>:
160
161=over 5
162
163=item 1.
164
165If none of the three command line flags (B<-w>, B<-W> or B<-X>) that
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.
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.
179
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.
185
186If a piece of code is under the control of the C<warnings> pragma,
187both the C<$^W> variable and the B<-w> flag will be ignored for the
188scope of the lexical warning.
189
190=item 5.
191
192The only way to override a lexical warnings setting is with the B<-W>
193or B<-X> command line flags.
194
195=back
196
197The combined effect of 3 & 4 is that it will allow code which uses
198the C<warnings> pragma to control the warning behavior of $^W-type
199code (using a C<local $^W=0>) if it really wants to, but not vice-versa.
200
201=head2 Category Hierarchy
202
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       |
210       +- chmod
211       |
212       +- closure
213       |
214       +- exiting
215       |
216       +- glob
217       |
218       +- io -----------+
219       |                |
220       |                +- closed
221       |                |
222       |                +- exec
223       |                |
224       |                +- newline
225       |                |
226       |                +- pipe
227       |                |
228       |                +- unopened
229       |
230       +- misc
231       |
232       +- numeric
233       |
234       +- once
235       |
236       +- overflow
237       |
238       +- pack
239       |
240       +- portable
241       |
242       +- recursion
243       |
244       +- redefine
245       |
246       +- regexp
247       |
248       +- severe -------+
249       |                |
250       |                +- debugging
251       |                |
252       |                +- inplace
253       |                |
254       |                +- internal
255       |                |
256       |                +- malloc
257       |
258       +- signal
259       |
260       +- substr
261       |
262       +- syntax -------+
263       |                |
264       |                +- ambiguous
265       |                |
266       |                +- bareword
267       |                |
268       |                +- deprecated
269       |                |
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       |
288       +- umask
289       |
290       +- uninitialized
291       |
292       +- unpack
293       |
294       +- untie
295       |
296       +- utf8
297       |
298       +- void
299       |
300       +- y2k
301
302Just like the "strict" pragma any of these categories can be combined
303
304    use warnings qw(void redefine) ;
305    no warnings qw(io syntax untie) ;
306
307Also like the "strict" pragma, if there is more than one instance of the
308C<warnings> pragma in a given scope the cumulative effect is additive.
309
310    use warnings qw(void) ; # only "void" warnings enabled
311    ...
312    use warnings qw(io) ;   # only "void" & "io" warnings enabled
313    ...
314    no warnings qw(void) ;  # only "io" warnings enabled
315
316To determine which category a specific warning has been assigned to see
317L<perldiag>.
318
319=head2 Fatal Warnings
320
321The presence of the word "FATAL" in the category list will escalate any
322warnings detected from the categories specified in the lexical scope
323into fatal errors. In the code below, the use of C<time>, C<length>
324and C<join> can all produce a C<"Useless use of xxx in void context">
325warning.
326
327    use warnings ;
328
329    time ;
330
331    {
332        use warnings FATAL => qw(void) ;
333        length "abc" ;
334    }
335
336    join "", 1,2,3 ;
337
338    print "done\n" ;     
339
340When run it produces this output
341
342    Useless use of time in void context at fatal line 3.
343    Useless use of length in void context at fatal line 7. 
344
345The scope where C<length> is used has escalated the C<void> warnings
346category into a fatal error, so the program terminates immediately it
347encounters the warning.
348
349
350=head2 Reporting Warnings from a Module
351
352The C<warnings> pragma provides a number of functions that are useful for
353module authors. These are used when you want to report a module-specific
354warning to a calling module has enabled warnings via the C<warnings>
355pragma.
356
357Consider the module C<MyMod::Abc> below.
358
359    package MyMod::Abc;
360
361    use warnings::register;
362
363    sub open {
364        my $path = shift ;
365        if (warnings::enabled() && $path !~ m#^/#) {
366            warnings::warn("changing relative path to /tmp/");
367            $path = "/tmp/$path" ;
368        }
369    }
370
371    1 ;
372
373The call to C<warnings::register> will create a new warnings category
374called "MyMod::abc", i.e. the new category name matches the current
375package name. The C<open> function in the module will display a warning
376message if it gets given a relative path as a parameter. This warnings
377will only be displayed if the code that uses C<MyMod::Abc> has actually
378enabled them with the C<warnings> pragma like below.
379
380    use MyMod::Abc;
381    use warnings 'MyMod::Abc';
382    ...
383    abc::open("../fred.txt");
384
385It is also possible to test whether the pre-defined warnings categories are
386set in the calling module with the C<warnings::enabled> function. Consider
387this snippet of code:
388
389    package MyMod::Abc;
390
391    sub open {
392        warnings::warnif("deprecated",
393                         "open is deprecated, use new instead") ;
394        new(@_) ;
395    }
396
397    sub new
398    ...
399    1 ;
400
401The function C<open> has been deprecated, so code has been included to
402display a warning message whenever the calling module has (at least) the
403"deprecated" warnings category enabled. Something like this, say.
404
405    use warnings 'deprecated';
406    use MyMod::Abc;
407    ...
408    MyMod::Abc::open($filename) ;
409
410Either the C<warnings::warn> or C<warnings::warnif> function should be
411used to actually display the warnings message. This is because they can
412make use of the feature that allows warnings to be escalated into fatal
413errors. So in this case
414
415    use MyMod::Abc;
416    use warnings FATAL => 'MyMod::Abc';
417    ...
418    MyMod::Abc::open('../fred.txt');
419
420the C<warnings::warnif> function will detect this and die after
421displaying the warning message.
422
423The three warnings functions, C<warnings::warn>, C<warnings::warnif>
424and C<warnings::enabled> can optionally take an object reference in place
425of a category name. In this case the functions will use the class name
426of the object as the warnings category.
427
428Consider this example:
429
430    package Original ;
431
432    no warnings ;
433    use warnings::register ;
434
435    sub new
436    {
437        my $class = shift ;
438        bless [], $class ;
439    }
440
441    sub check
442    {
443        my $self = shift ;
444        my $value = shift ;
445
446        if ($value % 2 && warnings::enabled($self))
447          { warnings::warn($self, "Odd numbers are unsafe") }
448    }
449
450    sub doit
451    {
452        my $self = shift ;
453        my $value = shift ;
454        $self->check($value) ;
455        # ...
456    }
457
458    1 ;
459
460    package Derived ;
461
462    use warnings::register ;
463    use Original ;
464    our @ISA = qw( Original ) ;
465    sub new
466    {
467        my $class = shift ;
468        bless [], $class ;
469    }
470
471
472    1 ;
473
474The code below makes use of both modules, but it only enables warnings from
475C<Derived>.
476
477    use Original ;
478    use Derived ;
479    use warnings 'Derived';
480    my $a = new Original ;
481    $a->doit(1) ;
482    my $b = new Derived ;
483    $a->doit(1) ;
484
485When this code is run only the C<Derived> object, C<$b>, will generate
486a warning.
487
488    Odd numbers are unsafe at main.pl line 7
489
490Notice also that the warning is reported at the line where the object is first
491used.
492
493=head1 TODO
494
495  perl5db.pl
496    The debugger saves and restores C<$^W> at runtime. I haven't checked
497    whether the debugger will still work with the lexical warnings
498    patch applied.
499
500  diagnostics.pm
501    I *think* I've got diagnostics to work with the lexical warnings
502    patch, but there were design decisions made in diagnostics to work
503    around the limitations of C<$^W>. Now that those limitations are gone,
504    the module should be revisited.
505
506  document calling the warnings::* functions from XS
507
508=head1 SEE ALSO
509
510L<warnings>, L<perldiag>.
511
512=head1 AUTHOR
513
514Paul Marquess
Note: See TracBrowser for help on using the repository browser.