This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
202056837a247c2f1e777172077973a6cb6053e7
[perl5.git] / lib / warnings.pm
1 # -*- buffer-read-only: t -*-
2 # !!!!!!!   DO NOT EDIT THIS FILE   !!!!!!!
3 # This file is built by regen/warnings.pl.
4 # Any changes made here will be lost!
5
6 package warnings;
7
8 our $VERSION = '1.30';
9
10 # Verify that we're called correctly so that warnings will work.
11 # see also strict.pm.
12 unless ( __FILE__ =~ /(^|[\/\\])\Q${\__PACKAGE__}\E\.pmc?$/ ) {
13     my (undef, $f, $l) = caller;
14     die("Incorrect use of pragma '${\__PACKAGE__}' at $f line $l.\n");
15 }
16
17 our %Offsets = (
18
19     # Warnings Categories added in Perl 5.008
20
21     'all'               => 0,
22     'closure'           => 2,
23     'deprecated'        => 4,
24     'exiting'           => 6,
25     'glob'              => 8,
26     'io'                => 10,
27     'closed'            => 12,
28     'exec'              => 14,
29     'layer'             => 16,
30     'newline'           => 18,
31     'pipe'              => 20,
32     'unopened'          => 22,
33     'misc'              => 24,
34     'numeric'           => 26,
35     'once'              => 28,
36     'overflow'          => 30,
37     'pack'              => 32,
38     'portable'          => 34,
39     'recursion'         => 36,
40     'redefine'          => 38,
41     'regexp'            => 40,
42     'severe'            => 42,
43     'debugging'         => 44,
44     'inplace'           => 46,
45     'internal'          => 48,
46     'malloc'            => 50,
47     'signal'            => 52,
48     'substr'            => 54,
49     'syntax'            => 56,
50     'ambiguous'         => 58,
51     'bareword'          => 60,
52     'digit'             => 62,
53     'parenthesis'       => 64,
54     'precedence'        => 66,
55     'printf'            => 68,
56     'prototype'         => 70,
57     'qw'                => 72,
58     'reserved'          => 74,
59     'semicolon'         => 76,
60     'taint'             => 78,
61     'threads'           => 80,
62     'uninitialized'     => 82,
63     'unpack'            => 84,
64     'untie'             => 86,
65     'utf8'              => 88,
66     'void'              => 90,
67
68     # Warnings Categories added in Perl 5.011
69
70     'imprecision'       => 92,
71     'illegalproto'      => 94,
72
73     # Warnings Categories added in Perl 5.013
74
75     'non_unicode'       => 96,
76     'nonchar'           => 98,
77     'surrogate'         => 100,
78
79     # Warnings Categories added in Perl 5.017
80
81     'experimental'      => 102,
82     'experimental::lexical_subs'=> 104,
83     'experimental::lexical_topic'=> 106,
84     'experimental::regex_sets'=> 108,
85     'experimental::smartmatch'=> 110,
86
87     # Warnings Categories added in Perl 5.019
88
89     'experimental::autoderef'=> 112,
90     'experimental::postderef'=> 114,
91     'experimental::signatures'=> 116,
92     'syscalls'          => 118,
93
94     # Warnings Categories added in Perl 5.021
95
96     'everything'        => 120,
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,
106   );
107
108 our %Bits = (
109     'all'               => "\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x54\x55\x00", # [0..59,61..67]
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]
117     'everything'        => "\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x05", # [0..69]
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]
120     'experimental'      => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x40\x55\x15\x54\x01\x00", # [51..58,61..64]
121     'experimental::autoderef'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00", # [56]
122     'experimental::const_attr'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00", # [61]
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]
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]
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]
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]
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]
140     'locale'            => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00", # [65]
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]
143     'missing'           => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x10\x00", # [66]
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]
160     'redundant'         => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x40\x00", # [67]
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]
178     'void_unusual'      => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x04", # [69]
179   );
180
181 our %DeadBits = (
182     'all'               => "\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xa8\xaa\x00", # [0..59,61..67]
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]
190     'everything'        => "\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\x0a", # [0..69]
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]
193     'experimental'      => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80\xaa\x2a\xa8\x02\x00", # [51..58,61..64]
194     'experimental::autoderef'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x00\x00", # [56]
195     'experimental::const_attr'=> "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x08\x00\x00", # [61]
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]
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]
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]
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]
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]
213     'locale'            => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x08\x00", # [65]
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]
216     'missing'           => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x20\x00", # [66]
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]
233     'redundant'         => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80\x00", # [67]
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]
251     'void_unusual'      => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x08", # [69]
252   );
253
254 $NONE     = "\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0";
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 ;
257 $BYTES    = 18 ;
258
259 $All = "" ; vec($All, $Offsets{'all'}, 2) = 3 ;
260
261 sub Croaker
262 {
263     require Carp; # this initializes %CarpInternal
264     local $Carp::CarpInternal{'warnings'};
265     delete $Carp::CarpInternal{'warnings'};
266     Carp::croak(@_);
267 }
268
269 sub _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
290           { Croaker("Unknown warnings category '$word'")}
291     }
292
293     return $mask ;
294 }
295
296 sub bits
297 {
298     # called from B::Deparse.pm
299     push @_, 'all' unless @_ ;
300     return _bits(undef, @_) ;
301 }
302
303 sub import
304 {
305     shift;
306
307     my $mask = ${^WARNING_BITS} // ($^W ? $Bits{all} : $DEFAULT) ;
308
309     if (vec($mask, $Offsets{'all'}, 1)) {
310         $mask |= $Bits{'all'} ;
311         $mask |= $DeadBits{'all'} if vec($mask, $Offsets{'all'}+1, 1);
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
321 sub 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)) {
329         $mask |= $Bits{'all'} ;
330         $mask |= $DeadBits{'all'} if vec($mask, $Offsets{'all'}+1, 1);
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
344           { Croaker("Unknown warnings category '$word'")}
345     }
346
347     ${^WARNING_BITS} = $mask ;
348 }
349
350 my %builtin_type; @builtin_type{qw(SCALAR ARRAY HASH CODE REF GLOB LVALUE Regexp)} = ();
351
352 sub MESSAGE () { 4 };
353 sub FATAL () { 2 };
354 sub NORMAL () { 1 };
355
356 sub __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 (@_) {
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};
378             $category = $type;
379             $isobj = 1 ;
380         }
381         $offset = $Offsets{$category};
382         Croaker("Unknown warnings category '$category'")
383             unless defined $offset;
384     }
385     else {
386         $category = (caller(1))[0] ;
387         $offset = $Offsets{$category};
388         Croaker("package '$category' not registered for warnings")
389             unless defined $offset ;
390     }
391
392     my $i;
393
394     if ($isobj) {
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         }
400         $i -= 2 ;
401     }
402     else {
403         $i = _error_loc(); # see where Carp will allocate the error
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
434 sub _mkMask
435 {
436     my ($bit) = @_;
437     my $mask = "";
438
439     vec($mask, $bit, 1) = 1;
440     return $mask;
441 }
442
443 sub 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
461 sub _error_loc {
462     require Carp;
463     goto &Carp::short_error_loc; # don't introduce another stack frame
464 }
465
466 sub enabled
467 {
468     return __chk(NORMAL, @_);
469 }
470
471 sub fatal_enabled
472 {
473     return __chk(FATAL, @_);
474 }
475
476 sub warn
477 {
478     return __chk(FATAL | MESSAGE, @_);
479 }
480
481 sub 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.
488 delete @warnings::{qw(NORMAL FATAL MESSAGE)};
489
490 1;
491 __END__
492 =head1 NAME
493
494 warnings - Perl pragma to control optional warnings
495
496 =head1 SYNOPSIS
497
498     use warnings;
499     no warnings;
500
501     use warnings "all";
502     no warnings "all";
503
504     use warnings::register;
505     if (warnings::enabled()) {
506         warnings::warn("some warning");
507     }
508
509     if (warnings::enabled("void")) {
510         warnings::warn("void", "some warning");
511     }
512
513     if (warnings::enabled($object)) {
514         warnings::warn($object, "some warning");
515     }
516
517     warnings::warnif("some warning");
518     warnings::warnif("void", "some warning");
519     warnings::warnif($object, "some warning");
520
521 =head1 DESCRIPTION
522
523 The C<warnings> pragma gives control over which warnings are enabled in
524 which parts of a Perl program.  It's a more flexible alternative for
525 both the command line flag B<-w> and the equivalent Perl variable,
526 C<$^W>.
527
528 This pragma works just like the C<strict> pragma.
529 This means that the scope of the warning pragma is limited to the
530 enclosing block.  It also means that the pragma setting will not
531 leak across files (via C<use>, C<require> or C<do>).  This allows
532 authors to independently define the degree of warning checks that will
533 be applied to their module.
534
535 By default, optional warnings are disabled, so any legacy code that
536 doesn't attempt to control the warnings will work unchanged.
537
538 When we talk about "all" warnings we don't actually mean "all the
539 warnings we support". See L</Top-level warning categories & associated
540 confusion> 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:
544
545     use warnings;
546     use warnings 'all';
547
548 Similarly "all" warnings are disabled in a block by either of these:
549
550     no warnings;
551     no warnings 'all';
552
553 For 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
563 The code in the enclosing block has warnings enabled, but the inner
564 block has them disabled.  In this case that means the assignment to the
565 scalar C<$c> will trip the C<"Scalar value @a[0] better written as $a[0]">
566 warning, but the assignment to the scalar C<$b> will not.
567
568 =head2 Default Warnings and Optional Warnings
569
570 Before the introduction of lexical warnings, Perl had two classes of
571 warnings: mandatory and optional.
572
573 As its name suggests, if your code tripped a mandatory warning, you
574 would get a warning whether you wanted it or not.
575 For example, the code below would always produce an C<"isn't numeric">
576 warning about the "2:".
577
578     my $a = "2:" + 3;
579
580 With the introduction of lexical warnings, mandatory warnings now become
581 I<default> warnings.  The difference is that although the previously
582 mandatory warnings are still enabled by default, they can then be
583 subsequently enabled or disabled with the lexical warning pragma.  For
584 example, in the code below, an C<"isn't numeric"> warning will only
585 be reported for the C<$a> variable.
586
587     my $a = "2:" + 3;
588     no warnings;
589     my $b = "2:" + 3;
590
591 Note that neither the B<-w> flag or the C<$^W> can be used to
592 disable/enable default warnings.  They are still mandatory in this case.
593
594 =head2 What's wrong with B<-w> and C<$^W>
595
596 Although very useful, the big problem with using B<-w> on the command
597 line to enable warnings is that it is all or nothing.  Take the typical
598 scenario when you are writing a Perl program.  Parts of the code you
599 will write yourself, but it's very likely that you will make use of
600 pre-written Perl modules.  If you use the B<-w> flag in this case, you
601 end up enabling warnings in pieces of code that you haven't written.
602
603 Similarly, using C<$^W> to either disable or enable blocks of code is
604 fundamentally flawed.  For a start, say you want to disable warnings in
605 a 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
613 When this code is run with the B<-w> flag, a warning will be produced
614 for the C<$a> line:  C<"Reversed += operator">.
615
616 The problem is that Perl has both compile-time and run-time warnings.  To
617 disable 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
625 The other big problem with C<$^W> is the way you can inadvertently
626 change the warning setting in unexpected places in your code.  For example,
627 when the code below is run (without the B<-w> flag), the second call
628 to C<doit> will trip a C<"Use of uninitialized value"> warning, whereas
629 the 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
643 This is a side-effect of C<$^W> being dynamically scoped.
644
645 Lexical warnings get around these limitations by allowing finer control
646 over where warnings can or can't be tripped.
647
648 =head2 Controlling Warnings from the Command Line
649
650 There are three Command Line flags that can be used to control when
651 warnings are (or aren't) produced:
652
653 =over 5
654
655 =item B<-w>
656 X<-w>
657
658 This is  the existing flag.  If the lexical warnings pragma is B<not>
659 used in any of you code, or any of the modules that you use, this flag
660 will enable warnings everywhere.  See L<Backward Compatibility> for
661 details of how this flag interacts with lexical warnings.
662
663 =item B<-W>
664 X<-W>
665
666 If the B<-W> flag is used on the command line, it will enable "all" warnings
667 throughout the program regardless of whether warnings were disabled
668 locally using C<no warnings> or C<$^W =0>.
669 This includes all files that get
670 included via C<use>, C<require> or C<do>.
671 Think of it as the Perl equivalent of the "lint" command.
672
673 =item B<-X>
674 X<-X>
675
676 Does 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
682 The lexical warning pragma was introduced in v5.6.0 of perl, and from
683 the very beginning doing C<use warnings> would enable the "all"
684 category of warnings, which were all the warnings we support.
685
686 This led to arguments whenever someone suggested a new warning be
687 added to perl, since that implicitly meant that existing programs that
688 used the warnings pragma would be retroactively subjected to them when
689 perl was upgraded.
690
691 So similarly to how most C compilers support C<-Wall> to mean "not
692 quite all warnings" along with extra options like C<-Wextra>, we
693 support warnings outside of the "all" category. Think of the "all"
694 category as "default", that's what we'd call it we were starting out
695 today and didn't have a bunch of programs doing C<use warnings "all">
696 in the wild already.
697
698 The categories we support are:
699
700 =over
701
702 =item * all
703
704 This is the "default" category for warnings that we've supported ever
705 since v5.6.0. We have and might occasionally add new warnings here if
706 they're deemed to be similar in nature to our existing warnings, but
707 mostly these are things we're pretty sure are a logic error, but
708 aren't irrecoverable, so they're not a runtime error.
709
710 When you upgrade perl you might find that we've added some new
711 warnings here, but they won't be anything wildly different from the
712 current set of warnings, so the burden of going through your existing
713 code and auditing the new parts that are warning should be fairly
714 light.
715
716 =item * everything
717
718 This is what "all" would be if the world made any sense, but since we
719 started out with "all" you need to enable "everything" to really
720 enable "all the warnings".
721
722 You almost definitely don't want to enable "everything", unless you're
723 willing to potentially get a flood of new warnings with every perl
724 upgrade, and those warnings may be entirely different in spirit to
725 existing warnings shipped with previous releases.
726
727 Maybe we'll start introducing really pedantic warnings that aren't
728 useful for most cases, maybe we'll start warning about inconsistent
729 indentation, who knows? If you really want ALL the warnings perl has
730 to offer enable these, otherwise stick with some more sane category.
731
732 =item * extra
733
734 These 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
736 perl today, but they'd probably cause too much of a disruption today
737 so we're not doing that.
738
739 As of writing this the sole warning in this category is a warning
740 about useless use of grep in void context, but unlike for the "all"
741 category we reserve the right to freely add things to this category in
742 the future.
743
744 =back
745
746 In the future we might add any number of other top-level
747 categories. The backwards-compatibility promises of those categories
748 (if any) will be documented here.
749
750 =head2 Backward Compatibility
751
752 If you are used to working with a version of Perl prior to the
753 introduction of lexically scoped warnings, or have code that uses both
754 lexical warnings and C<$^W>, this section will describe how they interact.
755
756 How Lexical Warnings interact with B<-w>/C<$^W>:
757
758 =over 5
759
760 =item 1.
761
762 If none of the three command line flags (B<-w>, B<-W> or B<-X>) that
763 control warnings is used and neither C<$^W> nor the C<warnings> pragma
764 are used, then default warnings will be enabled and optional warnings
765 disabled.
766 This means that legacy code that doesn't attempt to control the warnings
767 will work unchanged.
768
769 =item 2.
770
771 The B<-w> flag just sets the global C<$^W> variable as in 5.005.  This
772 means that any legacy code that currently relies on manipulating C<$^W>
773 to control warning behavior will still work as is.
774
775 =item 3.
776
777 Apart from now being a boolean, the C<$^W> variable operates in exactly
778 the same horrible uncontrolled global way, except that it cannot
779 disable/enable default warnings.
780
781 =item 4.
782
783 If a piece of code is under the control of the C<warnings> pragma,
784 both the C<$^W> variable and the B<-w> flag will be ignored for the
785 scope of the lexical warning.
786
787 =item 5.
788
789 The only way to override a lexical warnings setting is with the B<-W>
790 or B<-X> command line flags.
791
792 =back
793
794 The combined effect of 3 & 4 is that it will allow code which uses
795 the C<warnings> pragma to control the warning behavior of $^W-type
796 code (using a C<local $^W=0>) if it really wants to, but not vice-versa.
797
798 =head2 Category Hierarchy
799 X<warning, categories>
800
801 A hierarchy of "categories" have been defined to allow groups of warnings
802 to be enabled/disabled in isolation.
803
804 The current hierarchy is:
805
806  everything -+
807              |
808              +- all ---+
809              |         |
810              |         +- closure
811              |         |
812              |         +- deprecated
813              |         |
814              |         +- exiting
815              |         |
816              |         +- experimental --+
817              |         |                 |
818              |         |                 +- experimental::autoderef
819              |         |                 |
820              |         |                 +- experimental::const_attr
821              |         |                 |
822              |         |                 +- experimental::lexical_subs
823              |         |                 |
824              |         |                 +- experimental::lexical_topic
825              |         |                 |
826              |         |                 +- experimental::postderef
827              |         |                 |
828              |         |                 +- experimental::re_strict
829              |         |                 |
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
945
946 Just 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
951 Also like the "strict" pragma, if there is more than one instance of the
952 C<warnings> pragma in a given scope the cumulative effect is additive.
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
960 To determine which category a specific warning has been assigned to see
961 L<perldiag>.
962
963 Note: Before Perl 5.8.0, the lexical warnings category "deprecated" was a
964 sub-category of the "syntax" category.  It is now a top-level category
965 in its own right.
966
967 Note: Before 5.21.0, the "missing" lexical warnings category was
968 internally defined to be the same as the "uninitialized" category. It
969 is now a top-level category in its own right.
970
971 =head2 Fatal Warnings
972 X<warning, fatal>
973
974 The presence of the word "FATAL" in the category list will escalate any
975 warnings detected from the categories specified in the lexical scope
976 into fatal errors.  In the code below, the use of C<time>, C<length>
977 and C<join> can all produce a C<"Useless use of xxx in void context">
978 warning.
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
993 When run it produces this output
994
995     Useless use of time in void context at fatal line 3.
996     Useless use of length in void context at fatal line 7.
997
998 The scope where C<length> is used has escalated the C<void> warnings
999 category into a fatal error, so the program terminates immediately when it
1000 encounters the warning.
1001
1002 To explicitly turn off a "FATAL" warning you just disable the warning
1003 it is associated with.  So, for example, to disable the "void" warning
1004 in the example above, either of these will do the trick:
1005
1006     no warnings qw(void);
1007     no warnings FATAL => qw(void);
1008
1009 If you want to downgrade a warning that has been escalated into a fatal
1010 error back to a normal warning, you can use the "NONFATAL" keyword.  For
1011 example, the code below will promote all warnings into fatal errors,
1012 except for those in the "syntax" category.
1013
1014     use warnings FATAL => 'all', NONFATAL => 'syntax';
1015
1016 As of Perl 5.20, instead of C<< use warnings FATAL => 'all'; >> you can
1017 use:
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
1022 If you want your program to be compatible with versions of Perl before
1023 5.20, you must use C<< use warnings FATAL => 'all'; >> instead.  (In
1024 previous versions of Perl, the behavior of the statements
1025 C<< use warnings 'FATAL'; >>, C<< use warnings 'NONFATAL'; >> and
1026 C<< no warnings 'FATAL'; >> was unspecified; they did not behave as if
1027 they included the C<< => 'all' >> portion.  As of 5.20, they do.)
1028
1029 B<NOTE:> Users of FATAL warnings, especially
1030 those using C<< FATAL => 'all' >>
1031 should be fully aware that they are risking future portability of their
1032 programs by doing so.  Perl makes absolutely no commitments to not
1033 introduce new warnings, or warnings categories in the future, and indeed
1034 we explicitly reserve the right to do so.  Code that may not warn now may
1035 warn in a future release of Perl if the Perl5 development team deems it
1036 in the best interests of the community to do so.  Should code using FATAL
1037 warnings break due to the introduction of a new warning we will NOT
1038 consider it an incompatible change.  Users of FATAL warnings should take
1039 special caution during upgrades to check to see if their code triggers
1040 any new warnings and should pay particular attention to the fine print of
1041 the documentation of the features they use to ensure they do not exploit
1042 features that are documented as risky, deprecated, or unspecified, or where
1043 the documentation says "so don't do that", or anything with the same sense
1044 and spirit.  Use of such features in combination with FATAL warnings is
1045 ENTIRELY AT THE USER'S RISK.
1046
1047 =head2 Reporting Warnings from a Module
1048 X<warning, reporting> X<warning, registering>
1049
1050 The C<warnings> pragma provides a number of functions that are useful for
1051 module authors.  These are used when you want to report a module-specific
1052 warning to a calling module has enabled warnings via the C<warnings>
1053 pragma.
1054
1055 Consider 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
1072 The call to C<warnings::register> will create a new warnings category
1073 called "MyMod::Abc", i.e. the new category name matches the current
1074 package name.  The C<open> function in the module will display a warning
1075 message if it gets given a relative path as a parameter.  This warnings
1076 will only be displayed if the code that uses C<MyMod::Abc> has actually
1077 enabled 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
1084 It is also possible to test whether the pre-defined warnings categories are
1085 set in the calling module with the C<warnings::enabled> function.  Consider
1086 this snippet of code:
1087
1088     package MyMod::Abc;
1089
1090     sub open {
1091         warnings::warnif("deprecated",
1092                          "open is deprecated, use new instead");
1093         new(@_);
1094     }
1095
1096     sub new
1097     ...
1098     1;
1099
1100 The function C<open> has been deprecated, so code has been included to
1101 display 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
1109 Either the C<warnings::warn> or C<warnings::warnif> function should be
1110 used to actually display the warnings message.  This is because they can
1111 make use of the feature that allows warnings to be escalated into fatal
1112 errors.  So in this case
1113
1114     use MyMod::Abc;
1115     use warnings FATAL => 'MyMod::Abc';
1116     ...
1117     MyMod::Abc::open('../fred.txt');
1118
1119 the C<warnings::warnif> function will detect this and die after
1120 displaying the warning message.
1121
1122 The three warnings functions, C<warnings::warn>, C<warnings::warnif>
1123 and C<warnings::enabled> can optionally take an object reference in place
1124 of a category name.  In this case the functions will use the class name
1125 of the object as the warnings category.
1126
1127 Consider 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
1141     {
1142         my $self = shift;
1143         my $value = shift;
1144
1145         if ($value % 2 && warnings::enabled($self))
1146           { warnings::warn($self, "Odd numbers are unsafe") }
1147     }
1148
1149     sub doit
1150     {
1151         my $self = shift;
1152         my $value = shift;
1153         $self->check($value);
1154         # ...
1155     }
1156
1157     1;
1158
1159     package Derived;
1160
1161     use warnings::register;
1162     use Original;
1163     our @ISA = qw( Original );
1164     sub new
1165     {
1166         my $class = shift;
1167         bless [], $class;
1168     }
1169
1170
1171     1;
1172
1173 The code below makes use of both modules, but it only enables warnings from
1174 C<Derived>.
1175
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);
1183
1184 When this code is run only the C<Derived> object, C<$b>, will generate
1185 a warning.
1186
1187     Odd numbers are unsafe at main.pl line 7
1188
1189 Notice also that the warning is reported at the line where the object is first
1190 used.
1191
1192 When registering new categories of warning, you can supply more names to
1193 warnings::register like this:
1194
1195     package MyModule;
1196     use warnings::register qw(format precision);
1197
1198     ...
1199
1200     warnings::warnif('MyModule::format', '...');
1201
1202 =head1 FUNCTIONS
1203
1204 =over 4
1205
1206 =item use warnings::register
1207
1208 Creates a new warnings category with the same name as the package where
1209 the call to the pragma is used.
1210
1211 =item warnings::enabled()
1212
1213 Use the warnings category with the same name as the current package.
1214
1215 Return TRUE if that warnings category is enabled in the calling module.
1216 Otherwise returns FALSE.
1217
1218 =item warnings::enabled($category)
1219
1220 Return TRUE if the warnings category, C<$category>, is enabled in the
1221 calling module.
1222 Otherwise returns FALSE.
1223
1224 =item warnings::enabled($object)
1225
1226 Use the name of the class for the object reference, C<$object>, as the
1227 warnings category.
1228
1229 Return TRUE if that warnings category is enabled in the first scope
1230 where the object is used.
1231 Otherwise returns FALSE.
1232
1233 =item warnings::fatal_enabled()
1234
1235 Return TRUE if the warnings category with the same name as the current
1236 package has been set to FATAL in the calling module.
1237 Otherwise returns FALSE.
1238
1239 =item warnings::fatal_enabled($category)
1240
1241 Return TRUE if the warnings category C<$category> has been set to FATAL in
1242 the calling module.
1243 Otherwise returns FALSE.
1244
1245 =item warnings::fatal_enabled($object)
1246
1247 Use the name of the class for the object reference, C<$object>, as the
1248 warnings category.
1249
1250 Return TRUE if that warnings category has been set to FATAL in the first
1251 scope where the object is used.
1252 Otherwise returns FALSE.
1253
1254 =item warnings::warn($message)
1255
1256 Print C<$message> to STDERR.
1257
1258 Use the warnings category with the same name as the current package.
1259
1260 If that warnings category has been set to "FATAL" in the calling module
1261 then die. Otherwise return.
1262
1263 =item warnings::warn($category, $message)
1264
1265 Print C<$message> to STDERR.
1266
1267 If the warnings category, C<$category>, has been set to "FATAL" in the
1268 calling module then die. Otherwise return.
1269
1270 =item warnings::warn($object, $message)
1271
1272 Print C<$message> to STDERR.
1273
1274 Use the name of the class for the object reference, C<$object>, as the
1275 warnings category.
1276
1277 If that warnings category has been set to "FATAL" in the scope where C<$object>
1278 is first used then die. Otherwise return.
1279
1280
1281 =item warnings::warnif($message)
1282
1283 Equivalent to:
1284
1285     if (warnings::enabled())
1286       { warnings::warn($message) }
1287
1288 =item warnings::warnif($category, $message)
1289
1290 Equivalent to:
1291
1292     if (warnings::enabled($category))
1293       { warnings::warn($category, $message) }
1294
1295 =item warnings::warnif($object, $message)
1296
1297 Equivalent to:
1298
1299     if (warnings::enabled($object))
1300       { warnings::warn($object, $message) }
1301
1302 =item warnings::register_categories(@names)
1303
1304 This registers warning categories for the given names and is primarily for
1305 use by the warnings::register pragma.
1306
1307 =back
1308
1309 See also L<perlmodlib/Pragmatic Modules> and L<perldiag>.
1310
1311 =cut
1312
1313 # ex: set ro: