README.lexwarn

   1 Date: 29th July 1998
   2
   3 This patch adds lexical warnings to Perl. It should apply over
   4 5.005_50
   5
   6 NOTE: This is a prototype. Do not assume that lexical warnings will
   7       necessarily be anything like this implementation.
   8
   9 Changes
  10 =======
  11
  12   Date: 8th April 1998
  13
  14     * patch now applies cleanly over 5.004_64
  15
  16     * added the -X switch (the inverse "lint" command)
  17
  18   Date: 26th Feb 1997
  19
  20     * By popular demand, the warnings bitmask can now be of arbitrary
  21       length. The code uses an SV* to store the bitmask.
  22
  23     * Rationalised the warning categories a bit. This area still needs
  24       a lot of work.
  25
  26     * Added -W switch (the "lint" command).
  27
  28     * Added an experimental feature to allow warnings to be excalated
  29       to fatal errors.
  30
  31
  32 The "use warning" pragma
  33 ========================
  34
  35     The "use warning" pragma is intended to replace both the use of the
  36     command line flag "-w" and its equivalent variable $^W with a pragma
  37     that works like the existing "strict" pragma.
  38
  39     This means that the scope of the pragma is limited to the enclosing
  40     block. It also means that that a pragma setting will not leak across
  41     files (via use/require/do). This will allow authors to define the
  42     degree of warning checks that will be applied to their module.
  43
  44     By default warnings are disabled.
  45
  46     All warnings are enabled in a block by either of these:
  47
  48         use warning ;
  49         use warning 'all' ;
  50
  51     Similarly all warnings are disabled in a block by either of these:
  52
  53         no warning ;
  54         no warning 'all' ;
  55
  56     A hierarchy of "categories" have been defined to allow groups of
  57     warnings to be enabled/disabled in isolation.  The current
  58     hierarchy is:
  59
  60         all - +--- unsafe -------+--- taint
  61               |                  |
  62               |                  +--- substr
  63               |                  |
  64               |                  +--- signal
  65               |                  |
  66               |                  +--- closure
  67               |                  |
  68               |                  +--- untie
  69               |
  70               +--- io   ---------+--- pipe
  71               |                  |
  72               |                  +--- unopened
  73               |                  |
  74               |                  +--- closed
  75               |                  |
  76               |                  +--- newline
  77               |                  |
  78               |                  +--- exec
  79               |
  80               +--- syntax    ----+--- ambiguous
  81               |                  |
  82               |                  +--- semicolon
  83               |                  |
  84               |                  +--- precedence
  85               |                  |
  86               |                  +--- reserved
  87               |                  |
  88               |                  +--- octal
  89               |                  |
  90               |                  +--- parenthesis
  91               |                  |
  92               |                  +--- deprecated
  93               |
  94               |--- uninitialized
  95               |
  96               +--- void
  97               |
  98               +--- recursion
  99               |
 100               +--- redefine
 101               |
 102               +--- numeric
 103               |
 104               +--- once
 105               |
 106               +--- misc
 107
 108     This hierarchy is very tentative. Feedback is needed.
 109
 110     Just like the "strict" pragma any of these categories can be
 111     combined
 112
 113         use warning qw(void redefine) ;
 114         no warning qw(io syntax untie) ;
 115
 116 The "lint" flag, -W
 117 ===================
 118
 119 If the -W flag is used on the command line, it will enable all warnings
 120 throughout the program regardless of whether warnings were disabled
 121 locally using "no warning" or $^W =0. This includes any file that gets
 122 included during compilation via use/require.
 123
 124 The inverse "lint" flag, -X
 125 ===========================
 126 Does exactly the same as the -W flag, except it disables all warnings.
 127
 128
 129 Backward Compatability
 130 ======================
 131
 132     How Lexical Warnings interact with -w/$^W
 133
 134     1. The -w flag just sets the global $^W variable as in 5.004
 135        This means that any legacy code that currently relies on
 136        manipulating $^W to control warning behaviour will still work.
 137
 138     2. Apart from now being a boolean, the $^W variable operates in
 139        exactly the same horrible uncontrolled global way as in 5.004,
 140        except...
 141
 142     3. If a piece of code is under the control of a lexical warning
 143        pragma, the $^W variable will be ignored.
 144
 145        The combined effect of 2 & 3 is that it will will allow new code
 146        which will use the lexical warning pragma to control old
 147        $^W-type code (using a local $^W=0) if it really wants to, but
 148        not vice-versa.
 149
 150     4. The only way to override a lexical warnings setting is with the
 151        new -W or -X command line flags.
 152
 153
 154 Fatal Warnings
 155 ==============
 156
 157 This feature is very experimental.
 158
 159 The presence of the word "FATAL" in the category list will escalate any
 160 warnings from the category specified that are detected in the lexical
 161 scope into fatal errors. In the code below, there are 3 places where a
 162 deprecated warning will be detected, the middle one will produce a
 163 fatal error.
 164
 165
 166     use warning ;
 167
 168     $a = 1 if $a EQ $b ;
 169
 170     {
 171         use warning qw(FATAL deprecated) ;
 172         $a = 1 if $a EQ $b ;
 173     }
 174
 175     $a = 1 if $a EQ $b ;
 176
 177
 178 TODO
 179 ====
 180
 181 test harness for -X (assuming it is a permanent fixture).
 182 win32, os2 & vms all have warnings. These need to be included.
 183
 184 Unresolved Issues
 185 =================
 186
 187   The pragma name?
 188     A few possibilities:
 189         warning
 190         warnings
 191         warn
 192
 193   Hierarchy of Warnings
 194     The current patch has a fairly arbitrary hierarchy.
 195     Ideas for a useful hierarchy would be most welcome.
 196
 197   A command line option to turn off all warnings?
 198      -X or -q, perhaps.
 199
 200   Current mandatory warnings.
 201     May be useful to bring them under the control of this pragma.
 202
 203   Severity
 204     Do we want/need a severity classification?
 205         pedantic
 206         high/strict/precise
 207         medium/default
 208         low/common
 209
 210   Versions
 211     This is a thorhy issue. Say someone writes a script using Perl
 212     5.004 and places this at the top:
 213
 214         use warning ;
 215
 216     Time passes and 5.005 comes out. It has added a few extra warnings.
 217     The script prints warning messages.
 218
 219     A possibility is to allow the warnings that are checked to be
 220     limited to those available in a given version of Perl. A possible
 221     syntax could be:
 222
 223         use warning 5.004 ;
 224
 225     or
 226
 227         use warning 5.004 qw(void uninitialized) ;
 228
 229     Do we really need this amount of control?
 230
 231   Documentation
 232     There isn't any yet.
 233
 234
 235   perl5db.pl
 236     The debugger saves and restores $^W at runtime. I haven't checked
 237     whether the debugger will still work with the lexical warnings
 238     patch applied.
 239
 240   diagnostics.pm
 241     I *think* I've got diagnostics to work with the lexiacal warnings
 242     patch, but there were design decisions made in diagnostics to work
 243     around the limitations of $^W. Now that those limitations are gone,
 244     the module should be revisited.