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