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