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