Debian Codegraph @

upstream/debian-unstable/man3/warnings.3perl

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