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