#

## Issue STREAM-ACCESS Writeup

    Proposal ADD-TYPES-ACCESSORS was accepted at the January 1989 meeting.

    -----
    Issue:		STREAM-ACCESS
    References:	streams (Chapter 21 of CLtL)
    Category:	ADDITION
    Edit History:	17-Jun-88, version 1 by Walter van Roggen
    			30-Nov-88, version 2 by Masinter

    Problem Description:

      There are many components of streams which are specified upon creation
      but are not accessible afterwards.  Furthermore there is no way in
      Common Lisp to determine the type of a stream to see if it has particular
      components, or even if it is OPEN.

      The accessors wanted are those associated with broadcast streams,
      concatenated streams, echo streams, file streams, string streams,
      synonym streams, two way streams.

      There are three proposals, which differ only by the whether
      they include types, type predicates, or both, in addition to
      the stream component acessors. Ballots can be either for
      one of the proposals or none. (Other combinations of, say,
      accessors without either predicates or types, or types without
      accessors, do not seem reasonable and are not being proposed
      at this time.)

    Proposal STREAM-ACCESS:ADD-TYPES-PREDICATES-ACCESSORS

    First, add a function to determine whether a stream is "OPEN":

    OPEN-STREAM-P stream			[Function]

          Returns T if a stream is open, NIL if it is closed.  It is an error
          if the argument is not a stream.

        Streams are "open" until they have been closed with
        CLOSE, or, the dynamic context of the creating/accessing
        macros of  WITH-OUTPUT-TO-STRING, WITH-OPEN-FILE,
        WITH-INPUT-FROM-STRING,  WITH-OPEN-STREAM,
        have been exited.

    There are three kinds of things to add associated with each kind of
    stream: data types, predicates, accessors.

    Stream data types:
       BROADCAST-STREAM (returned by MAKE-BROADCAST-STREAM)
       CONCATENATED-STREAM (returned by MAKE-CONCATENATED-STREAM)
       ECHO-STREAM (returned by MAKE-ECHO-STREAM)
       FILE-STREAM (returned by OPEN or created by WITH-OPEN-FILE)
       STRING-STREAM (returned by MAKE-STRING-INPUT-STREAM,
    	MAKE-STRING-OUTPUT-STREAM, and created by WITH-INPUT-FROM-STRING
          and WITH-OUTPUT-TO-STRING and FORMAT with second argument NIL)
      SYNONYM-STREAM (created by MAKE-SYNONYM-STREAM)
      TWO-WAY-STREAM (created by  MAKE-TWO-WAY-STREAM)

      The stream data types are all subtypes of type STREAM and are mutually
      exclusive. (In particular, a synonym stream is only of type SYNONYM-STREAM.)

    Stream Predicates:

      Each of these returns T if the object is of the corresponding type,
      and NIL otherwise.

        BROADCAST-STREAM-P, CONCATENATED-STREAM-P,
        ECHO-STREAM-P, FILE-STREAM-P, STRING-STREAM-P,
        SYNONYM-STREAM-P, TWO-WAY-STREAM-P

      Note that the predicates do not "follow the link" of a synonym
      stream.

    Stream Informational Functions:

      BROADCAST-STREAM-STREAMS broadcast-stream       ==> list of streams

          This function returns a list of output streams that constitute
          all the streams the broadcast stream is broadcasting to.  It is
          an error if the argument is not of type BROADCAST-STREAM.

      CONCATENATED-STREAM-STREAMS concatenated-stream ==> list of streams

          This function returns a list of input streams that constitute
          the ordered set of streams the concatenated stream still has to
          to read from, starting with the current one it is reading from.
          The list may be () if no more streams remain to be read.
          It is an error if the argument is not of type CONCATENATED-STREAM.

      ECHO-STREAM-INPUT-STREAM echo-stream            ==> input-stream
      ECHO-STREAM-OUTPUT-STREAM echo-stream           ==> output-stream

          These functions return the corresponding component stream.  It is
          an error if the argument is not of type ECHO-STREAM.

      SYNONYM-STREAM-SYMBOL synonym-stream            ==> symbol

          This function returns the symbol whose SYMBOL-VALUE the
          synonym stream is using.  It is
          an error if the argument is not of type SYNONYM-STREAM.

      TWO-WAY-STREAM-INPUT-STREAM two-way-stream      ==> input-stream
      TWO-WAY-STREAM-OUTPUT-STREAM two-way-stream     ==> output-stream

          These functions return the corresponding component stream.  It is
          an error if the argument is not of type TWO-WAY-STREAM.

    Proposal: STREAM-ACCESS:ADD-TYPES-ACCESSORS

    Identical to ADD-TYPES-PREDICATES-ACCESSORS except to leave out the
    stream type predicates.

    Proposal: STREAM-ACCESS:ADD-PREDICATES-ACCESSORS

    Identical to ADD-TYPES-PREDICATES-ACCESSORS except to not
    identify new data types. The accessors act as if the types were specified
    (i.e., are mutually excusive).

    Current Practice:

    VAX LISP implements ADD-TYPES-PREDICATES-ACCESSORS.
     We have not surveyed other implementations.

    Cost to Implementors:

      All of the proposals are reasonably simple to implement, since the information
      must be present for nearly all types.

    Cost to Users:

      The proposals are upward-compatible, and should have little impact.

    Cost of Non-Adoption:

      The benefits would not be available in a portable fashion.

    Benefits:

      Programs would be able to access useful information otherwise hidden.

    Discussion:

      This issue has come up frequently, particularly dealing with SYNONYM-STREAMs.

      The behavior of OPEN-STREAM-P on, for example, broadcast streams, might
      be specified in a variety of alternative ways. This specification seems the simplest.

      There are three proposals for voting because there was no agreement at the
      October X3J13 on the issue of whether types, predicates, or both should be
     added.

      There was a proposal at one time to add a new function FOLLOW-SYNONYM-STREAM
      which could be written as
       (defun follow-synonym-stream (x)
         (if (synonym-stream-p x)
             (follow-synonym-stream (symbol-value (synonym-stream-symbol x)))
             x))

      i.e., which chases through zero or more synonym stream indirections.

Copyright 1996-2005, LispWorks Ltd. All rights reserved.