-;;; HOW THE STREAM STRUCTURE IS USED:
-;;;
-;;; Many of the slots of the stream structure contain functions
-;;; which are called to perform some operation on the stream. Closed
-;;; streams have #'CLOSED-FLAME in all of their function slots. If
-;;; one side of an I/O or echo stream is closed, the whole stream is
-;;; considered closed. The functions in the operation slots take
-;;; arguments as follows:
-;;;
-;;; In: Stream, Eof-Errorp, Eof-Value
-;;; Bin: Stream, Eof-Errorp, Eof-Value
-;;; N-Bin: Stream, Buffer, Start, Numbytes, Eof-Errorp
-;;; Out: Stream, Character
-;;; Bout: Stream, Integer
-;;; Sout: Stream, String, Start, End
-;;; Misc: Stream, Operation, &Optional Arg1, Arg2
-;;;
-;;; In order to save space, some of the less common stream operations
-;;; are handled by just one function, the MISC method. This function
-;;; is passed a keyword which indicates the operation to perform.
-;;; The following keywords are used:
-;;; :listen - Return the following values:
-;;; t if any input waiting.
-;;; :eof if at eof.
-;;; nil if no input is available and not at eof.
-;;; :unread - Unread the character Arg.
-;;; :close - Do any stream specific stuff to close the stream.
-;;; The methods are set to closed-flame by the close
-;;; function, so that need not be done by this
-;;; function.
-;;; :clear-input - Clear any unread input
-;;; :finish-output,
-;;; :force-output - Cause output to happen
-;;; :clear-output - Clear any undone output
-;;; :element-type - Return the type of element the stream deals with.
-;;; :line-length - Return the length of a line of output.
-;;; :charpos - Return current output position on the line.
-;;; :file-length - Return the file length of a file stream.
-;;; :file-position - Return or change the current position of a
-;;; file stream.
-;;; :file-name - Return the name of an associated file.
-;;; :interactive-p - Is this an interactive device?
-;;;
-;;; In order to do almost anything useful, it is necessary to
-;;; define a new type of structure that includes stream, so that the
-;;; stream can have some state information.
-;;;
-;;; THE STREAM IN-BUFFER:
-;;;
-;;; The IN-BUFFER in the stream holds characters or bytes that
-;;; are ready to be read by some input function. If there is any
-;;; stuff in the IN-BUFFER, then the reading function can use it
-;;; without calling any stream method. Any stream may put stuff in
-;;; the IN-BUFFER, and may also assume that any input in the IN-BUFFER
-;;; has been consumed before any in-method is called. If a text
-;;; stream has in IN-BUFFER, then the first character should not be
-;;; used to buffer normal input so that it is free for unreading into.
-;;;
-;;; The IN-BUFFER slot is a vector +IN-BUFFER-LENGTH+ long. The
-;;; IN-INDEX is the index in the IN-BUFFER of the first available
-;;; object. The available objects are thus between IN-INDEX and the
-;;; length of the IN-BUFFER.
-;;;
-;;; When this buffer is only accessed by the normal stream
-;;; functions, the number of function calls is halved, thus
-;;; potentially doubling the speed of simple operations. If the
-;;; FAST-READ-CHAR and FAST-READ-BYTE macros are used, nearly all
-;;; function call overhead is removed, vastly speeding up these
-;;; important operations.
-;;;
-;;; If a stream does not have an IN-BUFFER, then the IN-BUFFER slot
-;;; must be nil, and the IN-INDEX must be +IN-BUFFER-LENGTH+. These are
-;;; the default values for the slots.
-\f