#

## Issue BROADCAST-STREAM-RETURN-VALUES Writeup

    Issue:        BROADCAST-STREAM-RETURN-VALUES
    Forum:        X3J13 Letter Ballot
    References:   BROADCAST-STREAM (X3J13/92-102, p21-7)
    Category:     CLARIFICATION
    Edit history: 16-Jun-93, Version 1 by Pitman
                  17-Jun-93, Version 2 by Loosemore
    			(fix bugs, separate incompatible changes)
    Status:	      Proposal CLARIFY-MINIMALLY passed 9-2 on letter ballot 93/304

    Problem Description:

      The description of the return value for output operations applied
      to broadcast streams doesn't work well for certain kinds of operations,
      STREAM-ELEMENT-TYPE being an example.

      The zero-argument stream case is important, too, because
        (MAKE-BROADCAST-STREAM)
      is a commonly-used portable way to create a null output stream.

      Proposal CLARIFY-MINIMALLY makes explicit the "results from the last
      stream" rule from CLtL, and specifies behavior for the cases where there
      are no streams.  Proposal INCOMPATIBLE-CHANGES replaces this rule with
      behavior that makes more sense.

    Proposal (BROADCAST-STREAM-RETURN-VALUES:CLARIFY-MINIMALLY):

      STREAM-ELEMENT-TYPE returns the value from the last component stream, or
      T if there are no streams.

      FRESH-LINE returns the value from the last component stream, or NIL
      if there are no streams.

      The following functions return the value from the last component stream,
      or the indicated value if there are no component streams:

        FILE-LENGTH [0]
        FILE-POSITION [0]
        FILE-STRING-LENGTH [1]
        STREAM-EXTERNAL-FORMAT [:DEFAULT]

      STREAMP and OUTPUT-STREAM-P always return true for broadcast streams.
      OPEN-STREAM-P tests whether the broadcast stream is open, not whether its
      component streams are open.  INPUT-STREAM-P and INTERACTIVE-STREAM-P
      return an implementation-defined boolean value.

      For these input operations, the consequences are undefined if the indicated
      operation is performed.  (However, implementations that wish to are permitted
      to extend the behavior.)

        READ-BYTE
        READ-CHAR
        READ-CHAR-NO-HANG
        PEEK-CHAR
        UNREAD-CHAR
        READ-LINE
        LISTEN
        CLEAR-INPUT

    Proposal (BROADCAST-STREAM-RETURN-VALUES:INCOMPATIBLE-CHANGES):

      STREAM-ELEMENT-TYPE returns the type-specifier-equivalent of
      `(AND ,x1 ,x2 ...), where each Xi is the result for each component stream.

      FRESH-LINE returns the OR of the results for each component stream.

      For the following, if the streams are of the same element type and
      individually return the same result, that result is returned.
      Otherwise, the consequences are undefined.  (If there are no streams,
      the result shown in brackets is returned.)

        FILE-LENGTH [0]
        FILE-POSITION [0]
        FILE-STRING-LENGTH [1]
        STREAM-EXTERNAL-FORMAT [:DEFAULT]

      STREAMP and OUTPUT-STREAM-P always return true for broadcast streams.
      OPEN-STREAM-P tests whether the broadcast stream is open, not whether its
      component streams are open.  INPUT-STREAM-P and INTERACTIVE-STREAM-P
      return an implementation-defined boolean value.

      For these input operations, the consequences are undefined if the indicated
      operation is performed.  (However, implementations that wish to are permitted
      to extend the behavior.)

        READ-BYTE
        READ-CHAR
        READ-CHAR-NO-HANG
        PEEK-CHAR
        UNREAD-CHAR
        READ-LINE
        LISTEN
        CLEAR-INPUT

    Test Case:

      Not provided.

    Rationale:

      These values provide plausible defaults for the cases where there is likely
      to be no controversy, without trying to define the cases in the gray areas.

    Current Practice:

      Not provided.

    Cost to Implementors:

      Probably relatively small.

    Cost to Users:

      None.  This change doesn't affect anything already guaranteed to the user.

    Cost of Non-Adoption:

      Broadcast streams are hard to use reliably in many situations.

    Benefits:

      Better program portability.

    Editorial Impact:

      Small.  A number of small, localized edits.

    Aesthetics:

      Mostly neutral.

    Discussion:

      This addresses Barrett comment #12 (First Public Review).
      Pitman thinks it's a good idea to clarify this somehow and is mostly
      happy with the above, but might be satisfied with other variations on
      this theme, as long as they were intuitive, implementable, etc.

      Loosemore notes that we have already approved a previous issue
      (PATHNAME-STREAM) to make coercing a broadcast stream to a pathname
      have undefined consequences.  Likewise, we have already decided that
      calling CLOSE on a broadcast stream closes only the broadcast stream
      and not its component streams.

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