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