This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
doubled words in pods (from Simon Cozens
[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 ;
0453d815
PM
33 my $a ;
34 my $b ;
35 {
4438c4b7 36 no warnings ;
0453d815
PM
37 $b = 2 if $a EQ 3 ;
38 }
39 $b = 1 if $a NE 3 ;
40
41The code in the enclosing block has warnings enabled, but the inner
42block has them disabled. In this case that means that the use of the C<EQ>
43operator won't trip a C<"Use of EQ is deprecated"> warning, but the use of
44C<NE> will produce a C<"Use of NE is deprecated"> warning.
45
46=head2 Default Warnings and Optional Warnings
47
48Before the introduction of lexical warnings, Perl had two classes of
49warnings: mandatory and optional.
50
51As its name suggests, if your code tripped a mandatory warning, you
52would get a warning whether you wanted it or not.
252aa082
JH
53For example, the code below would always produce an C<"isn't numeric">
54warning about the "2:".
0453d815 55
252aa082 56 my $a = "2:" + 3;
0453d815 57
0453d815
PM
58With the introduction of lexical warnings, mandatory warnings now become
59I<default> warnings. The difference is that although the previously
60mandatory warnings are still enabled by default, they can then be
61subsequently enabled or disabled with the lexical warning pragma. For
e476b1b5 62example, in the code below, an C<"isn't numeric"> warning will only
0453d815
PM
63be reported for the C<$a> variable.
64
252aa082 65 my $a = "2:" + 3;
4438c4b7 66 no warnings ;
252aa082 67 my $b = "2:" + 3;
0453d815
PM
68
69Note that neither the B<-w> flag or the C<$^W> can be used to
70disable/enable default warnings. They are still mandatory in this case.
71
72=head2 What's wrong with B<-w> and C<$^W>
73
74Although very useful, the big problem with using B<-w> on the command
75line to enable warnings is that it is all or nothing. Take the typical
76scenario when you are writing a Perl program. Parts of the code you
77will write yourself, but it's very likely that you will make use of
78pre-written Perl modules. If you use the B<-w> flag in this case, you
79end up enabling warnings in pieces of code that you haven't written.
80
81Similarly, using C<$^W> to either disable or enable blocks of code is
82fundamentally flawed. For a start, say you want to disable warnings in
83a 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
91When this code is run with the B<-w> flag, a warning will be produced
92for the C<$a> line -- C<"Reversed += operator">.
93
94The problem is that Perl has both compile-time and run-time warnings. To
95disable 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
103The other big problem with C<$^W> is that way you can inadvertently
104change the warning setting in unexpected places in your code. For example,
105when the code below is run (without the B<-w> flag), the second call
106to C<doit> will trip a C<"Use of uninitialized value"> warning, whereas
107the 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
121This is a side-effect of C<$^W> being dynamically scoped.
122
123Lexical warnings get around these limitations by allowing finer control
124over where warnings can or can't be tripped.
125
126=head2 Controlling Warnings from the Command Line
127
128There are three Command Line flags that can be used to control when
129warnings are (or aren't) produced:
130
131=over 5
132
133=item B<-w>
134
135This is the existing flag. If the lexical warnings pragma is B<not>
136used in any of you code, or any of the modules that you use, this flag
137will enable warnings everywhere. See L<Backward Compatibility> for
138details of how this flag interacts with lexical warnings.
139
140=item B<-W>
c47ff5f1 141
0453d815
PM
142If the B<-W> flag is used on the command line, it will enable all warnings
143throughout the program regardless of whether warnings were disabled
4438c4b7 144locally using C<no warnings> or C<$^W =0>. This includes all files that get
0453d815
PM
145included via C<use>, C<require> or C<do>.
146Think of it as the Perl equivalent of the "lint" command.
147
148=item B<-X>
149
150Does the exact opposite to the B<-W> flag, i.e. it disables all warnings.
151
152=back
153
154=head2 Backward Compatibility
155
156If you are used with working with a version of Perl prior to the
157introduction of lexically scoped warnings, or have code that uses both
158lexical warnings and C<$^W>, this section will describe how they interact.
159
160How Lexical Warnings interact with B<-w>/C<$^W>:
5a3e7812 161
0453d815
PM
162=over 5
163
164=item 1.
165
166If none of the three command line flags (B<-w>, B<-W> or B<-X>) that
e476b1b5
GS
167control warnings is used and neither C<$^W> or the C<warnings> pragma
168are used, then default warnings will be enabled and optional warnings
169disabled.
0453d815
PM
170This means that legacy code that doesn't attempt to control the warnings
171will work unchanged.
172
173=item 2.
174
175The B<-w> flag just sets the global C<$^W> variable as in 5.005 -- this
176means that any legacy code that currently relies on manipulating C<$^W>
177to control warning behavior will still work as is.
178
179=item 3.
c47ff5f1 180
0453d815
PM
181Apart from now being a boolean, the C<$^W> variable operates in exactly
182the same horrible uncontrolled global way, except that it cannot
183disable/enable default warnings.
184
185=item 4.
c47ff5f1 186
e476b1b5 187If a piece of code is under the control of the C<warnings> pragma,
0453d815
PM
188both the C<$^W> variable and the B<-w> flag will be ignored for the
189scope of the lexical warning.
190
191=item 5.
c47ff5f1 192
0453d815
PM
193The only way to override a lexical warnings setting is with the B<-W>
194or B<-X> command line flags.
195
196=back
197
106325ad 198The combined effect of 3 & 4 is that it will allow code which uses
e476b1b5 199the C<warnings> pragma to control the warning behavior of $^W-type
0453d815
PM
200code (using a C<local $^W=0>) if it really wants to, but not vice-versa.
201
0453d815 202=head2 Category Hierarchy
c47ff5f1 203
e476b1b5
GS
204A hierarchy of "categories" have been defined to allow groups of warnings
205to be enabled/disabled in isolation.
206
207The 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
0453d815 302
4438c4b7
JH
303Just 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
308Also like the "strict" pragma, if there is more than one instance of the
e476b1b5 309C<warnings> pragma in a given scope the cumulative effect is additive.
4438c4b7
JH
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
e476b1b5
GS
317To determine which category a specific warning has been assigned to see
318L<perldiag>.
0453d815
PM
319
320=head2 Fatal Warnings
c47ff5f1 321
0453d815 322The presence of the word "FATAL" in the category list will escalate any
e476b1b5
GS
323warnings detected from the categories specified in the lexical scope
324into fatal errors. In the code below, there are 3 places where a
325deprecated warning will be detected, the middle one will produce a
326fatal error.
4438c4b7
JH
327
328
329 use warnings ;
c47ff5f1 330
0453d815 331 $a = 1 if $a EQ $b ;
c47ff5f1 332
0453d815 333 {
4438c4b7 334 use warnings FATAL => qw(deprecated) ;
0453d815
PM
335 $a = 1 if $a EQ $b ;
336 }
c47ff5f1 337
0453d815 338 $a = 1 if $a EQ $b ;
0453d815 339
e476b1b5
GS
340=head2 Reporting Warnings from a Module
341
d3a7d8c7
GS
342The C<warnings> pragma provides a number of functions that are useful for
343module authors. These are used when you want to report a module-specific
344warning when the calling module has enabled warnings via the C<warnings>
345pragma.
e476b1b5 346
d3a7d8c7 347Consider the module C<MyMod::Abc> below.
e476b1b5 348
d3a7d8c7 349 package MyMod::Abc;
e476b1b5 350
d3a7d8c7
GS
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
363The call to C<warnings::register> will create a new warnings category
364called "MyMod::abc", i.e. the new category name matches the module
365name. The C<open> function in the module will display a warning message
366if it gets given a relative path as a parameter. This warnings will only
367be displayed if the code that uses C<MyMod::Abc> has actually enabled
368them with the C<warnings> pragma like below.
369
370 use MyMod::Abc;
371 use warnings 'MyMod::Abc';
372 ...
373 abc::open("../fred.txt");
374
375It is also possible to test whether the pre-defined warnings categories are
376set in the calling module with the C<warnings::enabled> function. Consider
377this snippet of code:
378
379 package MyMod::Abc;
380
381 sub open {
e476b1b5
GS
382 if (warnings::enabled("deprecated")) {
383 warnings::warn("deprecated",
d3a7d8c7 384 "open is deprecated, use new instead") ;
e476b1b5
GS
385 }
386 new(@_) ;
387 }
6bc102ca 388
e476b1b5
GS
389 sub new
390 ...
391 1 ;
392
393The function C<open> has been deprecated, so code has been included to
394display 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';
d3a7d8c7 398 use MyMod::Abc;
e476b1b5 399 ...
d3a7d8c7 400 MyMod::Abc::open($filename) ;
e476b1b5 401
d3a7d8c7
GS
402The C<warnings::warn> function should be used to actually display the
403warnings message. This is because they can make use of the feature that
404allows warnings to be escalated into fatal errors. So in this case
e476b1b5 405
d3a7d8c7
GS
406 use MyMod::Abc;
407 use warnings FATAL => 'MyMod::Abc';
e476b1b5 408 ...
d3a7d8c7 409 MyMod::Abc::open('../fred.txt');
e476b1b5 410
d3a7d8c7
GS
411the C<warnings::warn> function will detect this and die after
412displaying the warning message.
e476b1b5
GS
413
414=head1 TODO
c47ff5f1 415
0453d815
PM
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
0453d815
PM
427=head1 SEE ALSO
428
e476b1b5 429L<warnings>, L<perldiag>.
c47ff5f1 430
0453d815 431=head1 AUTHOR
c47ff5f1 432
0453d815 433Paul Marquess