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