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