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