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