Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | .\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13 |
2 | .\" | |
3 | .\" Standard preamble: | |
4 | .\" ======================================================================== | |
5 | .de Sh \" Subsection heading | |
6 | .br | |
7 | .if t .Sp | |
8 | .ne 5 | |
9 | .PP | |
10 | \fB\\$1\fR | |
11 | .PP | |
12 | .. | |
13 | .de Sp \" Vertical space (when we can't use .PP) | |
14 | .if t .sp .5v | |
15 | .if n .sp | |
16 | .. | |
17 | .de Vb \" Begin verbatim text | |
18 | .ft CW | |
19 | .nf | |
20 | .ne \\$1 | |
21 | .. | |
22 | .de Ve \" End verbatim text | |
23 | .ft R | |
24 | .fi | |
25 | .. | |
26 | .\" Set up some character translations and predefined strings. \*(-- will | |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a | |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to | |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' | |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. | |
32 | .tr \(*W-|\(bv\*(Tr | |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | |
34 | .ie n \{\ | |
35 | . ds -- \(*W- | |
36 | . ds PI pi | |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
39 | . ds L" "" | |
40 | . ds R" "" | |
41 | . ds C` "" | |
42 | . ds C' "" | |
43 | 'br\} | |
44 | .el\{\ | |
45 | . ds -- \|\(em\| | |
46 | . ds PI \(*p | |
47 | . ds L" `` | |
48 | . ds R" '' | |
49 | 'br\} | |
50 | .\" | |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for | |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the | |
54 | .\" output yourself in some meaningful fashion. | |
55 | .if \nF \{\ | |
56 | . de IX | |
57 | . tm Index:\\$1\t\\n%\t"\\$2" | |
58 | .. | |
59 | . nr % 0 | |
60 | . rr F | |
61 | .\} | |
62 | .\" | |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes | |
64 | .\" way too many mistakes in technical documents. | |
65 | .hy 0 | |
66 | .if n .na | |
67 | .\" | |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
70 | . \" fudge factors for nroff and troff | |
71 | .if n \{\ | |
72 | . ds #H 0 | |
73 | . ds #V .8m | |
74 | . ds #F .3m | |
75 | . ds #[ \f1 | |
76 | . ds #] \fP | |
77 | .\} | |
78 | .if t \{\ | |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | |
80 | . ds #V .6m | |
81 | . ds #F 0 | |
82 | . ds #[ \& | |
83 | . ds #] \& | |
84 | .\} | |
85 | . \" simple accents for nroff and troff | |
86 | .if n \{\ | |
87 | . ds ' \& | |
88 | . ds ` \& | |
89 | . ds ^ \& | |
90 | . ds , \& | |
91 | . ds ~ ~ | |
92 | . ds / | |
93 | .\} | |
94 | .if t \{\ | |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
101 | .\} | |
102 | . \" troff and (daisy-wheel) nroff accents | |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
110 | .ds ae a\h'-(\w'a'u*4/10)'e | |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
112 | . \" corrections for vroff | |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
115 | . \" for low resolution devices (crt and lpr) | |
116 | .if \n(.H>23 .if \n(.V>19 \ | |
117 | \{\ | |
118 | . ds : e | |
119 | . ds 8 ss | |
120 | . ds o a | |
121 | . ds d- d\h'-1'\(ga | |
122 | . ds D- D\h'-1'\(hy | |
123 | . ds th \o'bp' | |
124 | . ds Th \o'LP' | |
125 | . ds ae ae | |
126 | . ds Ae AE | |
127 | .\} | |
128 | .rm #[ #] #H #V #F C | |
129 | .\" ======================================================================== | |
130 | .\" | |
131 | .IX Title "PERLLEXWARN 1" | |
132 | .TH PERLLEXWARN 1 "2002-06-08" "perl v5.8.0" "Perl Programmers Reference Guide" | |
133 | .SH "NAME" | |
134 | perllexwarn \- Perl Lexical Warnings | |
135 | .SH "DESCRIPTION" | |
136 | .IX Header "DESCRIPTION" | |
137 | The \f(CW\*(C`use warnings\*(C'\fR pragma is a replacement for both the command line | |
138 | flag \fB\-w\fR and the equivalent Perl variable, \f(CW$^W\fR. | |
139 | .PP | |
140 | The pragma works just like the existing \*(L"strict\*(R" pragma. | |
141 | This means that the scope of the warning pragma is limited to the | |
142 | enclosing block. It also means that the pragma setting will not | |
143 | leak across files (via \f(CW\*(C`use\*(C'\fR, \f(CW\*(C`require\*(C'\fR or \f(CW\*(C`do\*(C'\fR). This allows | |
144 | authors to independently define the degree of warning checks that will | |
145 | be applied to their module. | |
146 | .PP | |
147 | By default, optional warnings are disabled, so any legacy code that | |
148 | doesn't attempt to control the warnings will work unchanged. | |
149 | .PP | |
150 | All warnings are enabled in a block by either of these: | |
151 | .PP | |
152 | .Vb 2 | |
153 | \& use warnings ; | |
154 | \& use warnings 'all' ; | |
155 | .Ve | |
156 | .PP | |
157 | Similarly all warnings are disabled in a block by either of these: | |
158 | .PP | |
159 | .Vb 2 | |
160 | \& no warnings ; | |
161 | \& no warnings 'all' ; | |
162 | .Ve | |
163 | .PP | |
164 | For example, consider the code below: | |
165 | .PP | |
166 | .Vb 7 | |
167 | \& use warnings ; | |
168 | \& my @a ; | |
169 | \& { | |
170 | \& no warnings ; | |
171 | \& my $b = @a[0] ; | |
172 | \& } | |
173 | \& my $c = @a[0]; | |
174 | .Ve | |
175 | .PP | |
176 | The code in the enclosing block has warnings enabled, but the inner | |
177 | block has them disabled. In this case that means the assignment to the | |
178 | scalar \f(CW$c\fR will trip the \f(CW"Scalar value @a[0] better written as $a[0]"\fR | |
179 | warning, but the assignment to the scalar \f(CW$b\fR will not. | |
180 | .Sh "Default Warnings and Optional Warnings" | |
181 | .IX Subsection "Default Warnings and Optional Warnings" | |
182 | Before the introduction of lexical warnings, Perl had two classes of | |
183 | warnings: mandatory and optional. | |
184 | .PP | |
185 | As its name suggests, if your code tripped a mandatory warning, you | |
186 | would get a warning whether you wanted it or not. | |
187 | For example, the code below would always produce an \f(CW"isn't numeric"\fR | |
188 | warning about the \*(L"2:\*(R". | |
189 | .PP | |
190 | .Vb 1 | |
191 | \& my $a = "2:" + 3; | |
192 | .Ve | |
193 | .PP | |
194 | With the introduction of lexical warnings, mandatory warnings now become | |
195 | \&\fIdefault\fR warnings. The difference is that although the previously | |
196 | mandatory warnings are still enabled by default, they can then be | |
197 | subsequently enabled or disabled with the lexical warning pragma. For | |
198 | example, in the code below, an \f(CW"isn't numeric"\fR warning will only | |
199 | be reported for the \f(CW$a\fR variable. | |
200 | .PP | |
201 | .Vb 3 | |
202 | \& my $a = "2:" + 3; | |
203 | \& no warnings ; | |
204 | \& my $b = "2:" + 3; | |
205 | .Ve | |
206 | .PP | |
207 | Note that neither the \fB\-w\fR flag or the \f(CW$^W\fR can be used to | |
208 | disable/enable default warnings. They are still mandatory in this case. | |
209 | .ie n .Sh "What's wrong with \fB\-w\fP and $^W" | |
210 | .el .Sh "What's wrong with \fB\-w\fP and \f(CW$^W\fP" | |
211 | .IX Subsection "What's wrong with -w and $^W" | |
212 | Although very useful, the big problem with using \fB\-w\fR on the command | |
213 | line to enable warnings is that it is all or nothing. Take the typical | |
214 | scenario when you are writing a Perl program. Parts of the code you | |
215 | will write yourself, but it's very likely that you will make use of | |
216 | pre-written Perl modules. If you use the \fB\-w\fR flag in this case, you | |
217 | end up enabling warnings in pieces of code that you haven't written. | |
218 | .PP | |
219 | Similarly, using \f(CW$^W\fR to either disable or enable blocks of code is | |
220 | fundamentally flawed. For a start, say you want to disable warnings in | |
221 | a block of code. You might expect this to be enough to do the trick: | |
222 | .PP | |
223 | .Vb 5 | |
224 | \& { | |
225 | \& local ($^W) = 0 ; | |
226 | \& my $a =+ 2 ; | |
227 | \& my $b ; chop $b ; | |
228 | \& } | |
229 | .Ve | |
230 | .PP | |
231 | When this code is run with the \fB\-w\fR flag, a warning will be produced | |
232 | for the \f(CW$a\fR line \*(-- \f(CW"Reversed += operator"\fR. | |
233 | .PP | |
234 | The problem is that Perl has both compile-time and run-time warnings. To | |
235 | disable compile-time warnings you need to rewrite the code like this: | |
236 | .PP | |
237 | .Vb 5 | |
238 | \& { | |
239 | \& BEGIN { $^W = 0 } | |
240 | \& my $a =+ 2 ; | |
241 | \& my $b ; chop $b ; | |
242 | \& } | |
243 | .Ve | |
244 | .PP | |
245 | The other big problem with \f(CW$^W\fR is the way you can inadvertently | |
246 | change the warning setting in unexpected places in your code. For example, | |
247 | when the code below is run (without the \fB\-w\fR flag), the second call | |
248 | to \f(CW\*(C`doit\*(C'\fR will trip a \f(CW"Use of uninitialized value"\fR warning, whereas | |
249 | the first will not. | |
250 | .PP | |
251 | .Vb 4 | |
252 | \& sub doit | |
253 | \& { | |
254 | \& my $b ; chop $b ; | |
255 | \& } | |
256 | .Ve | |
257 | .PP | |
258 | .Vb 1 | |
259 | \& doit() ; | |
260 | .Ve | |
261 | .PP | |
262 | .Vb 4 | |
263 | \& { | |
264 | \& local ($^W) = 1 ; | |
265 | \& doit() | |
266 | \& } | |
267 | .Ve | |
268 | .PP | |
269 | This is a side-effect of \f(CW$^W\fR being dynamically scoped. | |
270 | .PP | |
271 | Lexical warnings get around these limitations by allowing finer control | |
272 | over where warnings can or can't be tripped. | |
273 | .Sh "Controlling Warnings from the Command Line" | |
274 | .IX Subsection "Controlling Warnings from the Command Line" | |
275 | There are three Command Line flags that can be used to control when | |
276 | warnings are (or aren't) produced: | |
277 | .IP "\fB\-w\fR" 5 | |
278 | .IX Item "-w" | |
279 | This is the existing flag. If the lexical warnings pragma is \fBnot\fR | |
280 | used in any of you code, or any of the modules that you use, this flag | |
281 | will enable warnings everywhere. See \*(L"Backward Compatibility\*(R" for | |
282 | details of how this flag interacts with lexical warnings. | |
283 | .IP "\fB\-W\fR" 5 | |
284 | .IX Item "-W" | |
285 | If the \fB\-W\fR flag is used on the command line, it will enable all warnings | |
286 | throughout the program regardless of whether warnings were disabled | |
287 | locally using \f(CW\*(C`no warnings\*(C'\fR or \f(CW\*(C`$^W =0\*(C'\fR. This includes all files that get | |
288 | included via \f(CW\*(C`use\*(C'\fR, \f(CW\*(C`require\*(C'\fR or \f(CW\*(C`do\*(C'\fR. | |
289 | Think of it as the Perl equivalent of the \*(L"lint\*(R" command. | |
290 | .IP "\fB\-X\fR" 5 | |
291 | .IX Item "-X" | |
292 | Does the exact opposite to the \fB\-W\fR flag, i.e. it disables all warnings. | |
293 | .Sh "Backward Compatibility" | |
294 | .IX Subsection "Backward Compatibility" | |
295 | If you are used with working with a version of Perl prior to the | |
296 | introduction of lexically scoped warnings, or have code that uses both | |
297 | lexical warnings and \f(CW$^W\fR, this section will describe how they interact. | |
298 | .PP | |
299 | How Lexical Warnings interact with \fB\-w\fR/\f(CW$^W\fR: | |
300 | .IP "1." 5 | |
301 | If none of the three command line flags (\fB\-w\fR, \fB\-W\fR or \fB\-X\fR) that | |
302 | control warnings is used and neither \f(CW$^W\fR or the \f(CW\*(C`warnings\*(C'\fR pragma | |
303 | are used, then default warnings will be enabled and optional warnings | |
304 | disabled. | |
305 | This means that legacy code that doesn't attempt to control the warnings | |
306 | will work unchanged. | |
307 | .IP "2." 5 | |
308 | The \fB\-w\fR flag just sets the global \f(CW$^W\fR variable as in 5.005 \*(-- this | |
309 | means that any legacy code that currently relies on manipulating \f(CW$^W\fR | |
310 | to control warning behavior will still work as is. | |
311 | .IP "3." 5 | |
312 | Apart from now being a boolean, the \f(CW$^W\fR variable operates in exactly | |
313 | the same horrible uncontrolled global way, except that it cannot | |
314 | disable/enable default warnings. | |
315 | .IP "4." 5 | |
316 | If a piece of code is under the control of the \f(CW\*(C`warnings\*(C'\fR pragma, | |
317 | both the \f(CW$^W\fR variable and the \fB\-w\fR flag will be ignored for the | |
318 | scope of the lexical warning. | |
319 | .IP "5." 5 | |
320 | The only way to override a lexical warnings setting is with the \fB\-W\fR | |
321 | or \fB\-X\fR command line flags. | |
322 | .PP | |
323 | The combined effect of 3 & 4 is that it will allow code which uses | |
324 | the \f(CW\*(C`warnings\*(C'\fR pragma to control the warning behavior of $^W\-type | |
325 | code (using a \f(CW\*(C`local $^W=0\*(C'\fR) if it really wants to, but not vice\-versa. | |
326 | .Sh "Category Hierarchy" | |
327 | .IX Subsection "Category Hierarchy" | |
328 | A hierarchy of \*(L"categories\*(R" have been defined to allow groups of warnings | |
329 | to be enabled/disabled in isolation. | |
330 | .PP | |
331 | The current hierarchy is: | |
332 | .PP | |
333 | .Vb 93 | |
334 | \& all -+ | |
335 | \& | | |
336 | \& +- closure | |
337 | \& | | |
338 | \& +- deprecated | |
339 | \& | | |
340 | \& +- exiting | |
341 | \& | | |
342 | \& +- glob | |
343 | \& | | |
344 | \& +- io -----------+ | |
345 | \& | | | |
346 | \& | +- closed | |
347 | \& | | | |
348 | \& | +- exec | |
349 | \& | | | |
350 | \& | +- layer | |
351 | \& | | | |
352 | \& | +- newline | |
353 | \& | | | |
354 | \& | +- pipe | |
355 | \& | | | |
356 | \& | +- unopened | |
357 | \& | | |
358 | \& +- misc | |
359 | \& | | |
360 | \& +- numeric | |
361 | \& | | |
362 | \& +- once | |
363 | \& | | |
364 | \& +- overflow | |
365 | \& | | |
366 | \& +- pack | |
367 | \& | | |
368 | \& +- portable | |
369 | \& | | |
370 | \& +- recursion | |
371 | \& | | |
372 | \& +- redefine | |
373 | \& | | |
374 | \& +- regexp | |
375 | \& | | |
376 | \& +- severe -------+ | |
377 | \& | | | |
378 | \& | +- debugging | |
379 | \& | | | |
380 | \& | +- inplace | |
381 | \& | | | |
382 | \& | +- internal | |
383 | \& | | | |
384 | \& | +- malloc | |
385 | \& | | |
386 | \& +- signal | |
387 | \& | | |
388 | \& +- substr | |
389 | \& | | |
390 | \& +- syntax -------+ | |
391 | \& | | | |
392 | \& | +- ambiguous | |
393 | \& | | | |
394 | \& | +- bareword | |
395 | \& | | | |
396 | \& | +- digit | |
397 | \& | | | |
398 | \& | +- parenthesis | |
399 | \& | | | |
400 | \& | +- precedence | |
401 | \& | | | |
402 | \& | +- printf | |
403 | \& | | | |
404 | \& | +- prototype | |
405 | \& | | | |
406 | \& | +- qw | |
407 | \& | | | |
408 | \& | +- reserved | |
409 | \& | | | |
410 | \& | +- semicolon | |
411 | \& | | |
412 | \& +- taint | |
413 | \& | | |
414 | \& +- threads | |
415 | \& | | |
416 | \& +- uninitialized | |
417 | \& | | |
418 | \& +- unpack | |
419 | \& | | |
420 | \& +- untie | |
421 | \& | | |
422 | \& +- utf8 | |
423 | \& | | |
424 | \& +- void | |
425 | \& | | |
426 | \& +- y2k | |
427 | .Ve | |
428 | .PP | |
429 | Just like the \*(L"strict\*(R" pragma any of these categories can be combined | |
430 | .PP | |
431 | .Vb 2 | |
432 | \& use warnings qw(void redefine) ; | |
433 | \& no warnings qw(io syntax untie) ; | |
434 | .Ve | |
435 | .PP | |
436 | Also like the \*(L"strict\*(R" pragma, if there is more than one instance of the | |
437 | \&\f(CW\*(C`warnings\*(C'\fR pragma in a given scope the cumulative effect is additive. | |
438 | .PP | |
439 | .Vb 5 | |
440 | \& use warnings qw(void) ; # only "void" warnings enabled | |
441 | \& ... | |
442 | \& use warnings qw(io) ; # only "void" & "io" warnings enabled | |
443 | \& ... | |
444 | \& no warnings qw(void) ; # only "io" warnings enabled | |
445 | .Ve | |
446 | .PP | |
447 | To determine which category a specific warning has been assigned to see | |
448 | perldiag. | |
449 | .PP | |
450 | Note: In Perl 5.6.1, the lexical warnings category \*(L"deprecated\*(R" was a | |
451 | sub-category of the \*(L"syntax\*(R" category. It is now a top-level category | |
452 | in its own right. | |
453 | .Sh "Fatal Warnings" | |
454 | .IX Subsection "Fatal Warnings" | |
455 | The presence of the word \*(L"\s-1FATAL\s0\*(R" in the category list will escalate any | |
456 | warnings detected from the categories specified in the lexical scope | |
457 | into fatal errors. In the code below, the use of \f(CW\*(C`time\*(C'\fR, \f(CW\*(C`length\*(C'\fR | |
458 | and \f(CW\*(C`join\*(C'\fR can all produce a \f(CW"Useless use of xxx in void context"\fR | |
459 | warning. | |
460 | .PP | |
461 | .Vb 1 | |
462 | \& use warnings ; | |
463 | .Ve | |
464 | .PP | |
465 | .Vb 1 | |
466 | \& time ; | |
467 | .Ve | |
468 | .PP | |
469 | .Vb 4 | |
470 | \& { | |
471 | \& use warnings FATAL => qw(void) ; | |
472 | \& length "abc" ; | |
473 | \& } | |
474 | .Ve | |
475 | .PP | |
476 | .Vb 1 | |
477 | \& join "", 1,2,3 ; | |
478 | .Ve | |
479 | .PP | |
480 | .Vb 1 | |
481 | \& print "done\en" ; | |
482 | .Ve | |
483 | .PP | |
484 | When run it produces this output | |
485 | .PP | |
486 | .Vb 2 | |
487 | \& Useless use of time in void context at fatal line 3. | |
488 | \& Useless use of length in void context at fatal line 7. | |
489 | .Ve | |
490 | .PP | |
491 | The scope where \f(CW\*(C`length\*(C'\fR is used has escalated the \f(CW\*(C`void\*(C'\fR warnings | |
492 | category into a fatal error, so the program terminates immediately it | |
493 | encounters the warning. | |
494 | .PP | |
495 | To explicitly turn off a \*(L"\s-1FATAL\s0\*(R" warning you just disable the warning | |
496 | it is associated with. So, for example, to disable the \*(L"void\*(R" warning | |
497 | in the example above, either of these will do the trick: | |
498 | .PP | |
499 | .Vb 2 | |
500 | \& no warnings qw(void); | |
501 | \& no warnings FATAL => qw(void); | |
502 | .Ve | |
503 | .PP | |
504 | If you want to downgrade a warning that has been escalated into a fatal | |
505 | error back to a normal warning, you can use the \*(L"\s-1NONFATAL\s0\*(R" keyword. For | |
506 | example, the code below will promote all warnings into fatal errors, | |
507 | except for those in the \*(L"syntax\*(R" category. | |
508 | .PP | |
509 | .Vb 1 | |
510 | \& use warnings FATAL => 'all', NONFATAL => 'syntax'; | |
511 | .Ve | |
512 | .Sh "Reporting Warnings from a Module" | |
513 | .IX Subsection "Reporting Warnings from a Module" | |
514 | The \f(CW\*(C`warnings\*(C'\fR pragma provides a number of functions that are useful for | |
515 | module authors. These are used when you want to report a module-specific | |
516 | warning to a calling module has enabled warnings via the \f(CW\*(C`warnings\*(C'\fR | |
517 | pragma. | |
518 | .PP | |
519 | Consider the module \f(CW\*(C`MyMod::Abc\*(C'\fR below. | |
520 | .PP | |
521 | .Vb 1 | |
522 | \& package MyMod::Abc; | |
523 | .Ve | |
524 | .PP | |
525 | .Vb 1 | |
526 | \& use warnings::register; | |
527 | .Ve | |
528 | .PP | |
529 | .Vb 8 | |
530 | \& sub open { | |
531 | \& my $path = shift ; | |
532 | \& if ($path !~ m#^/#) { | |
533 | \& warnings::warn("changing relative path to /tmp/") | |
534 | \& if warnings::enabled(); | |
535 | \& $path = "/tmp/$path" ; | |
536 | \& } | |
537 | \& } | |
538 | .Ve | |
539 | .PP | |
540 | .Vb 1 | |
541 | \& 1 ; | |
542 | .Ve | |
543 | .PP | |
544 | The call to \f(CW\*(C`warnings::register\*(C'\fR will create a new warnings category | |
545 | called \*(L"MyMod::abc\*(R", i.e. the new category name matches the current | |
546 | package name. The \f(CW\*(C`open\*(C'\fR function in the module will display a warning | |
547 | message if it gets given a relative path as a parameter. This warnings | |
548 | will only be displayed if the code that uses \f(CW\*(C`MyMod::Abc\*(C'\fR has actually | |
549 | enabled them with the \f(CW\*(C`warnings\*(C'\fR pragma like below. | |
550 | .PP | |
551 | .Vb 4 | |
552 | \& use MyMod::Abc; | |
553 | \& use warnings 'MyMod::Abc'; | |
554 | \& ... | |
555 | \& abc::open("../fred.txt"); | |
556 | .Ve | |
557 | .PP | |
558 | It is also possible to test whether the pre-defined warnings categories are | |
559 | set in the calling module with the \f(CW\*(C`warnings::enabled\*(C'\fR function. Consider | |
560 | this snippet of code: | |
561 | .PP | |
562 | .Vb 1 | |
563 | \& package MyMod::Abc; | |
564 | .Ve | |
565 | .PP | |
566 | .Vb 5 | |
567 | \& sub open { | |
568 | \& warnings::warnif("deprecated", | |
569 | \& "open is deprecated, use new instead") ; | |
570 | \& new(@_) ; | |
571 | \& } | |
572 | .Ve | |
573 | .PP | |
574 | .Vb 3 | |
575 | \& sub new | |
576 | \& ... | |
577 | \& 1 ; | |
578 | .Ve | |
579 | .PP | |
580 | The function \f(CW\*(C`open\*(C'\fR has been deprecated, so code has been included to | |
581 | display a warning message whenever the calling module has (at least) the | |
582 | \&\*(L"deprecated\*(R" warnings category enabled. Something like this, say. | |
583 | .PP | |
584 | .Vb 4 | |
585 | \& use warnings 'deprecated'; | |
586 | \& use MyMod::Abc; | |
587 | \& ... | |
588 | \& MyMod::Abc::open($filename) ; | |
589 | .Ve | |
590 | .PP | |
591 | Either the \f(CW\*(C`warnings::warn\*(C'\fR or \f(CW\*(C`warnings::warnif\*(C'\fR function should be | |
592 | used to actually display the warnings message. This is because they can | |
593 | make use of the feature that allows warnings to be escalated into fatal | |
594 | errors. So in this case | |
595 | .PP | |
596 | .Vb 4 | |
597 | \& use MyMod::Abc; | |
598 | \& use warnings FATAL => 'MyMod::Abc'; | |
599 | \& ... | |
600 | \& MyMod::Abc::open('../fred.txt'); | |
601 | .Ve | |
602 | .PP | |
603 | the \f(CW\*(C`warnings::warnif\*(C'\fR function will detect this and die after | |
604 | displaying the warning message. | |
605 | .PP | |
606 | The three warnings functions, \f(CW\*(C`warnings::warn\*(C'\fR, \f(CW\*(C`warnings::warnif\*(C'\fR | |
607 | and \f(CW\*(C`warnings::enabled\*(C'\fR can optionally take an object reference in place | |
608 | of a category name. In this case the functions will use the class name | |
609 | of the object as the warnings category. | |
610 | .PP | |
611 | Consider this example: | |
612 | .PP | |
613 | .Vb 1 | |
614 | \& package Original ; | |
615 | .Ve | |
616 | .PP | |
617 | .Vb 2 | |
618 | \& no warnings ; | |
619 | \& use warnings::register ; | |
620 | .Ve | |
621 | .PP | |
622 | .Vb 5 | |
623 | \& sub new | |
624 | \& { | |
625 | \& my $class = shift ; | |
626 | \& bless [], $class ; | |
627 | \& } | |
628 | .Ve | |
629 | .PP | |
630 | .Vb 4 | |
631 | \& sub check | |
632 | \& { | |
633 | \& my $self = shift ; | |
634 | \& my $value = shift ; | |
635 | .Ve | |
636 | .PP | |
637 | .Vb 3 | |
638 | \& if ($value % 2 && warnings::enabled($self)) | |
639 | \& { warnings::warn($self, "Odd numbers are unsafe") } | |
640 | \& } | |
641 | .Ve | |
642 | .PP | |
643 | .Vb 7 | |
644 | \& sub doit | |
645 | \& { | |
646 | \& my $self = shift ; | |
647 | \& my $value = shift ; | |
648 | \& $self->check($value) ; | |
649 | \& # ... | |
650 | \& } | |
651 | .Ve | |
652 | .PP | |
653 | .Vb 1 | |
654 | \& 1 ; | |
655 | .Ve | |
656 | .PP | |
657 | .Vb 1 | |
658 | \& package Derived ; | |
659 | .Ve | |
660 | .PP | |
661 | .Vb 8 | |
662 | \& use warnings::register ; | |
663 | \& use Original ; | |
664 | \& our @ISA = qw( Original ) ; | |
665 | \& sub new | |
666 | \& { | |
667 | \& my $class = shift ; | |
668 | \& bless [], $class ; | |
669 | \& } | |
670 | .Ve | |
671 | .PP | |
672 | .Vb 1 | |
673 | \& 1 ; | |
674 | .Ve | |
675 | .PP | |
676 | The code below makes use of both modules, but it only enables warnings from | |
677 | \&\f(CW\*(C`Derived\*(C'\fR. | |
678 | .PP | |
679 | .Vb 7 | |
680 | \& use Original ; | |
681 | \& use Derived ; | |
682 | \& use warnings 'Derived'; | |
683 | \& my $a = new Original ; | |
684 | \& $a->doit(1) ; | |
685 | \& my $b = new Derived ; | |
686 | \& $a->doit(1) ; | |
687 | .Ve | |
688 | .PP | |
689 | When this code is run only the \f(CW\*(C`Derived\*(C'\fR object, \f(CW$b\fR, will generate | |
690 | a warning. | |
691 | .PP | |
692 | .Vb 1 | |
693 | \& Odd numbers are unsafe at main.pl line 7 | |
694 | .Ve | |
695 | .PP | |
696 | Notice also that the warning is reported at the line where the object is first | |
697 | used. | |
698 | .SH "TODO" | |
699 | .IX Header "TODO" | |
700 | .Vb 4 | |
701 | \& perl5db.pl | |
702 | \& The debugger saves and restores C<$^W> at runtime. I haven't checked | |
703 | \& whether the debugger will still work with the lexical warnings | |
704 | \& patch applied. | |
705 | .Ve | |
706 | .PP | |
707 | .Vb 5 | |
708 | \& diagnostics.pm | |
709 | \& I *think* I've got diagnostics to work with the lexical warnings | |
710 | \& patch, but there were design decisions made in diagnostics to work | |
711 | \& around the limitations of C<$^W>. Now that those limitations are gone, | |
712 | \& the module should be revisited. | |
713 | .Ve | |
714 | .PP | |
715 | .Vb 1 | |
716 | \& document calling the warnings::* functions from XS | |
717 | .Ve | |
718 | .SH "SEE ALSO" | |
719 | .IX Header "SEE ALSO" | |
720 | warnings, perldiag. | |
721 | .SH "AUTHOR" | |
722 | .IX Header "AUTHOR" | |
723 | Paul Marquess |