Debian Codegraph @

upstream/mageia-cauldron/man3pm/warnings.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "warnings 3pm"
61 .TH warnings 3pm 2025-06-24 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 warnings \- Perl pragma to control optional warnings
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 2
71 \& use warnings;
72 \& no warnings;
73 \&
74 \& # Standard warnings are enabled by use v5.35 or above
75 \& use v5.35;
76 \&
77 \& use warnings "all";
78 \& no warnings "uninitialized";
79 \&
80 \& # or equivalent to those last two ...
81 \& use warnings qw(all \-uninitialized);
82 \&
83 \& use warnings::register;
84 \& if (warnings::enabled()) {
85 \& warnings::warn("some warning");
86 \& }
87 \&
88 \& if (warnings::enabled("void")) {
89 \& warnings::warn("void", "some warning");
90 \& }
91 \&
92 \& if (warnings::enabled($object)) {
93 \& warnings::warn($object, "some warning");
94 \& }
95 \&
96 \& warnings::warnif("some warning");
97 \& warnings::warnif("void", "some warning");
98 \& warnings::warnif($object, "some warning");
99 .Ve
100 .SH DESCRIPTION
101 .IX Header "DESCRIPTION"
102 The \f(CW\*(C`warnings\*(C'\fR pragma gives control over which warnings are enabled in
103 which parts of a Perl program. It\*(Aqs a more flexible alternative for
104 both the command line flag \fB\-w\fR and the equivalent Perl variable,
105 \&\f(CW$^W\fR.
106 .PP
107 This pragma works just like the \f(CW\*(C`strict\*(C'\fR pragma.
108 This means that the scope of the warning pragma is limited to the
109 enclosing block. It also means that the pragma setting will not
110 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
111 authors to independently define the degree of warning checks that will
112 be applied to their module.
113 .PP
114 By default, optional warnings are disabled, so any legacy code that
115 doesn\*(Aqt attempt to control the warnings will work unchanged.
116 .PP
117 All warnings are enabled in a block by either of these:
118 .PP
119 .Vb 2
120 \& use warnings;
121 \& use warnings \*(Aqall\*(Aq;
122 .Ve
123 .PP
124 Similarly all warnings are disabled in a block by either of these:
125 .PP
126 .Vb 2
127 \& no warnings;
128 \& no warnings \*(Aqall\*(Aq;
129 .Ve
130 .PP
131 For example, consider the code below:
132 .PP
133 .Vb 7
134 \& use warnings;
135 \& my @x;
136 \& {
137 \& no warnings;
138 \& my $y = @x[0];
139 \& }
140 \& my $z = @x[0];
141 .Ve
142 .PP
143 The code in the enclosing block has warnings enabled, but the inner
144 block has them disabled. In this case that means the assignment to the
145 scalar \f(CW$z\fR will trip the \f(CW"Scalar value @x[0] better written as $x[0]"\fR
146 warning, but the assignment to the scalar \f(CW$y\fR will not.
147 .PP
148 All warnings are enabled automatically within the scope of
149 a \f(CW\*(C`use v5.35\*(C'\fR (or higher) declaration.
150 .SS "Default Warnings and Optional Warnings"
151 .IX Subsection "Default Warnings and Optional Warnings"
152 Before the introduction of lexical warnings, Perl had two classes of
153 warnings: mandatory and optional.
154 .PP
155 As its name suggests, if your code tripped a mandatory warning, you
156 would get a warning whether you wanted it or not.
157 For example, the code below would always produce an \f(CW"isn\*(Aqt numeric"\fR
158 warning about the "2:".
159 .PP
160 .Vb 1
161 \& my $x = "2:" + 3;
162 .Ve
163 .PP
164 With the introduction of lexical warnings, mandatory warnings now become
165 \&\fIdefault\fR warnings. The difference is that although the previously
166 mandatory warnings are still enabled by default, they can then be
167 subsequently enabled or disabled with the lexical warning pragma. For
168 example, in the code below, an \f(CW"isn\*(Aqt numeric"\fR warning will only
169 be reported for the \f(CW$x\fR variable.
170 .PP
171 .Vb 3
172 \& my $x = "2:" + 3;
173 \& no warnings;
174 \& my $y = "2:" + 3;
175 .Ve
176 .PP
177 Note that neither the \fB\-w\fR flag or the \f(CW$^W\fR can be used to
178 disable/enable default warnings. They are still mandatory in this case.
179 .SS """Negative warnings"""
180 .IX Subsection """Negative warnings"""
181 As a convenience, you can (as of Perl 5.34) pass arguments to the
182 \&\f(CWimport()\fR method both positively and negatively. Negative warnings
183 are those with a \f(CW\*(C`\-\*(C'\fR sign prepended to their names; positive warnings
184 are anything else. This lets you turn on some warnings and turn off
185 others in one command. So, assuming that you\*(Aqve already turned on a
186 bunch of warnings but want to tweak them a bit in some block, you can
187 do this:
188 .PP
189 .Vb 4
190 \& {
191 \& use warnings qw(uninitialized \-redefine);
192 \& ...
193 \& }
194 .Ve
195 .PP
196 which is equivalent to:
197 .PP
198 .Vb 5
199 \& {
200 \& use warnings qw(uninitialized);
201 \& no warnings qw(redefine);
202 \& ...
203 \& }
204 .Ve
205 .PP
206 The argument list is processed in the order you specify. So, for example, if you
207 don\*(Aqt want to be warned about use of experimental features, except for \f(CW\*(C`somefeature\*(C'\fR
208 that you really dislike, you can say this:
209 .PP
210 .Vb 1
211 \& use warnings qw(all \-experimental experimental::somefeature);
212 .Ve
213 .PP
214 which is equivalent to:
215 .PP
216 .Vb 3
217 \& use warnings \*(Aqall\*(Aq;
218 \& no warnings \*(Aqexperimental\*(Aq;
219 \& use warnings \*(Aqexperimental::somefeature\*(Aq;
220 .Ve
221 .PP
222 As experimental features become regular features of Perl,
223 the corresponding warnings are not printed anymore.
224 They also stop being listed in the "Category Hierarchy" below.
225 .PP
226 It is still possible to request turning on or off these warnings,
227 but doing so has no effect.
228 .ie n .SS "What\*(Aqs wrong with \fB\-w\fP and $^W"
229 .el .SS "What\*(Aqs wrong with \fB\-w\fP and \f(CW$^W\fP"
230 .IX Subsection "What's wrong with -w and $^W"
231 Although very useful, the big problem with using \fB\-w\fR on the command
232 line to enable warnings is that it is all or nothing. Take the typical
233 scenario when you are writing a Perl program. Parts of the code you
234 will write yourself, but it\*(Aqs very likely that you will make use of
235 pre\-written Perl modules. If you use the \fB\-w\fR flag in this case, you
236 end up enabling warnings in pieces of code that you haven\*(Aqt written.
237 .PP
238 Similarly, using \f(CW$^W\fR to either disable or enable blocks of code is
239 fundamentally flawed. For a start, say you want to disable warnings in
240 a block of code. You might expect this to be enough to do the trick:
241 .PP
242 .Vb 5
243 \& {
244 \& local ($^W) = 0;
245 \& my $x =+ 2;
246 \& my $y; chop $y;
247 \& }
248 .Ve
249 .PP
250 When this code is run with the \fB\-w\fR flag, a warning will be produced
251 for the \f(CW$x\fR line: \f(CW"Reversed += operator"\fR.
252 .PP
253 The problem is that Perl has both compile\-time and run\-time warnings. To
254 disable compile\-time warnings you need to rewrite the code like this:
255 .PP
256 .Vb 5
257 \& {
258 \& BEGIN { $^W = 0 }
259 \& my $x =+ 2;
260 \& my $y; chop $y;
261 \& }
262 .Ve
263 .PP
264 And note that unlike the first example, this will permanently set \f(CW$^W\fR
265 since it cannot both run during compile\-time and be localized to a
266 run\-time block.
267 .PP
268 The other big problem with \f(CW$^W\fR is the way you can inadvertently
269 change the warning setting in unexpected places in your code. For example,
270 when the code below is run (without the \fB\-w\fR flag), the second call
271 to \f(CW\*(C`doit\*(C'\fR will trip a \f(CW"Use of uninitialized value"\fR warning, whereas
272 the first will not.
273 .PP
274 .Vb 4
275 \& sub doit
276 \& {
277 \& my $y; chop $y;
278 \& }
279 \&
280 \& doit();
281 \&
282 \& {
283 \& local ($^W) = 1;
284 \& doit()
285 \& }
286 .Ve
287 .PP
288 This is a side\-effect of \f(CW$^W\fR being dynamically scoped.
289 .PP
290 Lexical warnings get around these limitations by allowing finer control
291 over where warnings can or can\*(Aqt be tripped.
292 .SS "Controlling Warnings from the Command Line"
293 .IX Subsection "Controlling Warnings from the Command Line"
294 There are three Command Line flags that can be used to control when
295 warnings are (or aren\*(Aqt) produced:
296 .IP \fB\-w\fR 5
297 .IX Xref "-w"
298 .IX Item "-w"
299 This is the existing flag. If the lexical warnings pragma is \fBnot\fR
300 used in any of your code, or any of the modules that you use, this flag
301 will enable warnings everywhere. See "Backward Compatibility" for
302 details of how this flag interacts with lexical warnings.
303 .IP \fB\-W\fR 5
304 .IX Xref "-W"
305 .IX Item "-W"
306 If the \fB\-W\fR flag is used on the command line, it will enable all warnings
307 throughout the program regardless of whether warnings were disabled
308 locally using \f(CW\*(C`no warnings\*(C'\fR or \f(CW\*(C`$^W =0\*(C'\fR.
309 This includes all files that get
310 included via \f(CW\*(C`use\*(C'\fR, \f(CW\*(C`require\*(C'\fR or \f(CW\*(C`do\*(C'\fR.
311 Think of it as the Perl equivalent of the "lint" command.
312 .IP \fB\-X\fR 5
313 .IX Xref "-X"
314 .IX Item "-X"
315 Does the exact opposite to the \fB\-W\fR flag, i.e. it disables all warnings.
316 .SS "Backward Compatibility"
317 .IX Subsection "Backward Compatibility"
318 If you are used to working with a version of Perl prior to the
319 introduction of lexically scoped warnings, or have code that uses both
320 lexical warnings and \f(CW$^W\fR, this section will describe how they interact.
321 .PP
322 How Lexical Warnings interact with \fB\-w\fR/\f(CW$^W\fR:
323 .IP 1. 5
324 If none of the three command line flags (\fB\-w\fR, \fB\-W\fR or \fB\-X\fR) that
325 control warnings is used and neither \f(CW$^W\fR nor the \f(CW\*(C`warnings\*(C'\fR pragma
326 are used, then default warnings will be enabled and optional warnings
327 disabled.
328 This means that legacy code that doesn\*(Aqt attempt to control the warnings
329 will work unchanged.
330 .IP 2. 5
331 The \fB\-w\fR flag just sets the global \f(CW$^W\fR variable as in 5.005. This
332 means that any legacy code that currently relies on manipulating \f(CW$^W\fR
333 to control warning behavior will still work as is.
334 .IP 3. 5
335 Apart from now being a boolean, the \f(CW$^W\fR variable operates in exactly
336 the same horrible uncontrolled global way, except that it cannot
337 disable/enable default warnings.
338 .IP 4. 5
339 If a piece of code is under the control of the \f(CW\*(C`warnings\*(C'\fR pragma,
340 both the \f(CW$^W\fR variable and the \fB\-w\fR flag will be ignored for the
341 scope of the lexical warning.
342 .IP 5. 5
343 The only way to override a lexical warnings setting is with the \fB\-W\fR
344 or \fB\-X\fR command line flags.
345 .PP
346 The combined effect of 3 & 4 is that it will allow code which uses
347 the \f(CW\*(C`warnings\*(C'\fR pragma to control the warning behavior of $^W\-type
348 code (using a \f(CW\*(C`local $^W=0\*(C'\fR) if it really wants to, but not vice\-versa.
349 .SS "Category Hierarchy"
350 .IX Xref "warning, categories"
351 .IX Subsection "Category Hierarchy"
352 A hierarchy of "categories" have been defined to allow groups of warnings
353 to be enabled/disabled in isolation.
354 .PP
355 The current hierarchy is:
356 .PP
357 .Vb 10
358 \& all \-+
359 \& |
360 \& +\- closure
361 \& |
362 \& +\- deprecated \-\-\-\-+
363 \& | |
364 \& | +\- deprecated::delimiter_will_be_paired
365 \& | |
366 \& | +\- deprecated::dot_in_inc
367 \& | |
368 \& | +\- deprecated::goto_construct
369 \& | |
370 \& | +\- deprecated::missing_import_called_with_args
371 \& | |
372 \& | +\- deprecated::subsequent_use_version
373 \& | |
374 \& | +\- deprecated::unicode_property_name
375 \& | |
376 \& | +\- deprecated::version_downgrade
377 \& |
378 \& +\- exiting
379 \& |
380 \& +\- experimental \-\-+
381 \& | |
382 \& | +\- experimental::args_array_with_signatures
383 \& | |
384 \& | +\- experimental::builtin
385 \& | |
386 \& | +\- experimental::class
387 \& | |
388 \& | +\- experimental::declared_refs
389 \& | |
390 \& | +\- experimental::defer
391 \& | |
392 \& | +\- experimental::extra_paired_delimiters
393 \& | |
394 \& | +\- experimental::keyword_all
395 \& | |
396 \& | +\- experimental::keyword_any
397 \& | |
398 \& | +\- experimental::private_use
399 \& | |
400 \& | +\- experimental::re_strict
401 \& | |
402 \& | +\- experimental::refaliasing
403 \& | |
404 \& | +\- experimental::regex_sets
405 \& | |
406 \& | +\- experimental::try
407 \& | |
408 \& | +\- experimental::uniprop_wildcards
409 \& | |
410 \& | +\- experimental::vlb
411 \& |
412 \& +\- glob
413 \& |
414 \& +\- imprecision
415 \& |
416 \& +\- io \-\-\-\-\-\-\-\-\-\-\-\-+
417 \& | |
418 \& | +\- closed
419 \& | |
420 \& | +\- exec
421 \& | |
422 \& | +\- layer
423 \& | |
424 \& | +\- newline
425 \& | |
426 \& | +\- pipe
427 \& | |
428 \& | +\- syscalls
429 \& | |
430 \& | +\- unopened
431 \& |
432 \& +\- locale
433 \& |
434 \& +\- misc
435 \& |
436 \& +\- missing
437 \& |
438 \& +\- numeric
439 \& |
440 \& +\- once
441 \& |
442 \& +\- overflow
443 \& |
444 \& +\- pack
445 \& |
446 \& +\- portable
447 \& |
448 \& +\- recursion
449 \& |
450 \& +\- redefine
451 \& |
452 \& +\- redundant
453 \& |
454 \& +\- regexp
455 \& |
456 \& +\- scalar
457 \& |
458 \& +\- severe \-\-\-\-\-\-\-\-+
459 \& | |
460 \& | +\- debugging
461 \& | |
462 \& | +\- inplace
463 \& | |
464 \& | +\- internal
465 \& | |
466 \& | +\- malloc
467 \& |
468 \& +\- shadow
469 \& |
470 \& +\- signal
471 \& |
472 \& +\- substr
473 \& |
474 \& +\- syntax \-\-\-\-\-\-\-\-+
475 \& | |
476 \& | +\- ambiguous
477 \& | |
478 \& | +\- bareword
479 \& | |
480 \& | +\- digit
481 \& | |
482 \& | +\- illegalproto
483 \& | |
484 \& | +\- parenthesis
485 \& | |
486 \& | +\- precedence
487 \& | |
488 \& | +\- printf
489 \& | |
490 \& | +\- prototype
491 \& | |
492 \& | +\- qw
493 \& | |
494 \& | +\- reserved
495 \& | |
496 \& | +\- semicolon
497 \& |
498 \& +\- taint
499 \& |
500 \& +\- threads
501 \& |
502 \& +\- uninitialized
503 \& |
504 \& +\- unpack
505 \& |
506 \& +\- untie
507 \& |
508 \& +\- utf8 \-\-\-\-\-\-\-\-\-\-+
509 \& | |
510 \& | +\- non_unicode
511 \& | |
512 \& | +\- nonchar
513 \& | |
514 \& | +\- surrogate
515 \& |
516 \& +\- void
517 .Ve
518 .PP
519 Just like the "strict" pragma any of these categories can be combined
520 .PP
521 .Vb 2
522 \& use warnings qw(void redefine);
523 \& no warnings qw(io syntax untie);
524 .Ve
525 .PP
526 Also like the "strict" pragma, if there is more than one instance of the
527 \&\f(CW\*(C`warnings\*(C'\fR pragma in a given scope the cumulative effect is additive.
528 .PP
529 .Vb 5
530 \& use warnings qw(void); # only "void" warnings enabled
531 \& ...
532 \& use warnings qw(io); # only "void" & "io" warnings enabled
533 \& ...
534 \& no warnings qw(void); # only "io" warnings enabled
535 .Ve
536 .PP
537 To determine which category a specific warning has been assigned to see
538 perldiag.
539 .PP
540 Note: Before Perl 5.8.0, the lexical warnings category "deprecated" was a
541 sub\-category of the "syntax" category. It is now a top\-level category
542 in its own right.
543 .PP
544 Note: Before 5.21.0, the "missing" lexical warnings category was
545 internally defined to be the same as the "uninitialized" category. It
546 is now a top\-level category in its own right.
547 .SS "Fatal Warnings"
548 .IX Xref "warning, fatal"
549 .IX Subsection "Fatal Warnings"
550 The presence of the word "FATAL" in the category list will escalate
551 warnings in those categories into fatal errors in that lexical scope.
552 .PP
553 \&\fBNOTE:\fR FATAL warnings should be used with care, particularly
554 \&\f(CW\*(C`FATAL => \*(Aqall\*(Aq\*(C'\fR.
555 .PP
556 Libraries using warnings::warn for custom warning categories
557 generally don\*(Aqt expect warnings::warn to be fatal and can wind up
558 in an unexpected state as a result. For XS modules issuing categorized
559 warnings, such unanticipated exceptions could also expose memory leak bugs.
560 .PP
561 Moreover, the Perl interpreter itself has had serious bugs involving
562 fatalized warnings. For a summary of resolved and unresolved problems as
563 of January 2015, please see
564 this perl5\-porters post <http://www.nntp.perl.org/group/perl.perl5.porters/2015/01/msg225235.html>.
565 .PP
566 While some developers find fatalizing some warnings to be a useful
567 defensive programming technique, using \f(CW\*(C`FATAL => \*(Aqall\*(Aq\*(C'\fR to fatalize
568 all possible warning categories \-\- including custom ones \-\- is particularly
569 risky. Therefore, the use of \f(CW\*(C`FATAL => \*(Aqall\*(Aq\*(C'\fR is
570 discouraged.
571 .PP
572 The strictures module on CPAN offers one example of
573 a warnings subset that the module\*(Aqs authors believe is relatively safe to
574 fatalize.
575 .PP
576 \&\fBNOTE:\fR Users of FATAL warnings, especially those using
577 \&\f(CW\*(C`FATAL => \*(Aqall\*(Aq\*(C'\fR, should be fully aware that they are risking future
578 portability of their programs by doing so. Perl makes absolutely no
579 commitments to not introduce new warnings or warnings categories in the
580 future; indeed, we explicitly reserve the right to do so. Code that may
581 not warn now may warn in a future release of Perl if the Perl5 development
582 team deems it in the best interests of the community to do so. Should code
583 using FATAL warnings break due to the introduction of a new warning we will
584 NOT consider it an incompatible change. Users of FATAL warnings should
585 take special caution during upgrades to check to see if their code triggers
586 any new warnings and should pay particular attention to the fine print of
587 the documentation of the features they use to ensure they do not exploit
588 features that are documented as risky, deprecated, or unspecified, or where
589 the documentation says "so don\*(Aqt do that", or anything with the same sense
590 and spirit. Use of such features in combination with FATAL warnings is
591 ENTIRELY AT THE USER\*(AqS RISK.
592 .PP
593 The following documentation describes how to use FATAL warnings but the
594 perl5 porters strongly recommend that you understand the risks before doing
595 so, especially for library code intended for use by others, as there is no
596 way for downstream users to change the choice of fatal categories.
597 .PP
598 In the code below, the use of \f(CW\*(C`time\*(C'\fR, \f(CW\*(C`length\*(C'\fR
599 and \f(CW\*(C`join\*(C'\fR can all produce a \f(CW"Useless use of xxx in void context"\fR
600 warning.
601 .PP
602 .Vb 1
603 \& use warnings;
604 \&
605 \& time;
606 \&
607 \& {
608 \& use warnings FATAL => qw(void);
609 \& length "abc";
610 \& }
611 \&
612 \& join "", 1,2,3;
613 \&
614 \& print "done\en";
615 .Ve
616 .PP
617 When run it produces this output
618 .PP
619 .Vb 2
620 \& Useless use of time in void context at fatal line 3.
621 \& Useless use of length in void context at fatal line 7.
622 .Ve
623 .PP
624 The scope where \f(CW\*(C`length\*(C'\fR is used has escalated the \f(CW\*(C`void\*(C'\fR warnings
625 category into a fatal error, so the program terminates immediately when it
626 encounters the warning.
627 .PP
628 To explicitly turn off a "FATAL" warning you just disable the warning
629 it is associated with. So, for example, to disable the "void" warning
630 in the example above, either of these will do the trick:
631 .PP
632 .Vb 2
633 \& no warnings qw(void);
634 \& no warnings FATAL => qw(void);
635 .Ve
636 .PP
637 If you want to downgrade a warning that has been escalated into a fatal
638 error back to a normal warning, you can use the "NONFATAL" keyword. For
639 example, the code below will promote all warnings into fatal errors,
640 except for those in the "syntax" category.
641 .PP
642 .Vb 1
643 \& use warnings FATAL => \*(Aqall\*(Aq, NONFATAL => \*(Aqsyntax\*(Aq;
644 .Ve
645 .PP
646 As of Perl 5.20, instead of \f(CW\*(C`use warnings FATAL => \*(Aqall\*(Aq;\*(C'\fR you can
647 use:
648 .PP
649 .Vb 2
650 \& use v5.20; # Perl 5.20 or greater is required for the following
651 \& use warnings \*(AqFATAL\*(Aq; # short form of "use warnings FATAL => \*(Aqall\*(Aq;"
652 .Ve
653 .PP
654 However, you should still heed the guidance earlier in this section against
655 using \f(CW\*(C`use warnings FATAL => \*(Aqall\*(Aq;\*(C'\fR.
656 .PP
657 If you want your program to be compatible with versions of Perl before
658 5.20, you must use \f(CW\*(C`use warnings FATAL => \*(Aqall\*(Aq;\*(C'\fR instead. (In
659 previous versions of Perl, the behavior of the statements
660 \&\f(CW\*(C`use warnings \*(AqFATAL\*(Aq;\*(C'\fR, \f(CW\*(C`use warnings \*(AqNONFATAL\*(Aq;\*(C'\fR and
661 \&\f(CW\*(C`no warnings \*(AqFATAL\*(Aq;\*(C'\fR was unspecified; they did not behave as if
662 they included the \f(CW\*(C`=> \*(Aqall\*(Aq\*(C'\fR portion. As of 5.20, they do.)
663 .SS "Reporting Warnings from a Module"
664 .IX Xref "warning, reporting warning, registering"
665 .IX Subsection "Reporting Warnings from a Module"
666 The \f(CW\*(C`warnings\*(C'\fR pragma provides a number of functions that are useful for
667 module authors. These are used when you want to report a module\-specific
668 warning to a calling module that has enabled warnings via the \f(CW\*(C`warnings\*(C'\fR
669 pragma.
670 .PP
671 Consider the module \f(CW\*(C`MyMod::Abc\*(C'\fR below.
672 .PP
673 .Vb 1
674 \& package MyMod::Abc;
675 \&
676 \& use warnings::register;
677 \&
678 \& sub open {
679 \& my $path = shift;
680 \& if ($path !~ m#^/#) {
681 \& warnings::warn("changing relative path to /var/abc")
682 \& if warnings::enabled();
683 \& $path = "/var/abc/$path";
684 \& }
685 \& }
686 \&
687 \& 1;
688 .Ve
689 .PP
690 The call to \f(CW\*(C`warnings::register\*(C'\fR will create a new warnings category
691 called "MyMod::Abc", i.e. the new category name matches the current
692 package name. The \f(CW\*(C`open\*(C'\fR function in the module will display a warning
693 message if it gets given a relative path as a parameter. This warning
694 will only be displayed if the code that uses \f(CW\*(C`MyMod::Abc\*(C'\fR has actually
695 enabled them with the \f(CW\*(C`warnings\*(C'\fR pragma as below \- note that a plain
696 \&\f(CW\*(C`use warnings\*(C'\fR enables even warnings that have not yet been registered.
697 .PP
698 .Vb 4
699 \& use warnings;
700 \& use MyMod::Abc;
701 \& ...
702 \& abc::open("../fred.txt");
703 .Ve
704 .PP
705 The specific warning can be enabled or disabled, but only after the module
706 has been imported:
707 .PP
708 .Vb 6
709 \& # no warnings \*(AqMyMod::Abc\*(Aq; # error, unknown category before
710 \& # the module is loaded
711 \& use MyMod::Abc;
712 \& no warnings \*(AqMyMod::Abc\*(Aq; # ok after the module is loaded
713 \& ...
714 \& abc::open("../fred.txt");
715 .Ve
716 .PP
717 It is also possible to test whether the pre\-defined warnings categories are
718 set in the calling module with the \f(CW\*(C`warnings::enabled\*(C'\fR function. Consider
719 this snippet of code:
720 .PP
721 .Vb 1
722 \& package MyMod::Abc;
723 \&
724 \& sub open2 {
725 \& if (warnings::enabled("deprecated")) {
726 \& warnings::warn("deprecated",
727 \& "open2 is deprecated, use open instead");
728 \& }
729 \& open(@_);
730 \& }
731 \&
732 \& sub open
733 \& ...
734 \& 1;
735 .Ve
736 .PP
737 The function \f(CW\*(C`open2\*(C'\fR has been deprecated, so code has been included to
738 display a warning message whenever the calling module has (at least) the
739 "deprecated" warnings category enabled. Something like this, say.
740 .PP
741 .Vb 4
742 \& use warnings \*(Aqdeprecated\*(Aq;
743 \& use MyMod::Abc;
744 \& ...
745 \& MyMod::Abc::open2($filename);
746 .Ve
747 .PP
748 Either the \f(CW\*(C`warnings::warn\*(C'\fR or \f(CW\*(C`warnings::warnif\*(C'\fR function should be
749 used to actually display the warnings message. This is because they can
750 make use of the feature that allows warnings to be escalated into fatal
751 errors. So in this case
752 .PP
753 .Vb 4
754 \& use MyMod::Abc;
755 \& use warnings FATAL => \*(AqMyMod::Abc\*(Aq;
756 \& ...
757 \& MyMod::Abc::open(\*(Aq../fred.txt\*(Aq);
758 .Ve
759 .PP
760 the \f(CW\*(C`warnings::warnif\*(C'\fR function will detect this and die after
761 displaying the warning message.
762 .PP
763 The three warnings functions, \f(CW\*(C`warnings::warn\*(C'\fR, \f(CW\*(C`warnings::warnif\*(C'\fR
764 and \f(CW\*(C`warnings::enabled\*(C'\fR can optionally take an object reference in place
765 of a category name. In this case the functions will use the class name
766 of the object as the warnings category.
767 .PP
768 Consider this example:
769 .PP
770 .Vb 1
771 \& package Original;
772 \&
773 \& no warnings;
774 \& use warnings::register;
775 \&
776 \& sub new
777 \& {
778 \& my $class = shift;
779 \& bless [], $class;
780 \& }
781 \&
782 \& sub check
783 \& {
784 \& my $self = shift;
785 \& my $value = shift;
786 \&
787 \& if ($value % 2 && warnings::enabled($self))
788 \& { warnings::warn($self, "Odd numbers are unsafe") }
789 \& }
790 \&
791 \& sub doit
792 \& {
793 \& my $self = shift;
794 \& my $value = shift;
795 \& $self\->check($value);
796 \& # ...
797 \& }
798 \&
799 \& 1;
800 \&
801 \& package Derived;
802 \&
803 \& use warnings::register;
804 \& use Original;
805 \& our @ISA = qw( Original );
806 \& sub new
807 \& {
808 \& my $class = shift;
809 \& bless [], $class;
810 \& }
811 \&
812 \&
813 \& 1;
814 .Ve
815 .PP
816 The code below makes use of both modules, but it only enables warnings from
817 \&\f(CW\*(C`Derived\*(C'\fR.
818 .PP
819 .Vb 7
820 \& use Original;
821 \& use Derived;
822 \& use warnings \*(AqDerived\*(Aq;
823 \& my $x = Original\->new();
824 \& $x\->doit(1);
825 \& my $y = Derived\->new();
826 \& $x\->doit(1);
827 .Ve
828 .PP
829 When this code is run only the \f(CW\*(C`Derived\*(C'\fR object, \f(CW$y\fR, will generate
830 a warning.
831 .PP
832 .Vb 1
833 \& Odd numbers are unsafe at main.pl line 7
834 .Ve
835 .PP
836 Notice also that the warning is reported at the line where the object is first
837 used.
838 .PP
839 When registering new categories of warning, you can supply more names to
840 warnings::register like this:
841 .PP
842 .Vb 2
843 \& package MyModule;
844 \& use warnings::register qw(format precision);
845 \&
846 \& ...
847 \&
848 \& warnings::warnif(\*(AqMyModule::format\*(Aq, \*(Aq...\*(Aq);
849 .Ve
850 .SH FUNCTIONS
851 .IX Header "FUNCTIONS"
852 Note: The functions with names ending in \f(CW\*(C`_at_level\*(C'\fR were added in Perl
853 5.28.
854 .IP "use warnings::register" 4
855 .IX Item "use warnings::register"
856 Creates a new warnings category with the same name as the package where
857 the call to the pragma is used.
858 .IP \fBwarnings::enabled()\fR 4
859 .IX Item "warnings::enabled()"
860 Use the warnings category with the same name as the current package.
861 .Sp
862 Return TRUE if that warnings category is enabled in the calling module.
863 Otherwise returns FALSE.
864 .IP warnings::enabled($category) 4
865 .IX Item "warnings::enabled($category)"
866 Return TRUE if the warnings category, \f(CW$category\fR, is enabled in the
867 calling module.
868 Otherwise returns FALSE.
869 .IP warnings::enabled($object) 4
870 .IX Item "warnings::enabled($object)"
871 Use the name of the class for the object reference, \f(CW$object\fR, as the
872 warnings category.
873 .Sp
874 Return TRUE if that warnings category is enabled in the first scope
875 where the object is used.
876 Otherwise returns FALSE.
877 .ie n .IP "warnings::enabled_at_level($category, $level)" 4
878 .el .IP "warnings::enabled_at_level($category, \f(CW$level\fR)" 4
879 .IX Item "warnings::enabled_at_level($category, $level)"
880 Like \f(CW\*(C`warnings::enabled\*(C'\fR, but \f(CW$level\fR specifies the exact call frame, 0
881 being the immediate caller.
882 .IP \fBwarnings::fatal_enabled()\fR 4
883 .IX Item "warnings::fatal_enabled()"
884 Return TRUE if the warnings category with the same name as the current
885 package has been set to FATAL in the calling module.
886 Otherwise returns FALSE.
887 .IP warnings::fatal_enabled($category) 4
888 .IX Item "warnings::fatal_enabled($category)"
889 Return TRUE if the warnings category \f(CW$category\fR has been set to FATAL in
890 the calling module.
891 Otherwise returns FALSE.
892 .IP warnings::fatal_enabled($object) 4
893 .IX Item "warnings::fatal_enabled($object)"
894 Use the name of the class for the object reference, \f(CW$object\fR, as the
895 warnings category.
896 .Sp
897 Return TRUE if that warnings category has been set to FATAL in the first
898 scope where the object is used.
899 Otherwise returns FALSE.
900 .ie n .IP "warnings::fatal_enabled_at_level($category, $level)" 4
901 .el .IP "warnings::fatal_enabled_at_level($category, \f(CW$level\fR)" 4
902 .IX Item "warnings::fatal_enabled_at_level($category, $level)"
903 Like \f(CW\*(C`warnings::fatal_enabled\*(C'\fR, but \f(CW$level\fR specifies the exact call frame,
904 0 being the immediate caller.
905 .IP warnings::warn($message) 4
906 .IX Item "warnings::warn($message)"
907 Print \f(CW$message\fR to STDERR.
908 .Sp
909 Use the warnings category with the same name as the current package.
910 .Sp
911 If that warnings category has been set to "FATAL" in the calling module
912 then die. Otherwise return.
913 .ie n .IP "warnings::warn($category, $message)" 4
914 .el .IP "warnings::warn($category, \f(CW$message\fR)" 4
915 .IX Item "warnings::warn($category, $message)"
916 Print \f(CW$message\fR to STDERR.
917 .Sp
918 If the warnings category, \f(CW$category\fR, has been set to "FATAL" in the
919 calling module then die. Otherwise return.
920 .ie n .IP "warnings::warn($object, $message)" 4
921 .el .IP "warnings::warn($object, \f(CW$message\fR)" 4
922 .IX Item "warnings::warn($object, $message)"
923 Print \f(CW$message\fR to STDERR.
924 .Sp
925 Use the name of the class for the object reference, \f(CW$object\fR, as the
926 warnings category.
927 .Sp
928 If that warnings category has been set to "FATAL" in the scope where \f(CW$object\fR
929 is first used then die. Otherwise return.
930 .ie n .IP "warnings::warn_at_level($category, $level, $message)" 4
931 .el .IP "warnings::warn_at_level($category, \f(CW$level\fR, \f(CW$message\fR)" 4
932 .IX Item "warnings::warn_at_level($category, $level, $message)"
933 Like \f(CW\*(C`warnings::warn\*(C'\fR, but \f(CW$level\fR specifies the exact call frame,
934 0 being the immediate caller.
935 .IP warnings::warnif($message) 4
936 .IX Item "warnings::warnif($message)"
937 Equivalent to:
938 .Sp
939 .Vb 2
940 \& if (warnings::enabled())
941 \& { warnings::warn($message) }
942 .Ve
943 .ie n .IP "warnings::warnif($category, $message)" 4
944 .el .IP "warnings::warnif($category, \f(CW$message\fR)" 4
945 .IX Item "warnings::warnif($category, $message)"
946 Equivalent to:
947 .Sp
948 .Vb 2
949 \& if (warnings::enabled($category))
950 \& { warnings::warn($category, $message) }
951 .Ve
952 .ie n .IP "warnings::warnif($object, $message)" 4
953 .el .IP "warnings::warnif($object, \f(CW$message\fR)" 4
954 .IX Item "warnings::warnif($object, $message)"
955 Equivalent to:
956 .Sp
957 .Vb 2
958 \& if (warnings::enabled($object))
959 \& { warnings::warn($object, $message) }
960 .Ve
961 .ie n .IP "warnings::warnif_at_level($category, $level, $message)" 4
962 .el .IP "warnings::warnif_at_level($category, \f(CW$level\fR, \f(CW$message\fR)" 4
963 .IX Item "warnings::warnif_at_level($category, $level, $message)"
964 Like \f(CW\*(C`warnings::warnif\*(C'\fR, but \f(CW$level\fR specifies the exact call frame,
965 0 being the immediate caller.
966 .IP warnings::register_categories(@names) 4
967 .IX Item "warnings::register_categories(@names)"
968 This registers warning categories for the given names and is primarily for
969 use by the warnings::register pragma.
970 .PP
971 See also "Pragmatic Modules" in perlmodlib and perldiag.