lib/warnings.pm

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