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