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
CommitLineData
37442d52 1# -*- buffer-read-only: t -*-
38875929 2# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
78102347
NC
3# This file is built by regen/warnings.pl.
4# Any changes made here will be lost!
599cee73 5
4438c4b7 6package warnings;
599cee73 7
52e3acf8 8our $VERSION = "1.39";
f2c3e829
RGS
9
10# Verify that we're called correctly so that warnings will work.
67ba812d
AP
11# Can't use Carp, since Carp uses us!
12# String regexps because constant folding = smaller optree = less memory vs regexp literal
f2c3e829 13# see also strict.pm.
67ba812d
AP
14die sprintf "Incorrect use of pragma '%s' at %s line %d.\n", __PACKAGE__, +(caller)[1,2]
15 if __FILE__ !~ ( '(?x) \b '.__PACKAGE__.' \.pmc? \z' )
16 && __FILE__ =~ ( '(?x) \b (?i:'.__PACKAGE__.') \.pmc? \z' );
0ca4541c 17
effd17dc 18our %Offsets = (
effd17dc 19 # Warnings Categories added in Perl 5.008
3c3f8cd6
AB
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,
effd17dc
DD
66
67 # Warnings Categories added in Perl 5.011
3c3f8cd6
AB
68 'imprecision' => 92,
69 'illegalproto' => 94,
effd17dc
DD
70
71 # Warnings Categories added in Perl 5.013
3c3f8cd6
AB
72 'non_unicode' => 96,
73 'nonchar' => 98,
74 'surrogate' => 100,
effd17dc
DD
75
76 # Warnings Categories added in Perl 5.017
3c3f8cd6
AB
77 'experimental' => 102,
78 'experimental::lexical_subs' => 104,
c29314de
FC
79 'experimental::regex_sets' => 106,
80 'experimental::smartmatch' => 108,
effd17dc
DD
81
82 # Warnings Categories added in Perl 5.019
c29314de
FC
83 'experimental::postderef' => 110,
84 'experimental::signatures' => 112,
85 'syscalls' => 114,
effd17dc
DD
86
87 # Warnings Categories added in Perl 5.021
c29314de
FC
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,
88d5dae9
FC
96
97 # Warnings Categories added in Perl 5.025
98 'experimental::declared_refs' => 132,
52e3acf8
Z
99
100 # Warnings Categories added in Perl 5.027
101 'shadow' => 134,
3c3f8cd6 102);
effd17dc
DD
103
104our %Bits = (
006c1a1d 105 'all' => "\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55", # [0..67]
3c3f8cd6
AB
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]
88d5dae9 115 'experimental' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x40\x55\x51\x15\x10", # [51..56,58..62,66]
c29314de
FC
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]
88d5dae9 118 'experimental::declared_refs' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x10", # [66]
3c3f8cd6 119 'experimental::lexical_subs' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00", # [52]
c29314de
FC
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]
3c3f8cd6
AB
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]
c29314de 132 'io' => "\x00\x54\x55\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00", # [5..11,57]
3c3f8cd6 133 'layer' => "\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [8]
c29314de 134 'locale' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x40\x00", # [63]
3c3f8cd6
AB
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]
c29314de 137 'missing' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01", # [64]
3c3f8cd6
AB
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]
c29314de 154 'redundant' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x04", # [65]
3c3f8cd6
AB
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]
52e3acf8 159 'shadow' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x40", # [67]
3c3f8cd6
AB
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]
c29314de 164 'syscalls' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00", # [57]
3c3f8cd6
AB
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);
effd17dc
DD
174
175our %DeadBits = (
006c1a1d 176 'all' => "\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa", # [0..67]
3c3f8cd6
AB
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]
88d5dae9 186 'experimental' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80\xaa\xa2\x2a\x20", # [51..56,58..62,66]
c29314de
FC
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]
88d5dae9 189 'experimental::declared_refs' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x20", # [66]
3c3f8cd6 190 'experimental::lexical_subs' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x00\x00", # [52]
c29314de
FC
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]
3c3f8cd6
AB
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]
c29314de 203 'io' => "\x00\xa8\xaa\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x08\x00\x00", # [5..11,57]
3c3f8cd6 204 'layer' => "\x00\x00\x02\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [8]
c29314de 205 'locale' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80\x00", # [63]
3c3f8cd6
AB
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]
c29314de 208 'missing' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02", # [64]
3c3f8cd6
AB
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]
c29314de 225 'redundant' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x08", # [65]
3c3f8cd6
AB
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]
52e3acf8 230 'shadow' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80", # [67]
3c3f8cd6
AB
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]
c29314de 235 'syscalls' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x08\x00\x00", # [57]
3c3f8cd6
AB
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
247our $NONE = "\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0";
88d5dae9 248our $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]
52e3acf8 249our $LAST_BIT = 136 ;
3c3f8cd6
AB
250our $BYTES = 17 ;
251
effd17dc
DD
252sub Croaker
253{
254 require Carp; # this initializes %CarpInternal
255 local $Carp::CarpInternal{'warnings'};
256 delete $Carp::CarpInternal{'warnings'};
257 Carp::croak(@_);
258}
259
006c1a1d
Z
260sub _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
effd17dc
DD
279sub _bits {
280 my $mask = shift ;
281 my $catmask ;
282 my $fatal = 0 ;
283 my $no_fatal = 0 ;
284
006c1a1d 285 $mask = _expand_bits($mask);
effd17dc
DD
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 ;
006c1a1d 298 $mask = ~(~$mask | $DeadBits{$word}) if $no_fatal ;
effd17dc
DD
299 }
300 else
56873d42 301 { Croaker("Unknown warnings category '$word'")}
effd17dc
DD
302 }
303
304 return $mask ;
305}
306
307sub bits
308{
309 # called from B::Deparse.pm
310 push @_, 'all' unless @_ ;
006c1a1d 311 return _bits("", @_) ;
effd17dc
DD
312}
313
314sub import
315{
316 shift;
317
318 my $mask = ${^WARNING_BITS} // ($^W ? $Bits{all} : $DEFAULT) ;
319
006c1a1d
Z
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'));
effd17dc 324
006c1a1d 325 ${^WARNING_BITS} = _bits($mask, @_);
effd17dc
DD
326}
327
328sub unimport
329{
330 shift;
331
332 my $catmask ;
333 my $mask = ${^WARNING_BITS} // ($^W ? $Bits{all} : $DEFAULT) ;
334
effd17dc
DD
335 # append 'all' when implied (empty import list or after a lone "FATAL")
336 push @_, 'all' if !@_ || @_==1 && $_[0] eq 'FATAL';
337
006c1a1d 338 $mask = _expand_bits($mask);
effd17dc
DD
339 foreach my $word ( @_ ) {
340 if ($word eq 'FATAL') {
341 next;
342 }
343 elsif ($catmask = $Bits{$word}) {
006c1a1d 344 $mask = ~(~$mask | $catmask | $DeadBits{$word});
effd17dc
DD
345 }
346 else
56873d42 347 { Croaker("Unknown warnings category '$word'")}
effd17dc
DD
348 }
349
350 ${^WARNING_BITS} = $mask ;
351}
352
353my %builtin_type; @builtin_type{qw(SCALAR ARRAY HASH CODE REF GLOB LVALUE Regexp)} = ();
354
c4583f59 355sub LEVEL () { 8 };
effd17dc
DD
356sub MESSAGE () { 4 };
357sub FATAL () { 2 };
358sub NORMAL () { 1 };
359
360sub __chk
361{
362 my $category ;
363 my $offset ;
364 my $isobj = 0 ;
365 my $wanted = shift;
366 my $has_message = $wanted & MESSAGE;
c4583f59
FC
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)) {
effd17dc
DD
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 (@_) {
56873d42
DD
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};
effd17dc 392 $category = $type;
56873d42
DD
393 $isobj = 1 ;
394 }
395 $offset = $Offsets{$category};
396 Croaker("Unknown warnings category '$category'")
effd17dc
DD
397 unless defined $offset;
398 }
399 else {
56873d42
DD
400 $category = (caller(1))[0] ;
401 $offset = $Offsets{$category};
402 Croaker("package '$category' not registered for warnings")
effd17dc
DD
403 unless defined $offset ;
404 }
405
406 my $i;
407
408 if ($isobj) {
56873d42
DD
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 }
effd17dc
DD
414 $i -= 2 ;
415 }
c4583f59
FC
416 elsif ($has_level) {
417 $i = 2 + shift;
418 }
effd17dc 419 else {
56873d42 420 $i = _error_loc(); # see where Carp will allocate the error
effd17dc
DD
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 ;
006c1a1d 428 length($callers_bitmask) > ($offset >> 3) or $offset = $Offsets{all};
effd17dc
DD
429
430 my @results;
431 foreach my $type (FATAL, NORMAL) {
432 next unless $wanted & $type;
433
006c1a1d 434 push @results, vec($callers_bitmask, $offset + $type - 1, 1);
effd17dc
DD
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
c4583f59
FC
441 return if ($wanted & (NORMAL | FATAL | MESSAGE))
442 == (NORMAL | FATAL | MESSAGE)
effd17dc
DD
443 && !($results[0] || $results[1]);
444
c4583f59
FC
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
effd17dc
DD
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
460sub _mkMask
461{
462 my ($bit) = @_;
463 my $mask = "";
464
465 vec($mask, $bit, 1) = 1;
466 return $mask;
467}
468
469sub register_categories
470{
471 my @names = @_;
472
473 for my $name (@names) {
474 if (! defined $Bits{$name}) {
006c1a1d
Z
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";
effd17dc 481 }
effd17dc
DD
482 }
483 }
484}
485
486sub _error_loc {
487 require Carp;
488 goto &Carp::short_error_loc; # don't introduce another stack frame
489}
490
491sub enabled
492{
493 return __chk(NORMAL, @_);
494}
495
496sub fatal_enabled
497{
498 return __chk(FATAL, @_);
499}
500
501sub warn
502{
503 return __chk(FATAL | MESSAGE, @_);
504}
505
506sub warnif
507{
508 return __chk(NORMAL | FATAL | MESSAGE, @_);
509}
510
c4583f59
FC
511sub enabled_at_level
512{
513 return __chk(NORMAL | LEVEL, @_);
514}
515
516sub fatal_enabled_at_level
517{
518 return __chk(FATAL | LEVEL, @_);
519}
520
521sub warn_at_level
522{
523 return __chk(FATAL | MESSAGE | LEVEL, @_);
524}
525
526sub warnif_at_level
527{
528 return __chk(NORMAL | FATAL | MESSAGE | LEVEL, @_);
529}
530
effd17dc
DD
531# These are not part of any public interface, so we can delete them to save
532# space.
c4583f59 533delete @warnings::{qw(NORMAL FATAL MESSAGE LEVEL)};
effd17dc
DD
534
5351;
536__END__
599cee73
PM
537=head1 NAME
538
4438c4b7 539warnings - Perl pragma to control optional warnings
599cee73
PM
540
541=head1 SYNOPSIS
542
4438c4b7
JH
543 use warnings;
544 no warnings;
599cee73 545
4438c4b7
JH
546 use warnings "all";
547 no warnings "all";
599cee73 548
d3a7d8c7
GS
549 use warnings::register;
550 if (warnings::enabled()) {
551 warnings::warn("some warning");
552 }
553
554 if (warnings::enabled("void")) {
e476b1b5
GS
555 warnings::warn("void", "some warning");
556 }
557
7e6d00f8
PM
558 if (warnings::enabled($object)) {
559 warnings::warn($object, "some warning");
560 }
561
721f911b
PM
562 warnings::warnif("some warning");
563 warnings::warnif("void", "some warning");
564 warnings::warnif($object, "some warning");
7e6d00f8 565
599cee73
PM
566=head1 DESCRIPTION
567
a7f2b7af
RS
568The C<warnings> pragma gives control over which warnings are enabled in
569which parts of a Perl program. It's a more flexible alternative for
570both the command line flag B<-w> and the equivalent Perl variable,
571C<$^W>.
fe2e802c 572
a7f2b7af
RS
573This pragma works just like the C<strict> pragma.
574This means that the scope of the warning pragma is limited to the
575enclosing block. It also means that the pragma setting will not
576leak across files (via C<use>, C<require> or C<do>). This allows
577authors to independently define the degree of warning checks that will
578be applied to their module.
599cee73 579
a7f2b7af
RS
580By default, optional warnings are disabled, so any legacy code that
581doesn't attempt to control the warnings will work unchanged.
582
3c3f8cd6 583All warnings are enabled in a block by either of these:
a7f2b7af
RS
584
585 use warnings;
586 use warnings 'all';
587
3c3f8cd6 588Similarly all warnings are disabled in a block by either of these:
a7f2b7af
RS
589
590 no warnings;
591 no warnings 'all';
592
593For 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
603The code in the enclosing block has warnings enabled, but the inner
604block has them disabled. In this case that means the assignment to the
605scalar C<$c> will trip the C<"Scalar value @a[0] better written as $a[0]">
606warning, but the assignment to the scalar C<$b> will not.
607
608=head2 Default Warnings and Optional Warnings
609
610Before the introduction of lexical warnings, Perl had two classes of
56873d42 611warnings: mandatory and optional.
a7f2b7af
RS
612
613As its name suggests, if your code tripped a mandatory warning, you
614would get a warning whether you wanted it or not.
615For example, the code below would always produce an C<"isn't numeric">
616warning about the "2:".
617
618 my $a = "2:" + 3;
619
620With the introduction of lexical warnings, mandatory warnings now become
621I<default> warnings. The difference is that although the previously
622mandatory warnings are still enabled by default, they can then be
623subsequently enabled or disabled with the lexical warning pragma. For
624example, in the code below, an C<"isn't numeric"> warning will only
625be reported for the C<$a> variable.
626
627 my $a = "2:" + 3;
628 no warnings;
629 my $b = "2:" + 3;
630
631Note that neither the B<-w> flag or the C<$^W> can be used to
632disable/enable default warnings. They are still mandatory in this case.
633
634=head2 What's wrong with B<-w> and C<$^W>
635
636Although very useful, the big problem with using B<-w> on the command
637line to enable warnings is that it is all or nothing. Take the typical
638scenario when you are writing a Perl program. Parts of the code you
639will write yourself, but it's very likely that you will make use of
640pre-written Perl modules. If you use the B<-w> flag in this case, you
641end up enabling warnings in pieces of code that you haven't written.
642
643Similarly, using C<$^W> to either disable or enable blocks of code is
644fundamentally flawed. For a start, say you want to disable warnings in
645a 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
653When this code is run with the B<-w> flag, a warning will be produced
654for the C<$a> line: C<"Reversed += operator">.
655
656The problem is that Perl has both compile-time and run-time warnings. To
657disable 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
665The other big problem with C<$^W> is the way you can inadvertently
666change the warning setting in unexpected places in your code. For example,
667when the code below is run (without the B<-w> flag), the second call
668to C<doit> will trip a C<"Use of uninitialized value"> warning, whereas
669the 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
683This is a side-effect of C<$^W> being dynamically scoped.
684
685Lexical warnings get around these limitations by allowing finer control
686over where warnings can or can't be tripped.
687
688=head2 Controlling Warnings from the Command Line
689
690There are three Command Line flags that can be used to control when
691warnings are (or aren't) produced:
692
693=over 5
694
695=item B<-w>
696X<-w>
697
698This is the existing flag. If the lexical warnings pragma is B<not>
699used in any of you code, or any of the modules that you use, this flag
700will enable warnings everywhere. See L<Backward Compatibility> for
701details of how this flag interacts with lexical warnings.
702
703=item B<-W>
704X<-W>
705
3c3f8cd6 706If the B<-W> flag is used on the command line, it will enable all warnings
a7f2b7af
RS
707throughout the program regardless of whether warnings were disabled
708locally using C<no warnings> or C<$^W =0>.
709This includes all files that get
710included via C<use>, C<require> or C<do>.
711Think of it as the Perl equivalent of the "lint" command.
712
713=item B<-X>
714X<-X>
715
3c3f8cd6 716Does the exact opposite to the B<-W> flag, i.e. it disables all warnings.
ea5519d6
AB
717
718=back
719
a7f2b7af
RS
720=head2 Backward Compatibility
721
722If you are used to working with a version of Perl prior to the
723introduction of lexically scoped warnings, or have code that uses both
724lexical warnings and C<$^W>, this section will describe how they interact.
725
726How Lexical Warnings interact with B<-w>/C<$^W>:
727
728=over 5
729
730=item 1.
731
732If none of the three command line flags (B<-w>, B<-W> or B<-X>) that
733control warnings is used and neither C<$^W> nor the C<warnings> pragma
734are used, then default warnings will be enabled and optional warnings
735disabled.
736This means that legacy code that doesn't attempt to control the warnings
737will work unchanged.
738
739=item 2.
740
741The B<-w> flag just sets the global C<$^W> variable as in 5.005. This
742means that any legacy code that currently relies on manipulating C<$^W>
56873d42 743to control warning behavior will still work as is.
a7f2b7af
RS
744
745=item 3.
746
747Apart from now being a boolean, the C<$^W> variable operates in exactly
748the same horrible uncontrolled global way, except that it cannot
749disable/enable default warnings.
750
751=item 4.
752
753If a piece of code is under the control of the C<warnings> pragma,
754both the C<$^W> variable and the B<-w> flag will be ignored for the
755scope of the lexical warning.
756
757=item 5.
758
759The only way to override a lexical warnings setting is with the B<-W>
760or B<-X> command line flags.
761
762=back
763
764The combined effect of 3 & 4 is that it will allow code which uses
765the C<warnings> pragma to control the warning behavior of $^W-type
766code (using a C<local $^W=0>) if it really wants to, but not vice-versa.
767
768=head2 Category Hierarchy
769X<warning, categories>
770
771A hierarchy of "categories" have been defined to allow groups of warnings
772to be enabled/disabled in isolation.
773
774The current hierarchy is:
775
3c3f8cd6
AB
776 all -+
777 |
778 +- closure
779 |
780 +- deprecated
781 |
782 +- exiting
783 |
784 +- experimental --+
785 | |
9f88e537
FC
786 | +- experimental::bitwise
787 | |
3c3f8cd6
AB
788 | +- experimental::const_attr
789 | |
88d5dae9
FC
790 | +- experimental::declared_refs
791 | |
3c3f8cd6
AB
792 | +- experimental::lexical_subs
793 | |
3c3f8cd6
AB
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 |
52e3acf8
Z
862 +- shadow
863 |
3c3f8cd6
AB
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
a7f2b7af
RS
911
912Just 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
917Also like the "strict" pragma, if there is more than one instance of the
56873d42 918C<warnings> pragma in a given scope the cumulative effect is additive.
a7f2b7af
RS
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
926To determine which category a specific warning has been assigned to see
927L<perldiag>.
928
929Note: Before Perl 5.8.0, the lexical warnings category "deprecated" was a
930sub-category of the "syntax" category. It is now a top-level category
931in its own right.
932
3664866e
AB
933Note: Before 5.21.0, the "missing" lexical warnings category was
934internally defined to be the same as the "uninitialized" category. It
935is now a top-level category in its own right.
936
a7f2b7af
RS
937=head2 Fatal Warnings
938X<warning, fatal>
939
2e4abf26
DG
940The presence of the word "FATAL" in the category list will escalate
941warnings in those categories into fatal errors in that lexical scope.
942
943B<NOTE:> FATAL warnings should be used with care, particularly
944C<< FATAL => 'all' >>.
945
946Libraries using L<warnings::warn|/FUNCTIONS> for custom warning categories
947generally don't expect L<warnings::warn|/FUNCTIONS> to be fatal and can wind up
948in an unexpected state as a result. For XS modules issuing categorized
949warnings, such unanticipated exceptions could also expose memory leak bugs.
950
951Moreover, the Perl interpreter itself has had serious bugs involving
952fatalized warnings. For a summary of resolved and unresolved problems as
953of January 2015, please see
954L<this perl5-porters post|http://www.nntp.perl.org/group/perl.perl5.porters/2015/01/msg225235.html>.
955
956While some developers find fatalizing some warnings to be a useful
957defensive programming technique, using C<< FATAL => 'all' >> to fatalize
958all possible warning categories -- including custom ones -- is particularly
959risky. Therefore, the use of C<< FATAL => 'all' >> is
960L<discouraged|perlpolicy/discouraged>.
961
962The L<strictures|strictures/VERSION-2> module on CPAN offers one example of
963a warnings subset that the module's authors believe is relatively safe to
964fatalize.
965
966B<NOTE:> users of FATAL warnings, especially those using
967C<< FATAL => 'all' >>, should be fully aware that they are risking future
968portability of their programs by doing so. Perl makes absolutely no
969commitments to not introduce new warnings or warnings categories in the
970future; indeed, we explicitly reserve the right to do so. Code that may
971not warn now may warn in a future release of Perl if the Perl5 development
972team deems it in the best interests of the community to do so. Should code
973using FATAL warnings break due to the introduction of a new warning we will
974NOT consider it an incompatible change. Users of FATAL warnings should
975take special caution during upgrades to check to see if their code triggers
976any new warnings and should pay particular attention to the fine print of
977the documentation of the features they use to ensure they do not exploit
978features that are documented as risky, deprecated, or unspecified, or where
979the documentation says "so don't do that", or anything with the same sense
980and spirit. Use of such features in combination with FATAL warnings is
981ENTIRELY AT THE USER'S RISK.
982
983The following documentation describes how to use FATAL warnings but the
984perl5 porters strongly recommend that you understand the risks before doing
985so, especially for library code intended for use by others, as there is no
986way for downstream users to change the choice of fatal categories.
987
988In the code below, the use of C<time>, C<length>
a7f2b7af
RS
989and C<join> can all produce a C<"Useless use of xxx in void context">
990warning.
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
1005When run it produces this output
1006
1007 Useless use of time in void context at fatal line 3.
56873d42 1008 Useless use of length in void context at fatal line 7.
a7f2b7af
RS
1009
1010The scope where C<length> is used has escalated the C<void> warnings
1011category into a fatal error, so the program terminates immediately when it
1012encounters the warning.
1013
1014To explicitly turn off a "FATAL" warning you just disable the warning
1015it is associated with. So, for example, to disable the "void" warning
1016in the example above, either of these will do the trick:
1017
1018 no warnings qw(void);
1019 no warnings FATAL => qw(void);
1020
1021If you want to downgrade a warning that has been escalated into a fatal
1022error back to a normal warning, you can use the "NONFATAL" keyword. For
1023example, the code below will promote all warnings into fatal errors,
1024except for those in the "syntax" category.
1025
1026 use warnings FATAL => 'all', NONFATAL => 'syntax';
1027
1028As of Perl 5.20, instead of C<< use warnings FATAL => 'all'; >> you can
1029use:
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
1034If you want your program to be compatible with versions of Perl before
10355.20, you must use C<< use warnings FATAL => 'all'; >> instead. (In
1036previous versions of Perl, the behavior of the statements
1037C<< use warnings 'FATAL'; >>, C<< use warnings 'NONFATAL'; >> and
1038C<< no warnings 'FATAL'; >> was unspecified; they did not behave as if
1039they included the C<< => 'all' >> portion. As of 5.20, they do.)
1040
a7f2b7af
RS
1041=head2 Reporting Warnings from a Module
1042X<warning, reporting> X<warning, registering>
1043
1044The C<warnings> pragma provides a number of functions that are useful for
1045module authors. These are used when you want to report a module-specific
1046warning to a calling module has enabled warnings via the C<warnings>
1047pragma.
1048
1049Consider 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
1066The call to C<warnings::register> will create a new warnings category
1067called "MyMod::Abc", i.e. the new category name matches the current
1068package name. The C<open> function in the module will display a warning
1069message if it gets given a relative path as a parameter. This warnings
1070will only be displayed if the code that uses C<MyMod::Abc> has actually
1071enabled 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
1078It is also possible to test whether the pre-defined warnings categories are
1079set in the calling module with the C<warnings::enabled> function. Consider
1080this snippet of code:
1081
1082 package MyMod::Abc;
1083
1084 sub open {
4a21999a
TC
1085 if (warnings::enabled("deprecated")) {
1086 warnings::warn("deprecated",
1087 "open is deprecated, use new instead");
1088 }
a7f2b7af
RS
1089 new(@_);
1090 }
1091
1092 sub new
1093 ...
1094 1;
1095
1096The function C<open> has been deprecated, so code has been included to
1097display 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
1105Either the C<warnings::warn> or C<warnings::warnif> function should be
1106used to actually display the warnings message. This is because they can
1107make use of the feature that allows warnings to be escalated into fatal
1108errors. So in this case
1109
1110 use MyMod::Abc;
1111 use warnings FATAL => 'MyMod::Abc';
1112 ...
1113 MyMod::Abc::open('../fred.txt');
1114
1115the C<warnings::warnif> function will detect this and die after
1116displaying the warning message.
1117
1118The three warnings functions, C<warnings::warn>, C<warnings::warnif>
1119and C<warnings::enabled> can optionally take an object reference in place
1120of a category name. In this case the functions will use the class name
1121of the object as the warnings category.
1122
1123Consider 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
effd17dc
DD
1137 {
1138 my $self = shift;
1139 my $value = shift;
e476b1b5 1140
effd17dc
DD
1141 if ($value % 2 && warnings::enabled($self))
1142 { warnings::warn($self, "Odd numbers are unsafe") }
1143 }
599cee73 1144
effd17dc
DD
1145 sub doit
1146 {
1147 my $self = shift;
1148 my $value = shift;
1149 $self->check($value);
1150 # ...
1151 }
599cee73 1152
effd17dc 1153 1;
0d658bf5 1154
effd17dc 1155 package Derived;
0d658bf5 1156
effd17dc
DD
1157 use warnings::register;
1158 use Original;
1159 our @ISA = qw( Original );
1160 sub new
1161 {
1162 my $class = shift;
1163 bless [], $class;
1164 }
b88df990 1165
b88df990 1166
effd17dc 1167 1;
8457b38f 1168
56873d42 1169The code below makes use of both modules, but it only enables warnings from
effd17dc 1170C<Derived>.
8457b38f 1171
effd17dc
DD
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);
6f87cb12 1179
effd17dc 1180When this code is run only the C<Derived> object, C<$b>, will generate
56873d42 1181a warning.
6f87cb12 1182
effd17dc 1183 Odd numbers are unsafe at main.pl line 7
c8028aa6 1184
effd17dc
DD
1185Notice also that the warning is reported at the line where the object is first
1186used.
c8028aa6 1187
effd17dc
DD
1188When registering new categories of warning, you can supply more names to
1189warnings::register like this:
7ac92924 1190
effd17dc
DD
1191 package MyModule;
1192 use warnings::register qw(format precision);
7ac92924 1193
effd17dc 1194 ...
d3a7d8c7 1195
effd17dc 1196 warnings::warnif('MyModule::format', '...');
599cee73 1197
effd17dc 1198=head1 FUNCTIONS
599cee73 1199
c4583f59
FC
1200Note: The functions with names ending in C<_at_level> were added in Perl
12015.28.
1202
39b50539
Z
1203=over 4
1204
effd17dc 1205=item use warnings::register
599cee73 1206
effd17dc
DD
1207Creates a new warnings category with the same name as the package where
1208the call to the pragma is used.
c3186b65 1209
effd17dc 1210=item warnings::enabled()
6e9af7e4 1211
effd17dc 1212Use the warnings category with the same name as the current package.
599cee73 1213
effd17dc
DD
1214Return TRUE if that warnings category is enabled in the calling module.
1215Otherwise returns FALSE.
599cee73 1216
effd17dc 1217=item warnings::enabled($category)
4c02ac93 1218
effd17dc
DD
1219Return TRUE if the warnings category, C<$category>, is enabled in the
1220calling module.
1221Otherwise returns FALSE.
6e9af7e4 1222
effd17dc 1223=item warnings::enabled($object)
6e9af7e4 1224
effd17dc
DD
1225Use the name of the class for the object reference, C<$object>, as the
1226warnings category.
c91312d5 1227
effd17dc
DD
1228Return TRUE if that warnings category is enabled in the first scope
1229where the object is used.
1230Otherwise returns FALSE.
a7f2b7af 1231
c4583f59
FC
1232=item warnings::enabled_at_level($category, $level)
1233
1234Like C<warnings::enabled>, but $level specifies the exact call frame, 0
1235being the immediate caller.
1236
effd17dc 1237=item warnings::fatal_enabled()
599cee73 1238
effd17dc
DD
1239Return TRUE if the warnings category with the same name as the current
1240package has been set to FATAL in the calling module.
1241Otherwise returns FALSE.
6e9af7e4 1242
effd17dc 1243=item warnings::fatal_enabled($category)
6e9af7e4 1244
effd17dc
DD
1245Return TRUE if the warnings category C<$category> has been set to FATAL in
1246the calling module.
1247Otherwise returns FALSE.
6e9af7e4 1248
effd17dc 1249=item warnings::fatal_enabled($object)
6e9af7e4 1250
effd17dc
DD
1251Use the name of the class for the object reference, C<$object>, as the
1252warnings category.
6e9af7e4 1253
effd17dc
DD
1254Return TRUE if that warnings category has been set to FATAL in the first
1255scope where the object is used.
1256Otherwise returns FALSE.
599cee73 1257
c4583f59
FC
1258=item warnings::fatal_enabled_at_level($category, $level)
1259
1260Like C<warnings::fatal_enabled>, but $level specifies the exact call frame,
12610 being the immediate caller.
1262
effd17dc 1263=item warnings::warn($message)
9df0f64f 1264
effd17dc 1265Print C<$message> to STDERR.
8787a747 1266
effd17dc 1267Use the warnings category with the same name as the current package.
96183d25 1268
effd17dc
DD
1269If that warnings category has been set to "FATAL" in the calling module
1270then die. Otherwise return.
96183d25 1271
effd17dc 1272=item warnings::warn($category, $message)
d3a7d8c7 1273
effd17dc 1274Print C<$message> to STDERR.
d3a7d8c7 1275
effd17dc
DD
1276If the warnings category, C<$category>, has been set to "FATAL" in the
1277calling module then die. Otherwise return.
7e6d00f8 1278
effd17dc 1279=item warnings::warn($object, $message)
7e6d00f8 1280
effd17dc 1281Print C<$message> to STDERR.
8787a747 1282
effd17dc
DD
1283Use the name of the class for the object reference, C<$object>, as the
1284warnings category.
8787a747 1285
effd17dc
DD
1286If that warnings category has been set to "FATAL" in the scope where C<$object>
1287is first used then die. Otherwise return.
96183d25 1288
c4583f59
FC
1289=item warnings::warn_at_level($category, $level, $message)
1290
1291Like C<warnings::warn>, but $level specifies the exact call frame,
12920 being the immediate caller.
96183d25 1293
effd17dc 1294=item warnings::warnif($message)
96183d25 1295
effd17dc 1296Equivalent to:
7e6d00f8 1297
effd17dc
DD
1298 if (warnings::enabled())
1299 { warnings::warn($message) }
572bfd36 1300
effd17dc 1301=item warnings::warnif($category, $message)
572bfd36 1302
effd17dc 1303Equivalent to:
572bfd36 1304
effd17dc
DD
1305 if (warnings::enabled($category))
1306 { warnings::warn($category, $message) }
572bfd36 1307
effd17dc 1308=item warnings::warnif($object, $message)
4f527b71 1309
effd17dc 1310Equivalent to:
599cee73 1311
effd17dc
DD
1312 if (warnings::enabled($object))
1313 { warnings::warn($object, $message) }
d3a7d8c7 1314
c4583f59
FC
1315=item warnings::warnif_at_level($category, $level, $message)
1316
1317Like C<warnings::warnif>, but $level specifies the exact call frame,
13180 being the immediate caller.
1319
effd17dc 1320=item warnings::register_categories(@names)
e476b1b5 1321
effd17dc
DD
1322This registers warning categories for the given names and is primarily for
1323use by the warnings::register pragma.
0d658bf5 1324
effd17dc 1325=back
8787a747 1326
effd17dc
DD
1327See also L<perlmodlib/Pragmatic Modules> and L<perldiag>.
1328
1329=cut
ce716c52 1330
37442d52 1331# ex: set ro: