This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
move POD in warnings.pm to end of file to reduce module load I/O calls
[perl5.git] / lib / warnings.pm
CommitLineData
37442d52 1# -*- buffer-read-only: t -*-
38875929 2# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
78102347
NC
3# This file is built by regen/warnings.pl.
4# Any changes made here will be lost!
599cee73 5
4438c4b7 6package warnings;
599cee73 7
effd17dc 8our $VERSION = '1.28';
f2c3e829
RGS
9
10# Verify that we're called correctly so that warnings will work.
11# see also strict.pm.
5108dc18 12unless ( __FILE__ =~ /(^|[\/\\])\Q${\__PACKAGE__}\E\.pmc?$/ ) {
f2c3e829 13 my (undef, $f, $l) = caller;
5108dc18 14 die("Incorrect use of pragma '${\__PACKAGE__}' at $f line $l.\n");
f2c3e829 15}
0ca4541c 16
effd17dc
DD
17our %Offsets = (
18
19 # Warnings Categories added in Perl 5.008
20
21 'all' => 0,
22 'closure' => 2,
23 'deprecated' => 4,
24 'exiting' => 6,
25 'glob' => 8,
26 'io' => 10,
27 'closed' => 12,
28 'exec' => 14,
29 'layer' => 16,
30 'newline' => 18,
31 'pipe' => 20,
32 'unopened' => 22,
33 'misc' => 24,
34 'numeric' => 26,
35 'once' => 28,
36 'overflow' => 30,
37 'pack' => 32,
38 'portable' => 34,
39 'recursion' => 36,
40 'redefine' => 38,
41 'regexp' => 40,
42 'severe' => 42,
43 'debugging' => 44,
44 'inplace' => 46,
45 'internal' => 48,
46 'malloc' => 50,
47 'signal' => 52,
48 'substr' => 54,
49 'syntax' => 56,
50 'ambiguous' => 58,
51 'bareword' => 60,
52 'digit' => 62,
53 'parenthesis' => 64,
54 'precedence' => 66,
55 'printf' => 68,
56 'prototype' => 70,
57 'qw' => 72,
58 'reserved' => 74,
59 'semicolon' => 76,
60 'taint' => 78,
61 'threads' => 80,
62 'uninitialized' => 82,
63 'unpack' => 84,
64 'untie' => 86,
65 'utf8' => 88,
66 'void' => 90,
67
68 # Warnings Categories added in Perl 5.011
69
70 'imprecision' => 92,
71 'illegalproto' => 94,
72
73 # Warnings Categories added in Perl 5.013
74
75 'non_unicode' => 96,
76 'nonchar' => 98,
77 'surrogate' => 100,
78
79 # Warnings Categories added in Perl 5.017
80
81 'experimental' => 102,
82 'experimental::lexical_subs'=> 104,
83 'experimental::lexical_topic'=> 106,
84 'experimental::regex_sets'=> 108,
85 'experimental::smartmatch'=> 110,
86
87 # Warnings Categories added in Perl 5.019
88
89 'experimental::autoderef'=> 112,
90 'experimental::postderef'=> 114,
91 'experimental::signatures'=> 116,
92 'syscalls' => 118,
93
94 # Warnings Categories added in Perl 5.021
95
96 'experimental::lvalue_refs'=> 120,
97 'experimental::win32_perlio'=> 122,
98 'missing' => 124,
99 'redundant' => 126,
100 );
101
102our %Bits = (
103 'all' => "\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55", # [0..63]
104 'ambiguous' => "\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00\x00\x00\x00\x00\x00\x00", # [29]
105 'bareword' => "\x00\x00\x00\x00\x00\x00\x00\x10\x00\x00\x00\x00\x00\x00\x00\x00", # [30]
106 'closed' => "\x00\x10\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [6]
107 'closure' => "\x04\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [1]
108 'debugging' => "\x00\x00\x00\x00\x00\x10\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [22]
109 'deprecated' => "\x10\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [2]
110 'digit' => "\x00\x00\x00\x00\x00\x00\x00\x40\x00\x00\x00\x00\x00\x00\x00\x00", # [31]
111 'exec' => "\x00\x40\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [7]
112 'exiting' => "\x40\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [3]
113 'experimental' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x40\x55\x15\x05", # [51..58,60,61]
114 'experimental::autoderef'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00", # [56]
115 'experimental::lexical_subs'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00", # [52]
116 'experimental::lexical_topic'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00", # [53]
117 'experimental::lvalue_refs'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01", # [60]
118 'experimental::postderef'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00", # [57]
119 'experimental::regex_sets'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x10\x00\x00", # [54]
120 'experimental::signatures'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x10\x00", # [58]
121 'experimental::smartmatch'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x40\x00\x00", # [55]
122 'experimental::win32_perlio'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x04", # [61]
123 'glob' => "\x00\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [4]
124 'illegalproto' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x40\x00\x00\x00\x00", # [47]
125 'imprecision' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x10\x00\x00\x00\x00", # [46]
126 'inplace' => "\x00\x00\x00\x00\x00\x40\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [23]
127 'internal' => "\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [24]
128 'io' => "\x00\x54\x55\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x40\x00", # [5..11,59]
129 'layer' => "\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [8]
130 'malloc' => "\x00\x00\x00\x00\x00\x00\x04\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [25]
131 'misc' => "\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [12]
132 'missing' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x10", # [62]
133 'newline' => "\x00\x00\x04\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [9]
134 'non_unicode' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00", # [48]
135 'nonchar' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00\x00", # [49]
136 'numeric' => "\x00\x00\x00\x04\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [13]
137 'once' => "\x00\x00\x00\x10\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [14]
138 'overflow' => "\x00\x00\x00\x40\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [15]
139 'pack' => "\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [16]
140 'parenthesis' => "\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00", # [32]
141 'pipe' => "\x00\x00\x10\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [10]
142 'portable' => "\x00\x00\x00\x00\x04\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [17]
143 'precedence' => "\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00\x00\x00\x00\x00\x00", # [33]
144 'printf' => "\x00\x00\x00\x00\x00\x00\x00\x00\x10\x00\x00\x00\x00\x00\x00\x00", # [34]
145 'prototype' => "\x00\x00\x00\x00\x00\x00\x00\x00\x40\x00\x00\x00\x00\x00\x00\x00", # [35]
146 'qw' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00", # [36]
147 'recursion' => "\x00\x00\x00\x00\x10\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [18]
148 'redefine' => "\x00\x00\x00\x00\x40\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [19]
149 'redundant' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x40", # [63]
150 'regexp' => "\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [20]
151 'reserved' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00\x00\x00\x00\x00", # [37]
152 'semicolon' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x10\x00\x00\x00\x00\x00\x00", # [38]
153 'severe' => "\x00\x00\x00\x00\x00\x54\x05\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [21..25]
154 'signal' => "\x00\x00\x00\x00\x00\x00\x10\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [26]
155 'substr' => "\x00\x00\x00\x00\x00\x00\x40\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [27]
156 'surrogate' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x10\x00\x00\x00", # [50]
157 'syntax' => "\x00\x00\x00\x00\x00\x00\x00\x55\x55\x15\x00\x40\x00\x00\x00\x00", # [28..38,47]
158 'syscalls' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x40\x00", # [59]
159 'taint' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x40\x00\x00\x00\x00\x00\x00", # [39]
160 'threads' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00", # [40]
161 'uninitialized' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00\x00\x00\x00", # [41]
162 'unopened' => "\x00\x00\x40\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [11]
163 'unpack' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x10\x00\x00\x00\x00\x00", # [42]
164 'untie' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x40\x00\x00\x00\x00\x00", # [43]
165 'utf8' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x15\x00\x00\x00", # [44,48..50]
166 'void' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00\x00\x00", # [45]
167 );
168
169our %DeadBits = (
170 'all' => "\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa", # [0..63]
171 'ambiguous' => "\x00\x00\x00\x00\x00\x00\x00\x08\x00\x00\x00\x00\x00\x00\x00\x00", # [29]
172 'bareword' => "\x00\x00\x00\x00\x00\x00\x00\x20\x00\x00\x00\x00\x00\x00\x00\x00", # [30]
173 'closed' => "\x00\x20\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [6]
174 'closure' => "\x08\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [1]
175 'debugging' => "\x00\x00\x00\x00\x00\x20\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [22]
176 'deprecated' => "\x20\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [2]
177 'digit' => "\x00\x00\x00\x00\x00\x00\x00\x80\x00\x00\x00\x00\x00\x00\x00\x00", # [31]
178 'exec' => "\x00\x80\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [7]
179 'exiting' => "\x80\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [3]
180 'experimental' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80\xaa\x2a\x0a", # [51..58,60,61]
181 'experimental::autoderef'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00", # [56]
182 'experimental::lexical_subs'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x00", # [52]
183 'experimental::lexical_topic'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x08\x00\x00", # [53]
184 'experimental::lvalue_refs'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02", # [60]
185 'experimental::postderef'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x08\x00", # [57]
186 'experimental::regex_sets'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x20\x00\x00", # [54]
187 'experimental::signatures'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x20\x00", # [58]
188 'experimental::smartmatch'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80\x00\x00", # [55]
189 'experimental::win32_perlio'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x08", # [61]
190 'glob' => "\x00\x02\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [4]
191 'illegalproto' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80\x00\x00\x00\x00", # [47]
192 'imprecision' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x20\x00\x00\x00\x00", # [46]
193 'inplace' => "\x00\x00\x00\x00\x00\x80\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [23]
194 'internal' => "\x00\x00\x00\x00\x00\x00\x02\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [24]
195 'io' => "\x00\xa8\xaa\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80\x00", # [5..11,59]
196 'layer' => "\x00\x00\x02\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [8]
197 'malloc' => "\x00\x00\x00\x00\x00\x00\x08\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [25]
198 'misc' => "\x00\x00\x00\x02\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [12]
199 'missing' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x20", # [62]
200 'newline' => "\x00\x00\x08\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [9]
201 'non_unicode' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x00\x00", # [48]
202 'nonchar' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x08\x00\x00\x00", # [49]
203 'numeric' => "\x00\x00\x00\x08\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [13]
204 'once' => "\x00\x00\x00\x20\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [14]
205 'overflow' => "\x00\x00\x00\x80\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [15]
206 'pack' => "\x00\x00\x00\x00\x02\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [16]
207 'parenthesis' => "\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x00\x00\x00\x00\x00\x00", # [32]
208 'pipe' => "\x00\x00\x20\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [10]
209 'portable' => "\x00\x00\x00\x00\x08\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [17]
210 'precedence' => "\x00\x00\x00\x00\x00\x00\x00\x00\x08\x00\x00\x00\x00\x00\x00\x00", # [33]
211 'printf' => "\x00\x00\x00\x00\x00\x00\x00\x00\x20\x00\x00\x00\x00\x00\x00\x00", # [34]
212 'prototype' => "\x00\x00\x00\x00\x00\x00\x00\x00\x80\x00\x00\x00\x00\x00\x00\x00", # [35]
213 'qw' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x00\x00\x00\x00\x00", # [36]
214 'recursion' => "\x00\x00\x00\x00\x20\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [18]
215 'redefine' => "\x00\x00\x00\x00\x80\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [19]
216 'redundant' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80", # [63]
217 'regexp' => "\x00\x00\x00\x00\x00\x02\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [20]
218 'reserved' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x08\x00\x00\x00\x00\x00\x00", # [37]
219 'semicolon' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x20\x00\x00\x00\x00\x00\x00", # [38]
220 'severe' => "\x00\x00\x00\x00\x00\xa8\x0a\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [21..25]
221 'signal' => "\x00\x00\x00\x00\x00\x00\x20\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [26]
222 'substr' => "\x00\x00\x00\x00\x00\x00\x80\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [27]
223 'surrogate' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x20\x00\x00\x00", # [50]
224 'syntax' => "\x00\x00\x00\x00\x00\x00\x00\xaa\xaa\x2a\x00\x80\x00\x00\x00\x00", # [28..38,47]
225 'syscalls' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80\x00", # [59]
226 'taint' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80\x00\x00\x00\x00\x00\x00", # [39]
227 'threads' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x00\x00\x00\x00", # [40]
228 'uninitialized' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x08\x00\x00\x00\x00\x00", # [41]
229 'unopened' => "\x00\x00\x80\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [11]
230 'unpack' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x20\x00\x00\x00\x00\x00", # [42]
231 'untie' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80\x00\x00\x00\x00\x00", # [43]
232 'utf8' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x2a\x00\x00\x00", # [44,48..50]
233 'void' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x08\x00\x00\x00\x00", # [45]
234 );
235
236$NONE = "\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0";
237$DEFAULT = "\x10\x01\x00\x00\x00\x50\x04\x00\x00\x00\x00\x00\x00\x55\x15\x05", # [2,56,52,53,60,57,54,58,55,61,4,22,23,25]
238$LAST_BIT = 128 ;
239$BYTES = 16 ;
240
241$All = "" ; vec($All, $Offsets{'all'}, 2) = 3 ;
242
243sub Croaker
244{
245 require Carp; # this initializes %CarpInternal
246 local $Carp::CarpInternal{'warnings'};
247 delete $Carp::CarpInternal{'warnings'};
248 Carp::croak(@_);
249}
250
251sub _bits {
252 my $mask = shift ;
253 my $catmask ;
254 my $fatal = 0 ;
255 my $no_fatal = 0 ;
256
257 foreach my $word ( @_ ) {
258 if ($word eq 'FATAL') {
259 $fatal = 1;
260 $no_fatal = 0;
261 }
262 elsif ($word eq 'NONFATAL') {
263 $fatal = 0;
264 $no_fatal = 1;
265 }
266 elsif ($catmask = $Bits{$word}) {
267 $mask |= $catmask ;
268 $mask |= $DeadBits{$word} if $fatal ;
269 $mask &= ~($DeadBits{$word}|$All) if $no_fatal ;
270 }
271 else
272 { Croaker("Unknown warnings category '$word'")}
273 }
274
275 return $mask ;
276}
277
278sub bits
279{
280 # called from B::Deparse.pm
281 push @_, 'all' unless @_ ;
282 return _bits(undef, @_) ;
283}
284
285sub import
286{
287 shift;
288
289 my $mask = ${^WARNING_BITS} // ($^W ? $Bits{all} : $DEFAULT) ;
290
291 if (vec($mask, $Offsets{'all'}, 1)) {
292 $mask |= $Bits{'all'} ;
293 $mask |= $DeadBits{'all'} if vec($mask, $Offsets{'all'}+1, 1);
294 }
295
296 # append 'all' when implied (after a lone "FATAL" or "NONFATAL")
297 push @_, 'all' if @_==1 && ( $_[0] eq 'FATAL' || $_[0] eq 'NONFATAL' );
298
299 # Empty @_ is equivalent to @_ = 'all' ;
300 ${^WARNING_BITS} = @_ ? _bits($mask, @_) : $mask | $Bits{all} ;
301}
302
303sub unimport
304{
305 shift;
306
307 my $catmask ;
308 my $mask = ${^WARNING_BITS} // ($^W ? $Bits{all} : $DEFAULT) ;
309
310 if (vec($mask, $Offsets{'all'}, 1)) {
311 $mask |= $Bits{'all'} ;
312 $mask |= $DeadBits{'all'} if vec($mask, $Offsets{'all'}+1, 1);
313 }
314
315 # append 'all' when implied (empty import list or after a lone "FATAL")
316 push @_, 'all' if !@_ || @_==1 && $_[0] eq 'FATAL';
317
318 foreach my $word ( @_ ) {
319 if ($word eq 'FATAL') {
320 next;
321 }
322 elsif ($catmask = $Bits{$word}) {
323 $mask &= ~($catmask | $DeadBits{$word} | $All);
324 }
325 else
326 { Croaker("Unknown warnings category '$word'")}
327 }
328
329 ${^WARNING_BITS} = $mask ;
330}
331
332my %builtin_type; @builtin_type{qw(SCALAR ARRAY HASH CODE REF GLOB LVALUE Regexp)} = ();
333
334sub MESSAGE () { 4 };
335sub FATAL () { 2 };
336sub NORMAL () { 1 };
337
338sub __chk
339{
340 my $category ;
341 my $offset ;
342 my $isobj = 0 ;
343 my $wanted = shift;
344 my $has_message = $wanted & MESSAGE;
345
346 unless (@_ == 1 || @_ == ($has_message ? 2 : 0)) {
347 my $sub = (caller 1)[3];
348 my $syntax = $has_message ? "[category,] 'message'" : '[category]';
349 Croaker("Usage: $sub($syntax)");
350 }
351
352 my $message = pop if $has_message;
353
354 if (@_) {
355 # check the category supplied.
356 $category = shift ;
357 if (my $type = ref $category) {
358 Croaker("not an object")
359 if exists $builtin_type{$type};
360 $category = $type;
361 $isobj = 1 ;
362 }
363 $offset = $Offsets{$category};
364 Croaker("Unknown warnings category '$category'")
365 unless defined $offset;
366 }
367 else {
368 $category = (caller(1))[0] ;
369 $offset = $Offsets{$category};
370 Croaker("package '$category' not registered for warnings")
371 unless defined $offset ;
372 }
373
374 my $i;
375
376 if ($isobj) {
377 my $pkg;
378 $i = 2;
379 while (do { { package DB; $pkg = (caller($i++))[0] } } ) {
380 last unless @DB::args && $DB::args[0] =~ /^$category=/ ;
381 }
382 $i -= 2 ;
383 }
384 else {
385 $i = _error_loc(); # see where Carp will allocate the error
386 }
387
388 # Default to 0 if caller returns nothing. Default to $DEFAULT if it
389 # explicitly returns undef.
390 my(@callers_bitmask) = (caller($i))[9] ;
391 my $callers_bitmask =
392 @callers_bitmask ? $callers_bitmask[0] // $DEFAULT : 0 ;
393
394 my @results;
395 foreach my $type (FATAL, NORMAL) {
396 next unless $wanted & $type;
397
398 push @results, (vec($callers_bitmask, $offset + $type - 1, 1) ||
399 vec($callers_bitmask, $Offsets{'all'} + $type - 1, 1));
400 }
401
402 # &enabled and &fatal_enabled
403 return $results[0] unless $has_message;
404
405 # &warnif, and the category is neither enabled as warning nor as fatal
406 return if $wanted == (NORMAL | FATAL | MESSAGE)
407 && !($results[0] || $results[1]);
408
409 require Carp;
410 Carp::croak($message) if $results[0];
411 # will always get here for &warn. will only get here for &warnif if the
412 # category is enabled
413 Carp::carp($message);
414}
415
416sub _mkMask
417{
418 my ($bit) = @_;
419 my $mask = "";
420
421 vec($mask, $bit, 1) = 1;
422 return $mask;
423}
424
425sub register_categories
426{
427 my @names = @_;
428
429 for my $name (@names) {
430 if (! defined $Bits{$name}) {
431 $Bits{$name} = _mkMask($LAST_BIT);
432 vec($Bits{'all'}, $LAST_BIT, 1) = 1;
433 $Offsets{$name} = $LAST_BIT ++;
434 foreach my $k (keys %Bits) {
435 vec($Bits{$k}, $LAST_BIT, 1) = 0;
436 }
437 $DeadBits{$name} = _mkMask($LAST_BIT);
438 vec($DeadBits{'all'}, $LAST_BIT++, 1) = 1;
439 }
440 }
441}
442
443sub _error_loc {
444 require Carp;
445 goto &Carp::short_error_loc; # don't introduce another stack frame
446}
447
448sub enabled
449{
450 return __chk(NORMAL, @_);
451}
452
453sub fatal_enabled
454{
455 return __chk(FATAL, @_);
456}
457
458sub warn
459{
460 return __chk(FATAL | MESSAGE, @_);
461}
462
463sub warnif
464{
465 return __chk(NORMAL | FATAL | MESSAGE, @_);
466}
467
468# These are not part of any public interface, so we can delete them to save
469# space.
470delete @warnings::{qw(NORMAL FATAL MESSAGE)};
471
4721;
473__END__
599cee73
PM
474=head1 NAME
475
4438c4b7 476warnings - Perl pragma to control optional warnings
599cee73
PM
477
478=head1 SYNOPSIS
479
4438c4b7
JH
480 use warnings;
481 no warnings;
599cee73 482
4438c4b7
JH
483 use warnings "all";
484 no warnings "all";
599cee73 485
d3a7d8c7
GS
486 use warnings::register;
487 if (warnings::enabled()) {
488 warnings::warn("some warning");
489 }
490
491 if (warnings::enabled("void")) {
e476b1b5
GS
492 warnings::warn("void", "some warning");
493 }
494
7e6d00f8
PM
495 if (warnings::enabled($object)) {
496 warnings::warn($object, "some warning");
497 }
498
721f911b
PM
499 warnings::warnif("some warning");
500 warnings::warnif("void", "some warning");
501 warnings::warnif($object, "some warning");
7e6d00f8 502
599cee73
PM
503=head1 DESCRIPTION
504
a7f2b7af
RS
505The C<warnings> pragma gives control over which warnings are enabled in
506which parts of a Perl program. It's a more flexible alternative for
507both the command line flag B<-w> and the equivalent Perl variable,
508C<$^W>.
fe2e802c 509
a7f2b7af
RS
510This pragma works just like the C<strict> pragma.
511This means that the scope of the warning pragma is limited to the
512enclosing block. It also means that the pragma setting will not
513leak across files (via C<use>, C<require> or C<do>). This allows
514authors to independently define the degree of warning checks that will
515be applied to their module.
599cee73 516
a7f2b7af
RS
517By default, optional warnings are disabled, so any legacy code that
518doesn't attempt to control the warnings will work unchanged.
519
520All warnings are enabled in a block by either of these:
521
522 use warnings;
523 use warnings 'all';
524
525Similarly all warnings are disabled in a block by either of these:
526
527 no warnings;
528 no warnings 'all';
529
530For example, consider the code below:
531
532 use warnings;
533 my @a;
534 {
535 no warnings;
536 my $b = @a[0];
537 }
538 my $c = @a[0];
539
540The code in the enclosing block has warnings enabled, but the inner
541block has them disabled. In this case that means the assignment to the
542scalar C<$c> will trip the C<"Scalar value @a[0] better written as $a[0]">
543warning, but the assignment to the scalar C<$b> will not.
544
545=head2 Default Warnings and Optional Warnings
546
547Before the introduction of lexical warnings, Perl had two classes of
548warnings: mandatory and optional.
549
550As its name suggests, if your code tripped a mandatory warning, you
551would get a warning whether you wanted it or not.
552For example, the code below would always produce an C<"isn't numeric">
553warning about the "2:".
554
555 my $a = "2:" + 3;
556
557With the introduction of lexical warnings, mandatory warnings now become
558I<default> warnings. The difference is that although the previously
559mandatory warnings are still enabled by default, they can then be
560subsequently enabled or disabled with the lexical warning pragma. For
561example, in the code below, an C<"isn't numeric"> warning will only
562be reported for the C<$a> variable.
563
564 my $a = "2:" + 3;
565 no warnings;
566 my $b = "2:" + 3;
567
568Note that neither the B<-w> flag or the C<$^W> can be used to
569disable/enable default warnings. They are still mandatory in this case.
570
571=head2 What's wrong with B<-w> and C<$^W>
572
573Although very useful, the big problem with using B<-w> on the command
574line to enable warnings is that it is all or nothing. Take the typical
575scenario when you are writing a Perl program. Parts of the code you
576will write yourself, but it's very likely that you will make use of
577pre-written Perl modules. If you use the B<-w> flag in this case, you
578end up enabling warnings in pieces of code that you haven't written.
579
580Similarly, using C<$^W> to either disable or enable blocks of code is
581fundamentally flawed. For a start, say you want to disable warnings in
582a block of code. You might expect this to be enough to do the trick:
583
584 {
585 local ($^W) = 0;
586 my $a =+ 2;
587 my $b; chop $b;
588 }
589
590When this code is run with the B<-w> flag, a warning will be produced
591for the C<$a> line: C<"Reversed += operator">.
592
593The problem is that Perl has both compile-time and run-time warnings. To
594disable compile-time warnings you need to rewrite the code like this:
595
596 {
597 BEGIN { $^W = 0 }
598 my $a =+ 2;
599 my $b; chop $b;
600 }
601
602The other big problem with C<$^W> is the way you can inadvertently
603change the warning setting in unexpected places in your code. For example,
604when the code below is run (without the B<-w> flag), the second call
605to C<doit> will trip a C<"Use of uninitialized value"> warning, whereas
606the first will not.
607
608 sub doit
609 {
610 my $b; chop $b;
611 }
612
613 doit();
614
615 {
616 local ($^W) = 1;
617 doit()
618 }
619
620This is a side-effect of C<$^W> being dynamically scoped.
621
622Lexical warnings get around these limitations by allowing finer control
623over where warnings can or can't be tripped.
624
625=head2 Controlling Warnings from the Command Line
626
627There are three Command Line flags that can be used to control when
628warnings are (or aren't) produced:
629
630=over 5
631
632=item B<-w>
633X<-w>
634
635This is the existing flag. If the lexical warnings pragma is B<not>
636used in any of you code, or any of the modules that you use, this flag
637will enable warnings everywhere. See L<Backward Compatibility> for
638details of how this flag interacts with lexical warnings.
639
640=item B<-W>
641X<-W>
642
643If the B<-W> flag is used on the command line, it will enable all warnings
644throughout the program regardless of whether warnings were disabled
645locally using C<no warnings> or C<$^W =0>.
646This includes all files that get
647included via C<use>, C<require> or C<do>.
648Think of it as the Perl equivalent of the "lint" command.
649
650=item B<-X>
651X<-X>
652
653Does the exact opposite to the B<-W> flag, i.e. it disables all warnings.
654
655=back
656
657=head2 Backward Compatibility
658
659If you are used to working with a version of Perl prior to the
660introduction of lexically scoped warnings, or have code that uses both
661lexical warnings and C<$^W>, this section will describe how they interact.
662
663How Lexical Warnings interact with B<-w>/C<$^W>:
664
665=over 5
666
667=item 1.
668
669If none of the three command line flags (B<-w>, B<-W> or B<-X>) that
670control warnings is used and neither C<$^W> nor the C<warnings> pragma
671are used, then default warnings will be enabled and optional warnings
672disabled.
673This means that legacy code that doesn't attempt to control the warnings
674will work unchanged.
675
676=item 2.
677
678The B<-w> flag just sets the global C<$^W> variable as in 5.005. This
679means that any legacy code that currently relies on manipulating C<$^W>
680to control warning behavior will still work as is.
681
682=item 3.
683
684Apart from now being a boolean, the C<$^W> variable operates in exactly
685the same horrible uncontrolled global way, except that it cannot
686disable/enable default warnings.
687
688=item 4.
689
690If a piece of code is under the control of the C<warnings> pragma,
691both the C<$^W> variable and the B<-w> flag will be ignored for the
692scope of the lexical warning.
693
694=item 5.
695
696The only way to override a lexical warnings setting is with the B<-W>
697or B<-X> command line flags.
698
699=back
700
701The combined effect of 3 & 4 is that it will allow code which uses
702the C<warnings> pragma to control the warning behavior of $^W-type
703code (using a C<local $^W=0>) if it really wants to, but not vice-versa.
704
705=head2 Category Hierarchy
706X<warning, categories>
707
708A hierarchy of "categories" have been defined to allow groups of warnings
709to be enabled/disabled in isolation.
710
711The current hierarchy is:
712
713 all -+
714 |
715 +- closure
716 |
717 +- deprecated
718 |
719 +- exiting
720 |
721 +- experimental --+
722 | |
723 | +- experimental::autoderef
724 | |
725 | +- experimental::lexical_subs
726 | |
727 | +- experimental::lexical_topic
728 | |
f438dbf0
FC
729 | +- experimental::lvalue_refs
730 | |
a7f2b7af
RS
731 | +- experimental::postderef
732 | |
733 | +- experimental::regex_sets
734 | |
735 | +- experimental::signatures
736 | |
737 | +- experimental::smartmatch
7ac92924
TC
738 | |
739 | +- experimental::win32_perlio
a7f2b7af
RS
740 |
741 +- glob
742 |
743 +- imprecision
744 |
745 +- io ------------+
746 | |
747 | +- closed
748 | |
749 | +- exec
750 | |
751 | +- layer
752 | |
753 | +- newline
754 | |
755 | +- pipe
756 | |
757 | +- syscalls
758 | |
759 | +- unopened
760 |
761 +- misc
762 |
3664866e
AB
763 +- missing
764 |
a7f2b7af
RS
765 +- numeric
766 |
767 +- once
768 |
769 +- overflow
770 |
771 +- pack
772 |
773 +- portable
774 |
775 +- recursion
776 |
777 +- redefine
778 |
4077a6bc
AB
779 +- redundant
780 |
a7f2b7af
RS
781 +- regexp
782 |
783 +- severe --------+
784 | |
785 | +- debugging
786 | |
787 | +- inplace
788 | |
789 | +- internal
790 | |
791 | +- malloc
792 |
793 +- signal
794 |
795 +- substr
796 |
797 +- syntax --------+
798 | |
799 | +- ambiguous
800 | |
801 | +- bareword
802 | |
803 | +- digit
804 | |
805 | +- illegalproto
806 | |
807 | +- parenthesis
808 | |
809 | +- precedence
810 | |
811 | +- printf
812 | |
813 | +- prototype
814 | |
815 | +- qw
816 | |
817 | +- reserved
818 | |
819 | +- semicolon
820 |
821 +- taint
822 |
823 +- threads
824 |
825 +- uninitialized
826 |
827 +- unpack
828 |
829 +- untie
830 |
831 +- utf8 ----------+
832 | |
833 | +- non_unicode
834 | |
835 | +- nonchar
836 | |
837 | +- surrogate
838 |
839 +- void
840
841Just like the "strict" pragma any of these categories can be combined
842
843 use warnings qw(void redefine);
844 no warnings qw(io syntax untie);
845
846Also like the "strict" pragma, if there is more than one instance of the
847C<warnings> pragma in a given scope the cumulative effect is additive.
848
849 use warnings qw(void); # only "void" warnings enabled
850 ...
851 use warnings qw(io); # only "void" & "io" warnings enabled
852 ...
853 no warnings qw(void); # only "io" warnings enabled
854
855To determine which category a specific warning has been assigned to see
856L<perldiag>.
857
858Note: Before Perl 5.8.0, the lexical warnings category "deprecated" was a
859sub-category of the "syntax" category. It is now a top-level category
860in its own right.
861
3664866e
AB
862Note: Before 5.21.0, the "missing" lexical warnings category was
863internally defined to be the same as the "uninitialized" category. It
864is now a top-level category in its own right.
865
a7f2b7af
RS
866=head2 Fatal Warnings
867X<warning, fatal>
868
869The presence of the word "FATAL" in the category list will escalate any
870warnings detected from the categories specified in the lexical scope
871into fatal errors. In the code below, the use of C<time>, C<length>
872and C<join> can all produce a C<"Useless use of xxx in void context">
873warning.
874
875 use warnings;
876
877 time;
878
879 {
880 use warnings FATAL => qw(void);
881 length "abc";
882 }
883
884 join "", 1,2,3;
885
886 print "done\n";
887
888When run it produces this output
889
890 Useless use of time in void context at fatal line 3.
891 Useless use of length in void context at fatal line 7.
892
893The scope where C<length> is used has escalated the C<void> warnings
894category into a fatal error, so the program terminates immediately when it
895encounters the warning.
896
897To explicitly turn off a "FATAL" warning you just disable the warning
898it is associated with. So, for example, to disable the "void" warning
899in the example above, either of these will do the trick:
900
901 no warnings qw(void);
902 no warnings FATAL => qw(void);
903
904If you want to downgrade a warning that has been escalated into a fatal
905error back to a normal warning, you can use the "NONFATAL" keyword. For
906example, the code below will promote all warnings into fatal errors,
907except for those in the "syntax" category.
908
909 use warnings FATAL => 'all', NONFATAL => 'syntax';
910
911As of Perl 5.20, instead of C<< use warnings FATAL => 'all'; >> you can
912use:
913
914 use v5.20; # Perl 5.20 or greater is required for the following
915 use warnings 'FATAL'; # short form of "use warnings FATAL => 'all';"
916
917If you want your program to be compatible with versions of Perl before
9185.20, you must use C<< use warnings FATAL => 'all'; >> instead. (In
919previous versions of Perl, the behavior of the statements
920C<< use warnings 'FATAL'; >>, C<< use warnings 'NONFATAL'; >> and
921C<< no warnings 'FATAL'; >> was unspecified; they did not behave as if
922they included the C<< => 'all' >> portion. As of 5.20, they do.)
923
924B<NOTE:> Users of FATAL warnings, especially
925those using C<< FATAL => 'all' >>
926should be fully aware that they are risking future portability of their
927programs by doing so. Perl makes absolutely no commitments to not
928introduce new warnings, or warnings categories in the future, and indeed
929we explicitly reserve the right to do so. Code that may not warn now may
930warn in a future release of Perl if the Perl5 development team deems it
931in the best interests of the community to do so. Should code using FATAL
932warnings break due to the introduction of a new warning we will NOT
933consider it an incompatible change. Users of FATAL warnings should take
934special caution during upgrades to check to see if their code triggers
935any new warnings and should pay particular attention to the fine print of
936the documentation of the features they use to ensure they do not exploit
937features that are documented as risky, deprecated, or unspecified, or where
938the documentation says "so don't do that", or anything with the same sense
939and spirit. Use of such features in combination with FATAL warnings is
940ENTIRELY AT THE USER'S RISK.
941
942=head2 Reporting Warnings from a Module
943X<warning, reporting> X<warning, registering>
944
945The C<warnings> pragma provides a number of functions that are useful for
946module authors. These are used when you want to report a module-specific
947warning to a calling module has enabled warnings via the C<warnings>
948pragma.
949
950Consider the module C<MyMod::Abc> below.
951
952 package MyMod::Abc;
953
954 use warnings::register;
955
956 sub open {
957 my $path = shift;
958 if ($path !~ m#^/#) {
959 warnings::warn("changing relative path to /var/abc")
960 if warnings::enabled();
961 $path = "/var/abc/$path";
962 }
963 }
964
965 1;
966
967The call to C<warnings::register> will create a new warnings category
968called "MyMod::Abc", i.e. the new category name matches the current
969package name. The C<open> function in the module will display a warning
970message if it gets given a relative path as a parameter. This warnings
971will only be displayed if the code that uses C<MyMod::Abc> has actually
972enabled them with the C<warnings> pragma like below.
973
974 use MyMod::Abc;
975 use warnings 'MyMod::Abc';
976 ...
977 abc::open("../fred.txt");
978
979It is also possible to test whether the pre-defined warnings categories are
980set in the calling module with the C<warnings::enabled> function. Consider
981this snippet of code:
982
983 package MyMod::Abc;
984
985 sub open {
986 warnings::warnif("deprecated",
987 "open is deprecated, use new instead");
988 new(@_);
989 }
990
991 sub new
992 ...
993 1;
994
995The function C<open> has been deprecated, so code has been included to
996display a warning message whenever the calling module has (at least) the
997"deprecated" warnings category enabled. Something like this, say.
998
999 use warnings 'deprecated';
1000 use MyMod::Abc;
1001 ...
1002 MyMod::Abc::open($filename);
1003
1004Either the C<warnings::warn> or C<warnings::warnif> function should be
1005used to actually display the warnings message. This is because they can
1006make use of the feature that allows warnings to be escalated into fatal
1007errors. So in this case
1008
1009 use MyMod::Abc;
1010 use warnings FATAL => 'MyMod::Abc';
1011 ...
1012 MyMod::Abc::open('../fred.txt');
1013
1014the C<warnings::warnif> function will detect this and die after
1015displaying the warning message.
1016
1017The three warnings functions, C<warnings::warn>, C<warnings::warnif>
1018and C<warnings::enabled> can optionally take an object reference in place
1019of a category name. In this case the functions will use the class name
1020of the object as the warnings category.
1021
1022Consider this example:
1023
1024 package Original;
1025
1026 no warnings;
1027 use warnings::register;
1028
1029 sub new
1030 {
1031 my $class = shift;
1032 bless [], $class;
1033 }
1034
1035 sub check
effd17dc
DD
1036 {
1037 my $self = shift;
1038 my $value = shift;
e476b1b5 1039
effd17dc
DD
1040 if ($value % 2 && warnings::enabled($self))
1041 { warnings::warn($self, "Odd numbers are unsafe") }
1042 }
599cee73 1043
effd17dc
DD
1044 sub doit
1045 {
1046 my $self = shift;
1047 my $value = shift;
1048 $self->check($value);
1049 # ...
1050 }
599cee73 1051
effd17dc 1052 1;
0d658bf5 1053
effd17dc 1054 package Derived;
0d658bf5 1055
effd17dc
DD
1056 use warnings::register;
1057 use Original;
1058 our @ISA = qw( Original );
1059 sub new
1060 {
1061 my $class = shift;
1062 bless [], $class;
1063 }
b88df990 1064
b88df990 1065
effd17dc 1066 1;
8457b38f 1067
effd17dc
DD
1068The code below makes use of both modules, but it only enables warnings from
1069C<Derived>.
8457b38f 1070
effd17dc
DD
1071 use Original;
1072 use Derived;
1073 use warnings 'Derived';
1074 my $a = Original->new();
1075 $a->doit(1);
1076 my $b = Derived->new();
1077 $a->doit(1);
6f87cb12 1078
effd17dc
DD
1079When this code is run only the C<Derived> object, C<$b>, will generate
1080a warning.
6f87cb12 1081
effd17dc 1082 Odd numbers are unsafe at main.pl line 7
c8028aa6 1083
effd17dc
DD
1084Notice also that the warning is reported at the line where the object is first
1085used.
c8028aa6 1086
effd17dc
DD
1087When registering new categories of warning, you can supply more names to
1088warnings::register like this:
7ac92924 1089
effd17dc
DD
1090 package MyModule;
1091 use warnings::register qw(format precision);
7ac92924 1092
effd17dc 1093 ...
d3a7d8c7 1094
effd17dc 1095 warnings::warnif('MyModule::format', '...');
599cee73 1096
effd17dc 1097=head1 FUNCTIONS
599cee73 1098
effd17dc 1099=over 4
d3a7d8c7 1100
effd17dc 1101=item use warnings::register
599cee73 1102
effd17dc
DD
1103Creates a new warnings category with the same name as the package where
1104the call to the pragma is used.
c3186b65 1105
effd17dc 1106=item warnings::enabled()
6e9af7e4 1107
effd17dc 1108Use the warnings category with the same name as the current package.
599cee73 1109
effd17dc
DD
1110Return TRUE if that warnings category is enabled in the calling module.
1111Otherwise returns FALSE.
599cee73 1112
effd17dc 1113=item warnings::enabled($category)
4c02ac93 1114
effd17dc
DD
1115Return TRUE if the warnings category, C<$category>, is enabled in the
1116calling module.
1117Otherwise returns FALSE.
6e9af7e4 1118
effd17dc 1119=item warnings::enabled($object)
6e9af7e4 1120
effd17dc
DD
1121Use the name of the class for the object reference, C<$object>, as the
1122warnings category.
c91312d5 1123
effd17dc
DD
1124Return TRUE if that warnings category is enabled in the first scope
1125where the object is used.
1126Otherwise returns FALSE.
a7f2b7af 1127
effd17dc 1128=item warnings::fatal_enabled()
599cee73 1129
effd17dc
DD
1130Return TRUE if the warnings category with the same name as the current
1131package has been set to FATAL in the calling module.
1132Otherwise returns FALSE.
6e9af7e4 1133
effd17dc 1134=item warnings::fatal_enabled($category)
6e9af7e4 1135
effd17dc
DD
1136Return TRUE if the warnings category C<$category> has been set to FATAL in
1137the calling module.
1138Otherwise returns FALSE.
6e9af7e4 1139
effd17dc 1140=item warnings::fatal_enabled($object)
6e9af7e4 1141
effd17dc
DD
1142Use the name of the class for the object reference, C<$object>, as the
1143warnings category.
6e9af7e4 1144
effd17dc
DD
1145Return TRUE if that warnings category has been set to FATAL in the first
1146scope where the object is used.
1147Otherwise returns FALSE.
599cee73 1148
effd17dc 1149=item warnings::warn($message)
9df0f64f 1150
effd17dc 1151Print C<$message> to STDERR.
8787a747 1152
effd17dc 1153Use the warnings category with the same name as the current package.
96183d25 1154
effd17dc
DD
1155If that warnings category has been set to "FATAL" in the calling module
1156then die. Otherwise return.
96183d25 1157
effd17dc 1158=item warnings::warn($category, $message)
d3a7d8c7 1159
effd17dc 1160Print C<$message> to STDERR.
d3a7d8c7 1161
effd17dc
DD
1162If the warnings category, C<$category>, has been set to "FATAL" in the
1163calling module then die. Otherwise return.
7e6d00f8 1164
effd17dc 1165=item warnings::warn($object, $message)
7e6d00f8 1166
effd17dc 1167Print C<$message> to STDERR.
8787a747 1168
effd17dc
DD
1169Use the name of the class for the object reference, C<$object>, as the
1170warnings category.
8787a747 1171
effd17dc
DD
1172If that warnings category has been set to "FATAL" in the scope where C<$object>
1173is first used then die. Otherwise return.
96183d25 1174
96183d25 1175
effd17dc 1176=item warnings::warnif($message)
96183d25 1177
effd17dc 1178Equivalent to:
7e6d00f8 1179
effd17dc
DD
1180 if (warnings::enabled())
1181 { warnings::warn($message) }
572bfd36 1182
effd17dc 1183=item warnings::warnif($category, $message)
572bfd36 1184
effd17dc 1185Equivalent to:
572bfd36 1186
effd17dc
DD
1187 if (warnings::enabled($category))
1188 { warnings::warn($category, $message) }
572bfd36 1189
effd17dc 1190=item warnings::warnif($object, $message)
4f527b71 1191
effd17dc 1192Equivalent to:
599cee73 1193
effd17dc
DD
1194 if (warnings::enabled($object))
1195 { warnings::warn($object, $message) }
d3a7d8c7 1196
effd17dc 1197=item warnings::register_categories(@names)
e476b1b5 1198
effd17dc
DD
1199This registers warning categories for the given names and is primarily for
1200use by the warnings::register pragma.
0d658bf5 1201
effd17dc 1202=back
8787a747 1203
effd17dc
DD
1204See also L<perlmodlib/Pragmatic Modules> and L<perldiag>.
1205
1206=cut
ce716c52 1207
37442d52 1208# ex: set ro: