New issue: WITH-OPEN-FILE-DOES-NOT-EXIST

[peck@Sun.COM]

    Really a request for an editorial change, so users will know what
to expect. A user actually reported this as a bug...
Unless someone believes that STREAM-IS-NIL is wrong, this could just
be forwarded to editorial.

Issue:         WITH-OPEN-FILE-DOES-NOT-EXIST
References:    CLtL page 422
Category:      Clarify
Edit history:  17-Mar-89, Version 1

Problem description:
The documentation for WITH-OPEN-FILE (p 422) says:
  "WITH-OPEN-FILE evaluates the Forms of the body (an implict PROGN)
with the variable Stream bound to a stream that reads or writes the
file named by the value of Filename. The options are evaluated and
used as keyword arguments to the function OPEN."

  It is not clear what to do when there is no stream
"that reads or writes the file" named by Filename.
  Is the body evaluated? What is Stream bound to?

Proposal: WITH-OPEN-FILE-DOES-NOT-EXIST:DONT-EVALUATE
  If the result of OPEN does not return a stream (eg returns NIL)
Then the body of WITH-OPEN-FILE is not evaluated, NIL is returned.

Rationale:
  The contract that "the body is evaluated with ... bound to a stream"
is maintained in the sense of a vacuous evalation.
  The alternatives are:
    To let the stream variable be bound to NIL (unintuitive and dangerous).
    If users want to Signal-An-Error in this case, they can use
    :if-does-not-exist :error  
  The test for (STREAMP Stream) is probably done anyway,
    since the UNWIND-PROTECT cleanup form can't call CLOSE on NIL.

Proposal: WITH-OPEN-FILE-DOES-NOT-EXIST:STREAM-IS-NIL
  Clarify the documentation to explain that:
    Stream is bound to the value returned by OPEN.
    Users of :if-does-not-exist NIL should check for a valid stream.

Rationale:
  This simple to implement, no extra testing is done.
  Users who use :if-does-not-exist NIL  can wrap their body forms
with (when (STREAMP Stream) ...)

Examples:
1. (WITH-OPEN-FILE (foo "no-such-file" :IF-DOES-NOT-EXIST nil)
	(READ foo) t)
   DONT-EVALUATE: => NIL, no I/O is done, do not read from *standard-input*
   STREAM-IS-NIL: => T, reads from *standard-input*

2. (WITH-OPEN-FILE (foo "/no-dir" :direction :output :IF-DOES-NOT-EXIST nil)
	(format foo t) t)
   DONT-EVALUATE: => NIL, no string is created.
   STREAM-IS-NIL: => T, creates a string and writes to it.

Current practice:
    Symbolics and Lucid apparently implement STREAM-IS-NIL.

Cost to Implementors:
    STREAM-IS-NIL: no cost.
    DONT-EVALUATE:
        Trivial? to test for :if-does-not-exist NIL and supply a 
        test for (STREAMP Stream) in that case [or in every case].

Cost to Users:
    DONT-EVALUATE: System tests for (STREAMP Stream), possibly extraneously.
    STREAM-IS-NIL: User must write a test for (STREAMP Stream).
  Probably no portable code uses :if-does-not-exist NIL without
  testing explicitly for (STREAMP Stream).

Cost of non-adoption:
    The current situation is non-intuitive and/or confusing.

Benefits:
    Users would know if the STREAMP test has been done or whether 
they must supply it.

Esthetics:

Discussion: