[perl5.git] / README.lexwarn

Date: 29th July 1998

This patch adds lexical warnings to Perl. It should apply over
5.005_50

NOTE: This is a prototype. Do not assume that lexical warnings will
      necessarily be anything like this implementation.

Changes 
=======

  Date: 8th April 1998

    * patch now applies cleanly over 5.004_64

    * added the -X switch (the inverse "lint" command)

  Date: 26th Feb 1997

    * By popular demand, the warnings bitmask can now be of arbitrary
      length. The code uses an SV* to store the bitmask.

    * Rationalised the warning categories a bit. This area still needs
      a lot of work.

    * Added -W switch (the "lint" command).

    * Added an experimental feature to allow warnings to be excalated
      to fatal errors.


The "use warning" pragma
========================

    The "use warning" pragma is intended to replace both the use of the
    command line flag "-w" and its equivalent variable $^W with a pragma
    that works like the existing "strict" pragma.

    This means that the scope of the pragma is limited to the enclosing
    block. It also means that that a pragma setting will not leak across
    files (via use/require/do). This will allow authors to define the
    degree of warning checks that will be applied to their module.

    By default warnings are disabled.

    All warnings are enabled in a block by either of these:

	use warning ;
	use warning 'all' ;

    Similarly all warnings are disabled in a block by either of these:

	no warning ;
	no warning 'all' ;

    A hierarchy of "categories" have been defined to allow groups of
    warnings to be enabled/disabled in isolation.  The current
    hierarchy is:

	all - +--- unsafe -------+--- taint
	      |			 |
	      |			 +--- substr
	      |			 |
	      |			 +--- signal
	      |			 |
	      |			 +--- closure
	      |			 |
	      |			 +--- untie
	      |			 
	      +--- io	---------+--- pipe
	      |			 |
	      |			 +--- unopened
	      |			 |
	      |			 +--- closed
	      |			 |
	      |			 +--- newline
	      |			 |
	      |			 +--- exec
	      |
	      +--- syntax    ----+--- ambiguous
	      |			 |
	      |			 +--- semicolon
	      |			 |
	      |			 +--- precedence
	      |			 |
	      |			 +--- reserved
	      |			 |
	      |			 +--- octal
	      |			 |
	      |			 +--- parenthesis
	      |			 |
	      |			 +--- deprecated
	      |
	      |--- uninitialized
	      |
	      +--- void
	      |
	      +--- recursion
	      |
	      +--- redefine
	      |
	      +--- numeric
	      |
	      +--- once
	      |
	      +--- misc

    This hierarchy is very tentative. Feedback is needed.

    Just like the "strict" pragma any of these categories can be
    combined

	use warning qw(void redefine) ;
	no warning qw(io syntax untie) ;

The "lint" flag, -W
===================

If the -W flag is used on the command line, it will enable all warnings
throughout the program regardless of whether warnings were disabled
locally using "no warning" or $^W =0. This includes any file that gets
included during compilation via use/require.

The inverse "lint" flag, -X
===========================
Does exactly the same as the -W flag, except it disables all warnings.


Backward Compatability
======================

    How Lexical Warnings interact with -w/$^W

    1. The -w flag just sets the global $^W variable as in 5.004
       This means that any legacy code that currently relies on
       manipulating $^W to control warning behaviour will still work.

    2. Apart from now being a boolean, the $^W variable operates in
       exactly the same horrible uncontrolled global way as in 5.004,
       except...

    3. If a piece of code is under the control of a lexical warning
       pragma, the $^W variable will be ignored.
 
       The combined effect of 2 & 3 is that it will will allow new code
       which will use the lexical warning pragma to control old
       $^W-type code (using a local $^W=0) if it really wants to, but
       not vice-versa.
 
    4. The only way to override a lexical warnings setting is with the
       new -W or -X command line flags.


Fatal Warnings
==============

This feature is very experimental.

The presence of the word "FATAL" in the category list will escalate any
warnings from the category specified that are detected in the lexical
scope into fatal errors. In the code below, there are 3 places where a
deprecated warning will be detected, the middle one will produce a
fatal error.


    use warning ;

    $a = 1 if $a EQ $b ;

    {
	use warning qw(FATAL deprecated) ;
        $a = 1 if $a EQ $b ;
    }

    $a = 1 if $a EQ $b ;


TODO
====

test harness for -X (assuming it is a permanent fixture).
win32, os2 & vms all have warnings. These need to be included.

Unresolved Issues
=================

  The pragma name?
    A few possibilities:
	warning
	warnings
	warn

  Hierarchy of Warnings
    The current patch has a fairly arbitrary hierarchy.
    Ideas for a useful hierarchy would be most welcome.

  A command line option to turn off all warnings?
     -X or -q, perhaps.

  Current mandatory warnings.
    May be useful to bring them under the control of this pragma.

  Severity
    Do we want/need a severity classification?
        pedantic
        high/strict/precise
        medium/default
        low/common
    
  Versions
    This is a thorhy issue. Say someone writes a script using Perl
    5.004 and places this at the top:

	use warning ;

    Time passes and 5.005 comes out. It has added a few extra warnings.
    The script prints warning messages.

    A possibility is to allow the warnings that are checked to be
    limited to those available in a given version of Perl. A possible
    syntax could be:

	use warning 5.004 ;

    or

	use warning 5.004 qw(void uninitialized) ;

    Do we really need this amount of control?

  Documentation
    There isn't any yet.


  perl5db.pl
    The debugger saves and restores $^W at runtime. I haven't checked
    whether the debugger will still work with the lexical warnings
    patch applied.

  diagnostics.pm
    I *think* I've got diagnostics to work with the lexiacal warnings
    patch, but there were design decisions made in diagnostics to work
    around the limitations of $^W. Now that those limitations are gone,
    the module should be revisited.
Commit	Line	Data
599cee73 PM	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.