This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
https://perl5.git.perl.org / perl5.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Bump the perl version in various places for 5.37.8
[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
f8552c1a 8our $VERSION = "1.61";
f2c3e829
RGS		 9
10# Verify that we're called correctly so that warnings will work.
67ba812d
AP		 11# Can't use Carp, since Carp uses us!
12# String regexps because constant folding = smaller optree = less memory vs regexp literal
f2c3e829 13# see also strict.pm.
67ba812d
AP		 14die sprintf "Incorrect use of pragma '%s' at %s line %d.\n", __PACKAGE__, +(caller)[1,2]
15 if __FILE__ !~ ( '(?x) \b '.__PACKAGE__.' \.pmc? \z' )
16 && __FILE__ =~ ( '(?x) \b (?i:'.__PACKAGE__.') \.pmc? \z' );
0ca4541c 17
effd17dc 18our %Offsets = (
effd17dc 19 # Warnings Categories added in Perl 5.008
3c3f8cd6
AB		 20 'all' => 0,
21 'closure' => 2,
22 'deprecated' => 4,
23 'exiting' => 6,
24 'glob' => 8,
25 'io' => 10,
26 'closed' => 12,
27 'exec' => 14,
28 'layer' => 16,
29 'newline' => 18,
30 'pipe' => 20,
31 'unopened' => 22,
32 'misc' => 24,
33 'numeric' => 26,
34 'once' => 28,
35 'overflow' => 30,
36 'pack' => 32,
37 'portable' => 34,
38 'recursion' => 36,
39 'redefine' => 38,
40 'regexp' => 40,
41 'severe' => 42,
42 'debugging' => 44,
43 'inplace' => 46,
44 'internal' => 48,
45 'malloc' => 50,
46 'signal' => 52,
47 'substr' => 54,
48 'syntax' => 56,
49 'ambiguous' => 58,
50 'bareword' => 60,
51 'digit' => 62,
52 'parenthesis' => 64,
53 'precedence' => 66,
54 'printf' => 68,
55 'prototype' => 70,
56 'qw' => 72,
57 'reserved' => 74,
58 'semicolon' => 76,
59 'taint' => 78,
60 'threads' => 80,
61 'uninitialized' => 82,
62 'unpack' => 84,
63 'untie' => 86,
64 'utf8' => 88,
65 'void' => 90,
effd17dc
DD		 66
67 # Warnings Categories added in Perl 5.011
3c3f8cd6
AB		 68 'imprecision' => 92,
69 'illegalproto' => 94,
effd17dc
DD		 70
71 # Warnings Categories added in Perl 5.013
3c3f8cd6
AB		 72 'non_unicode' => 96,
73 'nonchar' => 98,
74 'surrogate' => 100,
effd17dc
DD		 75
76 # Warnings Categories added in Perl 5.017
3c3f8cd6 77 'experimental' => 102,
d7e8a031
PBB		 78 'experimental::regex_sets' => 104,
79 'experimental::smartmatch' => 106,
effd17dc
DD		 80
81 # Warnings Categories added in Perl 5.019
d7e8a031 82 'syscalls' => 108,
effd17dc
DD		 83
84 # Warnings Categories added in Perl 5.021
d7e8a031
PBB		 85 'experimental::const_attr' => 110,
86 'experimental::re_strict' => 112,
87 'experimental::refaliasing' => 114,
88 'locale' => 116,
89 'missing' => 118,
90 'redundant' => 120,
88d5dae9
FC		 91
92 # Warnings Categories added in Perl 5.025
d7e8a031 93 'experimental::declared_refs' => 122,
52e3acf8
Z		 94
95 # Warnings Categories added in Perl 5.027
d7e8a031 96 'shadow' => 124,
21c34e97
KW		 97
98 # Warnings Categories added in Perl 5.029
d7e8a031
PBB		 99 'experimental::private_use' => 126,
100 'experimental::uniprop_wildcards' => 128,
101 'experimental::vlb' => 130,
a1325b90
PE		 102
103 # Warnings Categories added in Perl 5.033
d7e8a031 104 'experimental::try' => 132,
f79e2ff9
PE		 105
106 # Warnings Categories added in Perl 5.035
d7e8a031
PBB		 107 'experimental::args_array_with_signatures'=> 134,
108 'experimental::builtin' => 136,
109 'experimental::defer' => 138,
110 'experimental::extra_paired_delimiters'=> 140,
111 'experimental::for_list' => 142,
112 'scalar' => 144,
3c3f8cd6 113);
effd17dc
DD		 114
115our %Bits = (
d7e8a031
PBB		 116 'all' => "\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55", # [0..75]
117 'ambiguous' => "\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [29]
118 'bareword' => "\x00\x00\x00\x00\x00\x00\x00\x10\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [30]
119 'closed' => "\x00\x10\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [6]
120 'closure' => "\x04\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [1]
121 'debugging' => "\x00\x00\x00\x00\x00\x10\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [22]
122 'deprecated' => "\x10\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [2]
123 'digit' => "\x00\x00\x00\x00\x00\x00\x00\x40\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [31]
124 'exec' => "\x00\x40\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [7]
125 'exiting' => "\x40\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [3]
126 'experimental' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x40\x45\x05\x44\x55\x55\x00", # [51..53,55..57,61,63..71]
127 'experimental::args_array_with_signatures'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x40\x00\x00", # [67]
128 'experimental::builtin' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00", # [68]
129 'experimental::const_attr' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x40\x00\x00\x00\x00\x00", # [55]
130 'experimental::declared_refs' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00\x00", # [61]
131 'experimental::defer' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00", # [69]
132 'experimental::extra_paired_delimiters'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x10\x00", # [70]
133 'experimental::for_list' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x40\x00", # [71]
134 'experimental::private_use' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x40\x00\x00\x00", # [63]
135 'experimental::re_strict' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00", # [56]
136 'experimental::refaliasing' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00\x00\x00", # [57]
137 'experimental::regex_sets' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00", # [52]
138 'experimental::smartmatch' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00\x00\x00\x00", # [53]
139 'experimental::try' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x10\x00\x00", # [66]
140 'experimental::uniprop_wildcards' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00", # [64]
141 'experimental::vlb' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00", # [65]
142 'glob' => "\x00\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [4]
143 'illegalproto' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x40\x00\x00\x00\x00\x00\x00\x00", # [47]
144 'imprecision' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x10\x00\x00\x00\x00\x00\x00\x00", # [46]
145 'inplace' => "\x00\x00\x00\x00\x00\x40\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [23]
146 'internal' => "\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [24]
147 'io' => "\x00\x54\x55\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x10\x00\x00\x00\x00\x00", # [5..11,54]
148 'layer' => "\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [8]
149 'locale' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x10\x00\x00\x00\x00", # [58]
150 'malloc' => "\x00\x00\x00\x00\x00\x00\x04\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [25]
151 'misc' => "\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [12]
152 'missing' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x40\x00\x00\x00\x00", # [59]
153 'newline' => "\x00\x00\x04\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [9]
154 'non_unicode' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00", # [48]
155 'nonchar' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00\x00\x00\x00\x00", # [49]
156 'numeric' => "\x00\x00\x00\x04\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [13]
157 'once' => "\x00\x00\x00\x10\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [14]
158 'overflow' => "\x00\x00\x00\x40\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [15]
159 'pack' => "\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [16]
160 'parenthesis' => "\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [32]
161 'pipe' => "\x00\x00\x10\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [10]
162 'portable' => "\x00\x00\x00\x00\x04\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [17]
163 'precedence' => "\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [33]
164 'printf' => "\x00\x00\x00\x00\x00\x00\x00\x00\x10\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [34]
165 'prototype' => "\x00\x00\x00\x00\x00\x00\x00\x00\x40\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [35]
166 'qw' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [36]
167 'recursion' => "\x00\x00\x00\x00\x10\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [18]
168 'redefine' => "\x00\x00\x00\x00\x40\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [19]
169 'redundant' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00", # [60]
170 'regexp' => "\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [20]
171 'reserved' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [37]
172 'scalar' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01", # [72]
173 'semicolon' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x10\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [38]
174 'severe' => "\x00\x00\x00\x00\x00\x54\x05\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [21..25]
175 'shadow' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x10\x00\x00\x00", # [62]
176 'signal' => "\x00\x00\x00\x00\x00\x00\x10\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [26]
177 'substr' => "\x00\x00\x00\x00\x00\x00\x40\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [27]
178 'surrogate' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x10\x00\x00\x00\x00\x00\x00", # [50]
179 'syntax' => "\x00\x00\x00\x00\x00\x00\x00\x55\x55\x15\x00\x40\x00\x00\x00\x00\x00\x00\x00", # [28..38,47]
180 'syscalls' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x10\x00\x00\x00\x00\x00", # [54]
181 'taint' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x40\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [39]
182 'threads' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x00", # [40]
183 'uninitialized' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00\x00\x00\x00\x00\x00\x00", # [41]
184 'unopened' => "\x00\x00\x40\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [11]
185 'unpack' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x10\x00\x00\x00\x00\x00\x00\x00\x00", # [42]
186 'untie' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x40\x00\x00\x00\x00\x00\x00\x00\x00", # [43]
187 'utf8' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x15\x00\x00\x00\x00\x00\x00", # [44,48..50]
188 'void' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00\x00\x00\x00\x00\x00", # [45]
3c3f8cd6 189);
effd17dc
DD		 190
191our %DeadBits = (
d7e8a031
PBB		 192 'all' => "\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa", # [0..75]
193 'ambiguous' => "\x00\x00\x00\x00\x00\x00\x00\x08\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [29]
194 'bareword' => "\x00\x00\x00\x00\x00\x00\x00\x20\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [30]
195 'closed' => "\x00\x20\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [6]
196 'closure' => "\x08\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [1]
197 'debugging' => "\x00\x00\x00\x00\x00\x20\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [22]
198 'deprecated' => "\x20\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [2]
199 'digit' => "\x00\x00\x00\x00\x00\x00\x00\x80\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [31]
200 'exec' => "\x00\x80\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [7]
201 'exiting' => "\x80\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [3]
202 'experimental' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80\x8a\x0a\x88\xaa\xaa\x00", # [51..53,55..57,61,63..71]
203 'experimental::args_array_with_signatures'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80\x00\x00", # [67]
204 'experimental::builtin' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00", # [68]
205 'experimental::const_attr' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80\x00\x00\x00\x00\x00", # [55]
206 'experimental::declared_refs' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x08\x00\x00\x00", # [61]
207 'experimental::defer' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x08\x00", # [69]
208 'experimental::extra_paired_delimiters'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x20\x00", # [70]
209 'experimental::for_list' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80\x00", # [71]
210 'experimental::private_use' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80\x00\x00\x00", # [63]
211 'experimental::re_strict' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x00\x00\x00", # [56]
212 'experimental::refaliasing' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x08\x00\x00\x00\x00", # [57]
213 'experimental::regex_sets' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x00\x00\x00\x00", # [52]
214 'experimental::smartmatch' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x08\x00\x00\x00\x00\x00", # [53]
215 'experimental::try' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x20\x00\x00", # [66]
216 'experimental::uniprop_wildcards' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x00", # [64]
217 'experimental::vlb' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x08\x00\x00", # [65]
218 'glob' => "\x00\x02\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [4]
219 'illegalproto' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80\x00\x00\x00\x00\x00\x00\x00", # [47]
220 'imprecision' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x20\x00\x00\x00\x00\x00\x00\x00", # [46]
221 'inplace' => "\x00\x00\x00\x00\x00\x80\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [23]
222 'internal' => "\x00\x00\x00\x00\x00\x00\x02\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [24]
223 'io' => "\x00\xa8\xaa\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x20\x00\x00\x00\x00\x00", # [5..11,54]
224 'layer' => "\x00\x00\x02\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [8]
225 'locale' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x20\x00\x00\x00\x00", # [58]
226 'malloc' => "\x00\x00\x00\x00\x00\x00\x08\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [25]
227 'misc' => "\x00\x00\x00\x02\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [12]
228 'missing' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80\x00\x00\x00\x00", # [59]
229 'newline' => "\x00\x00\x08\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [9]
230 'non_unicode' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x00\x00\x00\x00\x00", # [48]
231 'nonchar' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x08\x00\x00\x00\x00\x00\x00", # [49]
232 'numeric' => "\x00\x00\x00\x08\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [13]
233 'once' => "\x00\x00\x00\x20\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [14]
234 'overflow' => "\x00\x00\x00\x80\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [15]
235 'pack' => "\x00\x00\x00\x00\x02\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [16]
236 'parenthesis' => "\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [32]
237 'pipe' => "\x00\x00\x20\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [10]
238 'portable' => "\x00\x00\x00\x00\x08\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [17]
239 'precedence' => "\x00\x00\x00\x00\x00\x00\x00\x00\x08\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [33]
240 'printf' => "\x00\x00\x00\x00\x00\x00\x00\x00\x20\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [34]
241 'prototype' => "\x00\x00\x00\x00\x00\x00\x00\x00\x80\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [35]
242 'qw' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [36]
243 'recursion' => "\x00\x00\x00\x00\x20\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [18]
244 'redefine' => "\x00\x00\x00\x00\x80\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [19]
245 'redundant' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x00\x00", # [60]
246 'regexp' => "\x00\x00\x00\x00\x00\x02\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [20]
247 'reserved' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x08\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [37]
248 'scalar' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02", # [72]
249 'semicolon' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x20\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [38]
250 'severe' => "\x00\x00\x00\x00\x00\xa8\x0a\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [21..25]
251 'shadow' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x20\x00\x00\x00", # [62]
252 'signal' => "\x00\x00\x00\x00\x00\x00\x20\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [26]
253 'substr' => "\x00\x00\x00\x00\x00\x00\x80\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [27]
254 'surrogate' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x20\x00\x00\x00\x00\x00\x00", # [50]
255 'syntax' => "\x00\x00\x00\x00\x00\x00\x00\xaa\xaa\x2a\x00\x80\x00\x00\x00\x00\x00\x00\x00", # [28..38,47]
256 'syscalls' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x20\x00\x00\x00\x00\x00", # [54]
257 'taint' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [39]
258 'threads' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x00\x00\x00\x00\x00\x00\x00", # [40]
259 'uninitialized' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x08\x00\x00\x00\x00\x00\x00\x00\x00", # [41]
260 'unopened' => "\x00\x00\x80\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [11]
261 'unpack' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x20\x00\x00\x00\x00\x00\x00\x00\x00", # [42]
262 'untie' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80\x00\x00\x00\x00\x00\x00\x00\x00", # [43]
263 'utf8' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x2a\x00\x00\x00\x00\x00\x00", # [44,48..50]
264 'void' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x08\x00\x00\x00\x00\x00\x00\x00", # [45]
265);
266
267our %NoOp = (
268 'experimental::alpha_assertions' => 1,
269 'experimental::bitwise' => 1,
270 'experimental::isa' => 1,
271 'experimental::lexical_subs' => 1,
272 'experimental::postderef' => 1,
273 'experimental::script_run' => 1,
274 'experimental::signatures' => 1,
3c3f8cd6
AB		 275);
276
277# These are used by various things, including our own tests
d7e8a031
PBB		 278our $NONE = "\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0";
279our $DEFAULT = "\x10\x01\x00\x00\x00\x50\x04\x00\x00\x00\x00\x00\x00\x44\x15\x44\x55\x55\x00"; # [2,4,22,23,25,53,55..58,61,63..71]
280our $LAST_BIT = 146 ;
281our $BYTES = 19 ;
3c3f8cd6 282
effd17dc
DD		 283sub Croaker
284{
285 require Carp; # this initializes %CarpInternal
286 local $Carp::CarpInternal{'warnings'};
287 delete $Carp::CarpInternal{'warnings'};
288 Carp::croak(@_);
289}
290
006c1a1d
Z		 291sub _expand_bits {
292 my $bits = shift;
293 my $want_len = ($LAST_BIT + 7) >> 3;
294 my $len = length($bits);
295 if ($len != $want_len) {
9824c081
MS		 296 if ($bits eq "") {
297 $bits = "\x00" x $want_len;
298 } elsif ($len > $want_len) {
299 substr $bits, $want_len, $len-$want_len, "";
300 } else {
301 my $x = vec($bits, $Offsets{all} >> 1, 2);
302 $x |= $x << 2;
303 $x |= $x << 4;
304 $bits .= chr($x) x ($want_len - $len);
305 }
006c1a1d
Z		 306 }
307 return $bits;
308}
309
effd17dc
DD		 310sub _bits {
311 my $mask = shift ;
312 my $catmask ;
313 my $fatal = 0 ;
314 my $no_fatal = 0 ;
315
006c1a1d 316 $mask = _expand_bits($mask);
effd17dc 317 foreach my $word ( @_ ) {
d7e8a031 318 next if $NoOp{$word};
9824c081
MS		 319 if ($word eq 'FATAL') {
320 $fatal = 1;
321 $no_fatal = 0;
322 }
323 elsif ($word eq 'NONFATAL') {
324 $fatal = 0;
325 $no_fatal = 1;
326 }
327 elsif ($catmask = $Bits{$word}) {
328 $mask |= $catmask ;
329 $mask |= $DeadBits{$word} if $fatal ;
330 $mask = ~(~$mask | $DeadBits{$word}) if $no_fatal ;
331 }
332 else
333 { Croaker("Unknown warnings category '$word'")}
effd17dc
DD		 334 }
335
336 return $mask ;
337}
338
339sub bits
340{
341 # called from B::Deparse.pm
342 push @_, 'all' unless @_ ;
006c1a1d 343 return _bits("", @_) ;
effd17dc
DD		 344}
345
346sub import
347{
e926558e 348 my $invocant = shift;
effd17dc 349
006c1a1d
Z		 350 # append 'all' when implied (empty import list or after a lone
351 # "FATAL" or "NONFATAL")
352 push @_, 'all'
e926558e
DC		 353 if !@_ || (@_==1 && ($_[0] eq 'FATAL' || $_[0] eq 'NONFATAL'));
354
355 my @fatal = ();
356 foreach my $warning (@_) {
357 if($warning =~ /^(NON)?FATAL$/) {
358 @fatal = ($warning);
359 } elsif(substr($warning, 0, 1) ne '-') {
360 my $mask = ${^WARNING_BITS} // ($^W ? $Bits{all} : $DEFAULT) ;
361 ${^WARNING_BITS} = _bits($mask, @fatal, $warning);
362 } else {
363 $invocant->unimport(substr($warning, 1));
364 }
365 }
effd17dc
DD		 366}
367
368sub unimport
369{
370 shift;
371
372 my $catmask ;
373 my $mask = ${^WARNING_BITS} // ($^W ? $Bits{all} : $DEFAULT) ;
374
effd17dc
DD		 375 # append 'all' when implied (empty import list or after a lone "FATAL")
376 push @_, 'all' if !@_ || @_==1 && $_[0] eq 'FATAL';
377
006c1a1d 378 $mask = _expand_bits($mask);
effd17dc 379 foreach my $word ( @_ ) {
d7e8a031 380 next if $NoOp{$word};
9824c081
MS		 381 if ($word eq 'FATAL') {
382 next;
383 }
384 elsif ($catmask = $Bits{$word}) {
385 $mask = ~(~$mask | $catmask | $DeadBits{$word});
386 }
387 else
388 { Croaker("Unknown warnings category '$word'")}
effd17dc
DD		 389 }
390
391 ${^WARNING_BITS} = $mask ;
392}
393
394my %builtin_type; @builtin_type{qw(SCALAR ARRAY HASH CODE REF GLOB LVALUE Regexp)} = ();
395
c4583f59 396sub LEVEL () { 8 };
effd17dc
DD		 397sub MESSAGE () { 4 };
398sub FATAL () { 2 };
399sub NORMAL () { 1 };
400
401sub __chk
402{
403 my $category ;
404 my $offset ;
405 my $isobj = 0 ;
406 my $wanted = shift;
407 my $has_message = $wanted & MESSAGE;
c4583f59
FC		 408 my $has_level = $wanted & LEVEL ;
409
410 if ($has_level) {
9824c081
MS		 411 if (@_ != ($has_message ? 3 : 2)) {
412 my $sub = (caller 1)[3];
413 my $syntax = $has_message
414 ? "category, level, 'message'"
415 : 'category, level';
416 Croaker("Usage: $sub($syntax)");
c4583f59
FC		 417 }
418 }
419 elsif (not @_ == 1 || @_ == ($has_message ? 2 : 0)) {
9824c081
MS		 420 my $sub = (caller 1)[3];
421 my $syntax = $has_message ? "[category,] 'message'" : '[category]';
422 Croaker("Usage: $sub($syntax)");
effd17dc
DD		 423 }
424
425 my $message = pop if $has_message;
426
427 if (@_) {
9824c081
MS		 428 # check the category supplied.
429 $category = shift ;
430 if (my $type = ref $category) {
431 Croaker("not an object")
432 if exists $builtin_type{$type};
433 $category = $type;
434 $isobj = 1 ;
435 }
436 $offset = $Offsets{$category};
437 Croaker("Unknown warnings category '$category'")
438 unless defined $offset;
effd17dc
DD		 439 }
440 else {
9824c081
MS		 441 $category = (caller(1))[0] ;
442 $offset = $Offsets{$category};
443 Croaker("package '$category' not registered for warnings")
444 unless defined $offset ;
effd17dc
DD		 445 }
446
447 my $i;
448
449 if ($isobj) {
9824c081
MS		 450 my $pkg;
451 $i = 2;
452 while (do { { package DB; $pkg = (caller($i++))[0] } } ) {
453 last unless @DB::args && $DB::args[0] =~ /^$category=/ ;
454 }
455 $i -= 2 ;
effd17dc 456 }
c4583f59 457 elsif ($has_level) {
9824c081 458 $i = 2 + shift;
c4583f59 459 }
effd17dc 460 else {
9824c081 461 $i = _error_loc(); # see where Carp will allocate the error
effd17dc
DD		 462 }
463
464 # Default to 0 if caller returns nothing. Default to $DEFAULT if it
465 # explicitly returns undef.
466 my(@callers_bitmask) = (caller($i))[9] ;
467 my $callers_bitmask =
9824c081 468 @callers_bitmask ? $callers_bitmask[0] // $DEFAULT : 0 ;
006c1a1d 469 length($callers_bitmask) > ($offset >> 3) or $offset = $Offsets{all};
effd17dc
DD		 470
471 my @results;
472 foreach my $type (FATAL, NORMAL) {
9824c081 473 next unless $wanted & $type;
effd17dc 474
9824c081 475 push @results, vec($callers_bitmask, $offset + $type - 1, 1);
effd17dc
DD		 476 }
477
478 # &enabled and &fatal_enabled
479 return $results[0] unless $has_message;
480
481 # &warnif, and the category is neither enabled as warning nor as fatal
c4583f59 482 return if ($wanted & (NORMAL | FATAL | MESSAGE))
9824c081
MS		 483 == (NORMAL | FATAL | MESSAGE)
484 && !($results[0] || $results[1]);
effd17dc 485
c4583f59
FC		 486 # If we have an explicit level, bypass Carp.
487 if ($has_level and @callers_bitmask) {
9824c081
MS		 488 # logic copied from util.c:mess_sv
489 my $stuff = " at " . join " line ", (caller $i)[1,2];
490 $stuff .= sprintf ", <%s> %s %d",
491 *${^LAST_FH}{NAME},
492 ($/ eq "\n" ? "line" : "chunk"), $.
493 if $. && ${^LAST_FH};
494 die "$message$stuff.\n" if $results[0];
495 return warn "$message$stuff.\n";
c4583f59
FC		 496 }
497
effd17dc
DD		 498 require Carp;
499 Carp::croak($message) if $results[0];
500 # will always get here for &warn. will only get here for &warnif if the
501 # category is enabled
502 Carp::carp($message);
503}
504
505sub _mkMask
506{
507 my ($bit) = @_;
508 my $mask = "";
509
510 vec($mask, $bit, 1) = 1;
511 return $mask;
512}
513
514sub register_categories
515{
516 my @names = @_;
517
518 for my $name (@names) {
9824c081
MS		 519 if (! defined $Bits{$name}) {
520 $Offsets{$name} = $LAST_BIT;
521 $Bits{$name} = _mkMask($LAST_BIT++);
522 $DeadBits{$name} = _mkMask($LAST_BIT++);
523 if (length($Bits{$name}) > length($Bits{all})) {
524 $Bits{all} .= "\x55";
525 $DeadBits{all} .= "\xaa";
526 }
527 }
effd17dc
DD		 528 }
529}
530
531sub _error_loc {
532 require Carp;
533 goto &Carp::short_error_loc; # don't introduce another stack frame
534}
535
536sub enabled
537{
538 return __chk(NORMAL, @_);
539}
540
541sub fatal_enabled
542{
543 return __chk(FATAL, @_);
544}
545
546sub warn
547{
548 return __chk(FATAL | MESSAGE, @_);
549}
550
551sub warnif
552{
553 return __chk(NORMAL | FATAL | MESSAGE, @_);
554}
555
c4583f59
FC		 556sub enabled_at_level
557{
558 return __chk(NORMAL | LEVEL, @_);
559}
560
561sub fatal_enabled_at_level
562{
563 return __chk(FATAL | LEVEL, @_);
564}
565
566sub warn_at_level
567{
568 return __chk(FATAL | MESSAGE | LEVEL, @_);
569}
570
571sub warnif_at_level
572{
573 return __chk(NORMAL | FATAL | MESSAGE | LEVEL, @_);
574}
575
effd17dc
DD		 576# These are not part of any public interface, so we can delete them to save
577# space.
c4583f59 578delete @warnings::{qw(NORMAL FATAL MESSAGE LEVEL)};
effd17dc
DD		 579
5801;
581__END__
4bbd41f5 582
599cee73
PM		 583=head1 NAME
584
4438c4b7 585warnings - Perl pragma to control optional warnings
599cee73
PM		 586
587=head1 SYNOPSIS
588
4438c4b7
JH		 589 use warnings;
590 no warnings;
599cee73 591
1c3cfd87
BC		 592 # Standard warnings are enabled by use v5.35 or above
593 use v5.35;
594
4438c4b7 595 use warnings "all";
e926558e
DC		 596 no warnings "uninitialized";
597
598 # or equivalent to those last two ...
599 use warnings qw(all -uninitialized);
599cee73 600
d3a7d8c7
GS		 601 use warnings::register;
602 if (warnings::enabled()) {
603 warnings::warn("some warning");
604 }
605
606 if (warnings::enabled("void")) {
e476b1b5
GS		 607 warnings::warn("void", "some warning");
608 }
609
7e6d00f8
PM		 610 if (warnings::enabled($object)) {
611 warnings::warn($object, "some warning");
612 }
613
721f911b
PM		 614 warnings::warnif("some warning");
615 warnings::warnif("void", "some warning");
616 warnings::warnif($object, "some warning");
7e6d00f8 617
599cee73
PM		 618=head1 DESCRIPTION
619
a7f2b7af
RS		 620The C<warnings> pragma gives control over which warnings are enabled in
621which parts of a Perl program. It's a more flexible alternative for
622both the command line flag B<-w> and the equivalent Perl variable,
623C<$^W>.
fe2e802c 624
a7f2b7af
RS		 625This pragma works just like the C<strict> pragma.
626This means that the scope of the warning pragma is limited to the
627enclosing block. It also means that the pragma setting will not
628leak across files (via C<use>, C<require> or C<do>). This allows
629authors to independently define the degree of warning checks that will
630be applied to their module.
599cee73 631
a7f2b7af
RS		 632By default, optional warnings are disabled, so any legacy code that
633doesn't attempt to control the warnings will work unchanged.
634
3c3f8cd6 635All warnings are enabled in a block by either of these:
a7f2b7af
RS		 636
637 use warnings;
638 use warnings 'all';
639
3c3f8cd6 640Similarly all warnings are disabled in a block by either of these:
a7f2b7af
RS		 641
642 no warnings;
643 no warnings 'all';
644
645For example, consider the code below:
646
647 use warnings;
573a192d 648 my @x;
a7f2b7af
RS		 649 {
650 no warnings;
9824c081 651 my $y = @x[0];
a7f2b7af 652 }
573a192d 653 my $z = @x[0];
a7f2b7af
RS		 654
655The code in the enclosing block has warnings enabled, but the inner
656block has them disabled. In this case that means the assignment to the
cd2e5170 657scalar C<$z> will trip the C<"Scalar value @x[0] better written as $x[0]">
573a192d 658warning, but the assignment to the scalar C<$y> will not.
a7f2b7af 659
1c3cfd87
BC		 660All warnings are enabled automatically within the scope of
661a C<L<use v5.35|perlfunc/use VERSION>> (or higher) declaration.
662
a7f2b7af
RS		 663=head2 Default Warnings and Optional Warnings
664
665Before the introduction of lexical warnings, Perl had two classes of
56873d42 666warnings: mandatory and optional.
a7f2b7af
RS		 667
668As its name suggests, if your code tripped a mandatory warning, you
669would get a warning whether you wanted it or not.
670For example, the code below would always produce an C<"isn't numeric">
671warning about the "2:".
672
573a192d 673 my $x = "2:" + 3;
a7f2b7af
RS		 674
675With the introduction of lexical warnings, mandatory warnings now become
676I<default> warnings. The difference is that although the previously
677mandatory warnings are still enabled by default, they can then be
678subsequently enabled or disabled with the lexical warning pragma. For
679example, in the code below, an C<"isn't numeric"> warning will only
573a192d 680be reported for the C<$x> variable.
a7f2b7af 681
573a192d 682 my $x = "2:" + 3;
a7f2b7af 683 no warnings;
573a192d 684 my $y = "2:" + 3;
a7f2b7af
RS		 685
686Note that neither the B<-w> flag or the C<$^W> can be used to
687disable/enable default warnings. They are still mandatory in this case.
688
e926558e
DC		 689=head2 "Negative warnings"
690
691As a convenience, you can (as of Perl 5.34) pass arguments to the
692C<import()> method both positively and negatively. Negative warnings
693are those with a C<-> sign prepended to their names; positive warnings
694are anything else. This lets you turn on some warnings and turn off
695others in one command. So, assuming that you've already turned on a
696bunch of warnings but want to tweak them a bit in some block, you can
697do this:
698
699 {
700 use warnings qw(uninitialized -redefine);
701 ...
702 }
703
704which is equivalent to:
705
706 {
707 use warnings qw(uninitialized);
708 no warnings qw(redefine);
709 ...
710 }
711
712The argument list is processed in the order you specify. So, for example, if you
713don't want to be warned about use of experimental features, except for C<somefeature>
714that you really dislike, you can say this:
715
716 use warnings qw(all -experimental experimental::somefeature);
717
718which is equivalent to:
719
720 use warnings 'all';
721 no warnings 'experimental';
722 use warnings 'experimental::somefeature';
723
d7e8a031
PBB		 724As experimental features become regular features of Perl,
725the corresponding warnings are not printed anymore.
726They also stop being listed in the L</Category Hierarchy> below.
727
728It is still possible to request turning on or off these warnings,
729but doing so has no effect.
730
a7f2b7af
RS		 731=head2 What's wrong with B<-w> and C<$^W>
732
733Although very useful, the big problem with using B<-w> on the command
734line to enable warnings is that it is all or nothing. Take the typical
735scenario when you are writing a Perl program. Parts of the code you
736will write yourself, but it's very likely that you will make use of
737pre-written Perl modules. If you use the B<-w> flag in this case, you
738end up enabling warnings in pieces of code that you haven't written.
739
740Similarly, using C<$^W> to either disable or enable blocks of code is
741fundamentally flawed. For a start, say you want to disable warnings in
742a block of code. You might expect this to be enough to do the trick:
743
744 {
745 local ($^W) = 0;
9824c081
MS		 746 my $x =+ 2;
747 my $y; chop $y;
a7f2b7af
RS		 748 }
749
750When this code is run with the B<-w> flag, a warning will be produced
573a192d 751for the C<$x> line: C<"Reversed += operator">.
a7f2b7af
RS		 752
753The problem is that Perl has both compile-time and run-time warnings. To
754disable compile-time warnings you need to rewrite the code like this:
755
756 {
757 BEGIN { $^W = 0 }
9824c081
MS		 758 my $x =+ 2;
759 my $y; chop $y;
a7f2b7af
RS		 760 }
761
45f87e65
DB		 762And note that unlike the first example, this will permanently set C<$^W>
763since it cannot both run during compile-time and be localized to a
764run-time block.
765
a7f2b7af
RS		 766The other big problem with C<$^W> is the way you can inadvertently
767change the warning setting in unexpected places in your code. For example,
768when the code below is run (without the B<-w> flag), the second call
769to C<doit> will trip a C<"Use of uninitialized value"> warning, whereas
770the first will not.
771
772 sub doit
773 {
573a192d 774 my $y; chop $y;
a7f2b7af
RS		 775 }
776
777 doit();
778
779 {
780 local ($^W) = 1;
781 doit()
782 }
783
784This is a side-effect of C<$^W> being dynamically scoped.
785
786Lexical warnings get around these limitations by allowing finer control
787over where warnings can or can't be tripped.
788
789=head2 Controlling Warnings from the Command Line
790
791There are three Command Line flags that can be used to control when
792warnings are (or aren't) produced:
793
794=over 5
795
796=item B<-w>
797X<-w>
798
799This is the existing flag. If the lexical warnings pragma is B<not>
677f8b87 800used in any of your code, or any of the modules that you use, this flag
05a64c17 801will enable warnings everywhere. See L</Backward Compatibility> for
a7f2b7af
RS		 802details of how this flag interacts with lexical warnings.
803
804=item B<-W>
805X<-W>
806
3c3f8cd6 807If the B<-W> flag is used on the command line, it will enable all warnings
a7f2b7af
RS		 808throughout the program regardless of whether warnings were disabled
809locally using C<no warnings> or C<$^W =0>.
810This includes all files that get
811included via C<use>, C<require> or C<do>.
812Think of it as the Perl equivalent of the "lint" command.
813
814=item B<-X>
815X<-X>
816
3c3f8cd6 817Does the exact opposite to the B<-W> flag, i.e. it disables all warnings.
ea5519d6
AB		 818
819=back
820
a7f2b7af
RS		 821=head2 Backward Compatibility
822
823If you are used to working with a version of Perl prior to the
824introduction of lexically scoped warnings, or have code that uses both
825lexical warnings and C<$^W>, this section will describe how they interact.
826
827How Lexical Warnings interact with B<-w>/C<$^W>:
828
829=over 5
830
831=item 1.
832
833If none of the three command line flags (B<-w>, B<-W> or B<-X>) that
834control warnings is used and neither C<$^W> nor the C<warnings> pragma
835are used, then default warnings will be enabled and optional warnings
836disabled.
837This means that legacy code that doesn't attempt to control the warnings
838will work unchanged.
839
840=item 2.
841
842The B<-w> flag just sets the global C<$^W> variable as in 5.005. This
843means that any legacy code that currently relies on manipulating C<$^W>
56873d42 844to control warning behavior will still work as is.
a7f2b7af
RS		 845
846=item 3.
847
848Apart from now being a boolean, the C<$^W> variable operates in exactly
849the same horrible uncontrolled global way, except that it cannot
850disable/enable default warnings.
851
852=item 4.
853
854If a piece of code is under the control of the C<warnings> pragma,
855both the C<$^W> variable and the B<-w> flag will be ignored for the
856scope of the lexical warning.
857
858=item 5.
859
860The only way to override a lexical warnings setting is with the B<-W>
861or B<-X> command line flags.
862
863=back
864
865The combined effect of 3 & 4 is that it will allow code which uses
866the C<warnings> pragma to control the warning behavior of $^W-type
867code (using a C<local $^W=0>) if it really wants to, but not vice-versa.
868
869=head2 Category Hierarchy
870X<warning, categories>
871
872A hierarchy of "categories" have been defined to allow groups of warnings
873to be enabled/disabled in isolation.
874
875The current hierarchy is:
876
3c3f8cd6
AB		 877 all -+
878 |
879 +- closure
880 |
881 +- deprecated
882 |
883 +- exiting
884 |
885 +- experimental --+
886 | |
1c547c3e
PE		 887 | +- experimental::args_array_with_signatures
888 | |
59802880
PE		 889 | +- experimental::builtin
890 | |
3c3f8cd6
AB		 891 | +- experimental::const_attr
892 | |
88d5dae9
FC		 893 | +- experimental::declared_refs
894 | |
f79e2ff9
PE		 895 | +- experimental::defer
896 | |
9c9853e8
KW		 897 | +- experimental::extra_paired_delimiters
898 | |
3b54923c
NC		 899 | +- experimental::for_list
900 | |
21c34e97
KW		 901 | +- experimental::private_use
902 | |
3c3f8cd6
AB		 903 | +- experimental::re_strict
904 | |
905 | +- experimental::refaliasing
906 | |
907 | +- experimental::regex_sets
908 | |
3c3f8cd6
AB		 909 | +- experimental::smartmatch
910 | |
a1325b90
PE		 911 | +- experimental::try
912 | |
4fa1c4b6
KW		 913 | +- experimental::uniprop_wildcards
914 | |
15a9bc0d 915 | +- experimental::vlb
3c3f8cd6
AB		 916 |
917 +- glob
918 |
919 +- imprecision
920 |
921 +- io ------------+
922 | |
923 | +- closed
924 | |
925 | +- exec
926 | |
927 | +- layer
928 | |
929 | +- newline
930 | |
931 | +- pipe
932 | |
933 | +- syscalls
934 | |
935 | +- unopened
936 |
937 +- locale
938 |
939 +- misc
940 |
941 +- missing
942 |
943 +- numeric
944 |
945 +- once
946 |
947 +- overflow
948 |
949 +- pack
950 |
951 +- portable
952 |
953 +- recursion
954 |
955 +- redefine
956 |
957 +- redundant
958 |
959 +- regexp
960 |
4c58833d
PE		 961 +- scalar
962 |
3c3f8cd6
AB		 963 +- severe --------+
964 | |
965 | +- debugging
966 | |
967 | +- inplace
968 | |
969 | +- internal
970 | |
971 | +- malloc
972 |
52e3acf8
Z		 973 +- shadow
974 |
3c3f8cd6
AB		 975 +- signal
976 |
977 +- substr
978 |
979 +- syntax --------+
980 | |
981 | +- ambiguous
982 | |
983 | +- bareword
984 | |
985 | +- digit
986 | |
987 | +- illegalproto
988 | |
989 | +- parenthesis
990 | |
991 | +- precedence
992 | |
993 | +- printf
994 | |
995 | +- prototype
996 | |
997 | +- qw
998 | |
999 | +- reserved
1000 | |
1001 | +- semicolon
1002 |
1003 +- taint
1004 |
1005 +- threads
1006 |
1007 +- uninitialized
1008 |
1009 +- unpack
1010 |
1011 +- untie
1012 |
1013 +- utf8 ----------+
1014 | |
1015 | +- non_unicode
1016 | |
1017 | +- nonchar
1018 | |
1019 | +- surrogate
1020 |
1021 +- void
a7f2b7af
RS		 1022
1023Just like the "strict" pragma any of these categories can be combined
1024
1025 use warnings qw(void redefine);
1026 no warnings qw(io syntax untie);
1027
1028Also like the "strict" pragma, if there is more than one instance of the
56873d42 1029C<warnings> pragma in a given scope the cumulative effect is additive.
a7f2b7af
RS		 1030
1031 use warnings qw(void); # only "void" warnings enabled
1032 ...
1033 use warnings qw(io); # only "void" & "io" warnings enabled
1034 ...
1035 no warnings qw(void); # only "io" warnings enabled
1036
1037To determine which category a specific warning has been assigned to see
1038L<perldiag>.
1039
1040Note: Before Perl 5.8.0, the lexical warnings category "deprecated" was a
1041sub-category of the "syntax" category. It is now a top-level category
1042in its own right.
1043
3664866e
AB		 1044Note: Before 5.21.0, the "missing" lexical warnings category was
1045internally defined to be the same as the "uninitialized" category. It
1046is now a top-level category in its own right.
1047
a7f2b7af
RS		 1048=head2 Fatal Warnings
1049X<warning, fatal>
1050
2e4abf26
DG		 1051The presence of the word "FATAL" in the category list will escalate
1052warnings in those categories into fatal errors in that lexical scope.
1053
1054B<NOTE:> FATAL warnings should be used with care, particularly
1055C<< FATAL => 'all' >>.
1056
1057Libraries using L<warnings::warn|/FUNCTIONS> for custom warning categories
1058generally don't expect L<warnings::warn|/FUNCTIONS> to be fatal and can wind up
1059in an unexpected state as a result. For XS modules issuing categorized
1060warnings, such unanticipated exceptions could also expose memory leak bugs.
1061
1062Moreover, the Perl interpreter itself has had serious bugs involving
1063fatalized warnings. For a summary of resolved and unresolved problems as
1064of January 2015, please see
1065L<this perl5-porters post|http://www.nntp.perl.org/group/perl.perl5.porters/2015/01/msg225235.html>.
1066
1067While some developers find fatalizing some warnings to be a useful
1068defensive programming technique, using C<< FATAL => 'all' >> to fatalize
1069all possible warning categories -- including custom ones -- is particularly
1070risky. Therefore, the use of C<< FATAL => 'all' >> is
1071L<discouraged|perlpolicy/discouraged>.
1072
1073The L<strictures|strictures/VERSION-2> module on CPAN offers one example of
1074a warnings subset that the module's authors believe is relatively safe to
1075fatalize.
1076
01900a5f 1077B<NOTE:> Users of FATAL warnings, especially those using
2e4abf26
DG		 1078C<< FATAL => 'all' >>, should be fully aware that they are risking future
1079portability of their programs by doing so. Perl makes absolutely no
1080commitments to not introduce new warnings or warnings categories in the
1081future; indeed, we explicitly reserve the right to do so. Code that may
1082not warn now may warn in a future release of Perl if the Perl5 development
1083team deems it in the best interests of the community to do so. Should code
1084using FATAL warnings break due to the introduction of a new warning we will
1085NOT consider it an incompatible change. Users of FATAL warnings should
1086take special caution during upgrades to check to see if their code triggers
1087any new warnings and should pay particular attention to the fine print of
1088the documentation of the features they use to ensure they do not exploit
1089features that are documented as risky, deprecated, or unspecified, or where
1090the documentation says "so don't do that", or anything with the same sense
1091and spirit. Use of such features in combination with FATAL warnings is
1092ENTIRELY AT THE USER'S RISK.
1093
1094The following documentation describes how to use FATAL warnings but the
1095perl5 porters strongly recommend that you understand the risks before doing
1096so, especially for library code intended for use by others, as there is no
1097way for downstream users to change the choice of fatal categories.
1098
1099In the code below, the use of C<time>, C<length>
a7f2b7af
RS		 1100and C<join> can all produce a C<"Useless use of xxx in void context">
1101warning.
1102
1103 use warnings;
1104
1105 time;
1106
1107 {
1108 use warnings FATAL => qw(void);
1109 length "abc";
1110 }
1111
1112 join "", 1,2,3;
1113
1114 print "done\n";
1115
1116When run it produces this output
1117
1118 Useless use of time in void context at fatal line 3.
56873d42 1119 Useless use of length in void context at fatal line 7.
a7f2b7af
RS		 1120
1121The scope where C<length> is used has escalated the C<void> warnings
1122category into a fatal error, so the program terminates immediately when it
1123encounters the warning.
1124
1125To explicitly turn off a "FATAL" warning you just disable the warning
1126it is associated with. So, for example, to disable the "void" warning
1127in the example above, either of these will do the trick:
1128
1129 no warnings qw(void);
1130 no warnings FATAL => qw(void);
1131
1132If you want to downgrade a warning that has been escalated into a fatal
1133error back to a normal warning, you can use the "NONFATAL" keyword. For
1134example, the code below will promote all warnings into fatal errors,
1135except for those in the "syntax" category.
1136
1137 use warnings FATAL => 'all', NONFATAL => 'syntax';
1138
1139As of Perl 5.20, instead of C<< use warnings FATAL => 'all'; >> you can
1140use:
1141
1142 use v5.20; # Perl 5.20 or greater is required for the following
1143 use warnings 'FATAL'; # short form of "use warnings FATAL => 'all';"
1144
01900a5f 1145However, you should still heed the guidance earlier in this section against
5624cfff 1146using C<< use warnings FATAL => 'all'; >>.
01900a5f 1147
a7f2b7af
RS		 1148If you want your program to be compatible with versions of Perl before
11495.20, you must use C<< use warnings FATAL => 'all'; >> instead. (In
1150previous versions of Perl, the behavior of the statements
1151C<< use warnings 'FATAL'; >>, C<< use warnings 'NONFATAL'; >> and
1152C<< no warnings 'FATAL'; >> was unspecified; they did not behave as if
1153they included the C<< => 'all' >> portion. As of 5.20, they do.)
1154
a7f2b7af
RS		 1155=head2 Reporting Warnings from a Module
1156X<warning, reporting> X<warning, registering>
1157
1158The C<warnings> pragma provides a number of functions that are useful for
1159module authors. These are used when you want to report a module-specific
1160warning to a calling module has enabled warnings via the C<warnings>
1161pragma.
1162
1163Consider the module C<MyMod::Abc> below.
1164
1165 package MyMod::Abc;
1166
1167 use warnings::register;
1168
1169 sub open {
1170 my $path = shift;
1171 if ($path !~ m#^/#) {
1172 warnings::warn("changing relative path to /var/abc")
1173 if warnings::enabled();
1174 $path = "/var/abc/$path";
1175 }
1176 }
1177
1178 1;
1179
1180The call to C<warnings::register> will create a new warnings category
1181called "MyMod::Abc", i.e. the new category name matches the current
1182package name. The C<open> function in the module will display a warning
1183message if it gets given a relative path as a parameter. This warnings
1184will only be displayed if the code that uses C<MyMod::Abc> has actually
1185enabled them with the C<warnings> pragma like below.
1186
1187 use MyMod::Abc;
1188 use warnings 'MyMod::Abc';
1189 ...
1190 abc::open("../fred.txt");
1191
1192It is also possible to test whether the pre-defined warnings categories are
1193set in the calling module with the C<warnings::enabled> function. Consider
1194this snippet of code:
1195
1196 package MyMod::Abc;
1197
1198 sub open {
4a21999a
TC		 1199 if (warnings::enabled("deprecated")) {
1200 warnings::warn("deprecated",
1201 "open is deprecated, use new instead");
1202 }
a7f2b7af
RS		 1203 new(@_);
1204 }
1205
1206 sub new
1207 ...
1208 1;
1209
1210The function C<open> has been deprecated, so code has been included to
1211display a warning message whenever the calling module has (at least) the
1212"deprecated" warnings category enabled. Something like this, say.
1213
1214 use warnings 'deprecated';
1215 use MyMod::Abc;
1216 ...
1217 MyMod::Abc::open($filename);
1218
1219Either the C<warnings::warn> or C<warnings::warnif> function should be
1220used to actually display the warnings message. This is because they can
1221make use of the feature that allows warnings to be escalated into fatal
1222errors. So in this case
1223
1224 use MyMod::Abc;
1225 use warnings FATAL => 'MyMod::Abc';
1226 ...
1227 MyMod::Abc::open('../fred.txt');
1228
1229the C<warnings::warnif> function will detect this and die after
1230displaying the warning message.
1231
1232The three warnings functions, C<warnings::warn>, C<warnings::warnif>
1233and C<warnings::enabled> can optionally take an object reference in place
1234of a category name. In this case the functions will use the class name
1235of the object as the warnings category.
1236
1237Consider this example:
1238
1239 package Original;
1240
1241 no warnings;
1242 use warnings::register;
1243
1244 sub new
1245 {
1246 my $class = shift;
1247 bless [], $class;
1248 }
1249
1250 sub check
effd17dc
DD		 1251 {
1252 my $self = shift;
1253 my $value = shift;
e476b1b5 1254
effd17dc
DD		 1255 if ($value % 2 && warnings::enabled($self))
1256 { warnings::warn($self, "Odd numbers are unsafe") }
1257 }
599cee73 1258
effd17dc
DD		 1259 sub doit
1260 {
1261 my $self = shift;
1262 my $value = shift;
1263 $self->check($value);
1264 # ...
1265 }
599cee73 1266
effd17dc 1267 1;
0d658bf5 1268
effd17dc 1269 package Derived;
0d658bf5 1270
effd17dc
DD		 1271 use warnings::register;
1272 use Original;
1273 our @ISA = qw( Original );
1274 sub new
1275 {
1276 my $class = shift;
1277 bless [], $class;
1278 }
b88df990 1279
b88df990 1280
effd17dc 1281 1;
8457b38f 1282
56873d42 1283The code below makes use of both modules, but it only enables warnings from
effd17dc 1284C<Derived>.
8457b38f 1285
effd17dc
DD		 1286 use Original;
1287 use Derived;
1288 use warnings 'Derived';
573a192d
DIM		 1289 my $x = Original->new();
1290 $x->doit(1);
1291 my $y = Derived->new();
1292 $x->doit(1);
6f87cb12 1293
573a192d 1294When this code is run only the C<Derived> object, C<$y>, will generate
56873d42 1295a warning.
6f87cb12 1296
effd17dc 1297 Odd numbers are unsafe at main.pl line 7
c8028aa6 1298
effd17dc
DD		 1299Notice also that the warning is reported at the line where the object is first
1300used.
c8028aa6 1301
effd17dc
DD		 1302When registering new categories of warning, you can supply more names to
1303warnings::register like this:
7ac92924 1304
effd17dc
DD		 1305 package MyModule;
1306 use warnings::register qw(format precision);
7ac92924 1307
effd17dc 1308 ...
d3a7d8c7 1309
effd17dc 1310 warnings::warnif('MyModule::format', '...');
599cee73 1311
effd17dc 1312=head1 FUNCTIONS
599cee73 1313
c4583f59
FC		 1314Note: The functions with names ending in C<_at_level> were added in Perl
13155.28.
1316
39b50539
Z		 1317=over 4
1318
effd17dc 1319=item use warnings::register
599cee73 1320
effd17dc
DD		 1321Creates a new warnings category with the same name as the package where
1322the call to the pragma is used.
c3186b65 1323
effd17dc 1324=item warnings::enabled()
6e9af7e4 1325
effd17dc 1326Use the warnings category with the same name as the current package.
599cee73 1327
effd17dc
DD		 1328Return TRUE if that warnings category is enabled in the calling module.
1329Otherwise returns FALSE.
599cee73 1330
effd17dc 1331=item warnings::enabled($category)
4c02ac93 1332
effd17dc
DD		 1333Return TRUE if the warnings category, C<$category>, is enabled in the
1334calling module.
1335Otherwise returns FALSE.
6e9af7e4 1336
effd17dc 1337=item warnings::enabled($object)
6e9af7e4 1338
effd17dc
DD		 1339Use the name of the class for the object reference, C<$object>, as the
1340warnings category.
c91312d5 1341
effd17dc
DD		 1342Return TRUE if that warnings category is enabled in the first scope
1343where the object is used.
1344Otherwise returns FALSE.
a7f2b7af 1345
c4583f59
FC		 1346=item warnings::enabled_at_level($category, $level)
1347
1348Like C<warnings::enabled>, but $level specifies the exact call frame, 0
1349being the immediate caller.
1350
effd17dc 1351=item warnings::fatal_enabled()
599cee73 1352
effd17dc
DD		 1353Return TRUE if the warnings category with the same name as the current
1354package has been set to FATAL in the calling module.
1355Otherwise returns FALSE.
6e9af7e4 1356
effd17dc 1357=item warnings::fatal_enabled($category)
6e9af7e4 1358
effd17dc
DD		 1359Return TRUE if the warnings category C<$category> has been set to FATAL in
1360the calling module.
1361Otherwise returns FALSE.
6e9af7e4 1362
effd17dc 1363=item warnings::fatal_enabled($object)
6e9af7e4 1364
effd17dc
DD		 1365Use the name of the class for the object reference, C<$object>, as the
1366warnings category.
6e9af7e4 1367
effd17dc
DD		 1368Return TRUE if that warnings category has been set to FATAL in the first
1369scope where the object is used.
1370Otherwise returns FALSE.
599cee73 1371
c4583f59
FC		 1372=item warnings::fatal_enabled_at_level($category, $level)
1373
1374Like C<warnings::fatal_enabled>, but $level specifies the exact call frame,
13750 being the immediate caller.
1376
effd17dc 1377=item warnings::warn($message)
9df0f64f 1378
effd17dc 1379Print C<$message> to STDERR.
8787a747 1380
effd17dc 1381Use the warnings category with the same name as the current package.
96183d25 1382
effd17dc
DD		 1383If that warnings category has been set to "FATAL" in the calling module
1384then die. Otherwise return.
96183d25 1385
effd17dc 1386=item warnings::warn($category, $message)
d3a7d8c7 1387
effd17dc 1388Print C<$message> to STDERR.
d3a7d8c7 1389
effd17dc
DD		 1390If the warnings category, C<$category>, has been set to "FATAL" in the
1391calling module then die. Otherwise return.
7e6d00f8 1392
effd17dc 1393=item warnings::warn($object, $message)
7e6d00f8 1394
effd17dc 1395Print C<$message> to STDERR.
8787a747 1396
effd17dc
DD		 1397Use the name of the class for the object reference, C<$object>, as the
1398warnings category.
8787a747 1399
effd17dc
DD		 1400If that warnings category has been set to "FATAL" in the scope where C<$object>
1401is first used then die. Otherwise return.
96183d25 1402
c4583f59
FC		 1403=item warnings::warn_at_level($category, $level, $message)
1404
1405Like C<warnings::warn>, but $level specifies the exact call frame,
14060 being the immediate caller.
96183d25 1407
effd17dc 1408=item warnings::warnif($message)
96183d25 1409
effd17dc 1410Equivalent to:
7e6d00f8 1411
effd17dc
DD		 1412 if (warnings::enabled())
1413 { warnings::warn($message) }
572bfd36 1414
effd17dc 1415=item warnings::warnif($category, $message)
572bfd36 1416
effd17dc 1417Equivalent to:
572bfd36 1418
effd17dc
DD		 1419 if (warnings::enabled($category))
1420 { warnings::warn($category, $message) }
572bfd36 1421
effd17dc 1422=item warnings::warnif($object, $message)
4f527b71 1423
effd17dc 1424Equivalent to:
599cee73 1425
effd17dc
DD		 1426 if (warnings::enabled($object))
1427 { warnings::warn($object, $message) }
d3a7d8c7 1428
c4583f59
FC		 1429=item warnings::warnif_at_level($category, $level, $message)
1430
1431Like C<warnings::warnif>, but $level specifies the exact call frame,
14320 being the immediate caller.
1433
effd17dc 1434=item warnings::register_categories(@names)
e476b1b5 1435
effd17dc
DD		 1436This registers warning categories for the given names and is primarily for
1437use by the warnings::register pragma.
0d658bf5 1438
effd17dc 1439=back
8787a747 1440
effd17dc
DD		 1441See also L<perlmodlib/Pragmatic Modules> and L<perldiag>.
1442
1443=cut
ce716c52 1444
37442d52 1445# ex: set ro:
Unnamed repository; edit this file 'description' to name the repository.