From 74d673b79d680edd34d2d8a04463dec2a0e5ab21 Mon Sep 17 00:00:00 2001
From: dtc <dtc>
Date: Tue, 2 Jun 1998 02:43:15 +0000
Subject: [PATCH] Integrate some of the documentation from the original
 stream-definition-by-user proposal by David N. Gray.

---
 pcl/gray-streams-class.lisp |   3 +-
 pcl/gray-streams.lisp       | 157 ++++++++++++++++++++++++++++--------
 2 files changed, 126 insertions(+), 34 deletions(-)

diff --git a/pcl/gray-streams-class.lisp b/pcl/gray-streams-class.lisp
index 6b25a4c33..6411c273d 100644
--- a/pcl/gray-streams-class.lisp
+++ b/pcl/gray-streams-class.lisp
@@ -4,11 +4,12 @@
 ;;; the Public domain, and is provided 'as is'.
 ;;;
 (ext:file-comment
-  "$Header: /Volumes/share2/src/cmucl/cvs2git/cvsroot/src/pcl/gray-streams-class.lisp,v 1.1 1998/05/05 00:33:19 dtc Exp $")
+  "$Header: /Volumes/share2/src/cmucl/cvs2git/cvsroot/src/pcl/gray-streams-class.lisp,v 1.2 1998/06/02 02:43:15 dtc Exp $")
 ;;;
 ;;; **********************************************************************
 ;;;
 ;;; Class definitions for the CMUCL Gray streams implementation.
+;;; Based on the stream-definition-by-user proposal by David N. Gray.
 ;;;
 
 (in-package "LISP")
diff --git a/pcl/gray-streams.lisp b/pcl/gray-streams.lisp
index 289a79af1..c1b05a192 100644
--- a/pcl/gray-streams.lisp
+++ b/pcl/gray-streams.lisp
@@ -4,11 +4,12 @@
 ;;; the Public domain, and is provided 'as is'.
 ;;;
 (ext:file-comment
-  "$Header: /Volumes/share2/src/cmucl/cvs2git/cvsroot/src/pcl/gray-streams.lisp,v 1.1 1998/05/05 00:33:20 dtc Exp $")
+  "$Header: /Volumes/share2/src/cmucl/cvs2git/cvsroot/src/pcl/gray-streams.lisp,v 1.2 1998/06/02 02:43:15 dtc Exp $")
 ;;;
 ;;; **********************************************************************
 ;;;
 ;;; Gray streams implementation for CMUCL.
+;;; Based on the stream-definition-by-user proposal by David N. Gray.
 ;;;
 
 (in-package "LISP")
@@ -18,7 +19,10 @@
 (fmakunbound 'stream-element-type)
 
 (defgeneric stream-element-type (stream)
-  (:documentation "Returns a type specifier for the kind of object returned by the Stream."))
+  (:documentation
+   "Returns a type specifier for the kind of object returned by the
+  Stream. Class FUNDAMENTAL-CHARACTER-STREAM provides a default method
+  which returns CHARACTER."))
 
 (defmethod stream-element-type ((stream lisp-stream))
   (funcall (lisp-stream-misc stream) stream :element-type))
@@ -29,7 +33,10 @@
 
 
 (defgeneric pcl-open-stream-p (stream)
-  (:documentation "Return true if Stream is not closed."))
+  (:documentation
+   "Return true if Stream is not closed.  A default method is provided
+  by class FUNDAMENTAL-STREAM which returns true if CLOSE has not been
+  called on the stream."))
 
 (defmethod pcl-open-stream-p ((stream lisp-stream))
   (not (eq (lisp-stream-in stream) #'closed-flame)))
@@ -45,9 +52,10 @@
 
 
 (defgeneric pcl-close (stream &key abort)
-  (:documentation "Closes the given Stream.  No more I/O may be performed, but inquiries
-  may still be made.  If :Abort is non-nil, an attempt is made to clean
-  up the side effects of having created the stream."))
+  (:documentation
+   "Closes the given Stream.  No more I/O may be performed, but
+  inquiries may still be made.  If :Abort is non-nil, an attempt is made
+  to clean up the side effects of having created the stream."))
 
 (defmethod pcl-close ((stream lisp-stream) &key abort)
   (when (open-stream-p stream)
@@ -88,23 +96,41 @@
 
 
 ;;; Character input streams.
+;;;
+;;; A character input stream can be created by defining a class that
+;;; includes FUNDAMENTAL-CHARACTER-INPUT-STREAM and defining methods
+;;; for the generic functions below.
 
 (defgeneric stream-read-char (stream)
-  (:documentation "Reads one character, :eof on end of file."))
+  (:documentation
+   "This reads one character from the stream.  It returns either a
+  character object, or the symbol :EOF if the stream is at end-of-file.
+  Every subclass of FUNDAMENTAL-CHARACTER-INPUT-STREAM must define a
+  method for this function."))
 
 (defgeneric stream-unread-char (stream character)
-  (:documentation "Unreads one character, and returns nil."))
+  (:documentation
+   "Un-does the last call to STREAM-READ-CHAR, as in UNREAD-CHAR.
+  Returns NIL.  Every subclass of FUNDAMENTAL-CHARACTER-INPUT-STREAM
+  must define a method for this function."))
 
 (defgeneric stream-read-char-no-hang (stream)
-  (:documentation "Reads either a character, or NIL is none is available,
-  and :eof on end of file."))
+  (:documentation
+   "This is used to implement READ-CHAR-NO-HANG.  It returns either a
+  character, or NIL if no input is currently available, or :EOF if
+  end-of-file is reached.  The default method provided by
+  FUNDAMENTAL-CHARACTER-INPUT-STREAM simply calls STREAM-READ-CHAR; this
+  is sufficient for file streams, but interactive streams should define
+  their own method."))
 
 (defmethod stream-read-char-no-hang ((stream fundamental-character-input-stream))
   (stream-read-char stream))
 
 (defgeneric stream-peek-char (stream)
-  (:documentation "Reads either a character or :eof without removing the character
-  from the stream."))
+  (:documentation
+   "Used to implement PEEK-CHAR; this corresponds to peek-type of NIL.
+  It returns either a character or :EOF.  The default method calls
+  STREAM-READ-CHAR and STREAM-UNREAD-CHAR."))
 
 (defmethod stream-peek-char ((stream fundamental-character-input-stream))
   (let ((char (stream-read-char stream)))
@@ -113,17 +139,24 @@
     char))
 
 (defgeneric stream-listen (stream)
-  (:documentation "Return true if input is available, otherwise false."))
+  (:documentation
+   "Used by LISTEN.  Returns true or false.  The default method uses
+  STREAM-READ-CHAR-NO-HANG and STREAM-UNREAD-CHAR.  Most streams should 
+  define their own method since it will usually be trivial and will
+  always be more efficient than the default method."))
 
 (defmethod stream-listen ((stream fundamental-character-input-stream))
   (let ((char (stream-read-char-no-hang stream)))
     (when (characterp char)
       (stream-unread-char stream char)
-      char)))
+      t)))
 
 (defgeneric stream-read-line (stream)
-  (:documentation "Reads the first line, and returns a string and T as the second
-  value if the line was terminated by end-of-file."))
+  (:documentation
+   "Used by READ-LINE.  A string is returned as the first value.  The
+  second value is true if the string was terminated by end-of-file
+  instead of the end of a line.  The default method uses repeated
+  calls to STREAM-READ-CHAR."))
 
 (defmethod stream-read-line ((stream fundamental-character-input-stream))
   (let ((res (make-string 80))
@@ -145,19 +178,35 @@
 	      (incf index)))))))
 
 (defgeneric stream-clear-input (stream)
-  (:documentation "Clears buffered input, and returns Nil."))
+  (:documentation
+   "Implements CLEAR-INPUT for the stream, returning NIL.  The default
+  method does nothing."))
 
 (defmethod stream-clear-input ((stream fundamental-character-input-stream))
   nil)
 
 
 ;;; Character output streams.
+;;;
+;;; A character output stream can be created by defining a class that
+;;; includes FUNDAMENTAL-CHARACTER-OUTPUT-STREAM and defining methods
+;;; for the generic functions below.
 
 (defgeneric stream-write-char (stream character)
-  (:documentation "Outputs the Character to the Stream."))
+  (:documentation
+   "Writes character to the stream and returns the character.  Every
+  subclass of FUNDAMENTAL-CHARACTER-OUTPUT-STREAM must have a method
+  defined for this function."))
 
 (defgeneric stream-line-column (stream)
-  (:documentation "Return the current column number for the stream or Nil."))
+  (:documentation
+   "This function returns the column number where the next character
+  will be written, or NIL if that is not meaningful for this stream.
+  The first column on a line is numbered 0.  This function is used in
+  the implementation of PPRINT and the FORMAT ~T directive.  For every
+  character output stream class that is defined, a method must be
+  defined for this function, although it is permissible for it to
+  always return NIL."))
 
 ;;; Stream-line-length is a CMUCL extension to Gray streams.
 (defgeneric stream-line-length (stream)
@@ -167,13 +216,30 @@
   nil)
 
 (defgeneric stream-start-line-p (stream)
-  (:documentation "Return true when at the start of a line otherwise false."))
+  (:documentation
+   "This is a predicate which returns T if the stream is positioned at
+  the beginning of a line, else NIL.  It is permissible to always return
+  NIL.  This is used in the implementation of FRESH-LINE.  Note that
+  while a value of 0 from STREAM-LINE-COLUMN also indicates the
+  beginning of a line, there are cases where STREAM-START-LINE-P can be
+  meaningfully implemented although STREAM-LINE-COLUMN can't be.  For
+  example, for a window using variable-width characters, the column
+  number isn't very meaningful, but the beginning of the line does have
+  a clear meaning.  The default method for STREAM-START-LINE-P on class
+  FUNDAMENTAL-CHARACTER-OUTPUT-STREAM uses STREAM-LINE-COLUMN, so if
+  that is defined to return NIL, then a method should be provided for
+  either STREAM-START-LINE-P or STREAM-FRESH-LINE."))
 
 (defmethod stream-start-line-p ((stream fundamental-character-output-stream))
   (eql (stream-line-column stream) 0))
 
 (defgeneric stream-write-string (stream string &optional (start 0) end)
-  (:documentation "Outputs the String to the given Stream."))
+  (:documentation
+   "This is used by WRITE-STRING.  It writes the string to the stream,
+  optionally delimited by start and end, which default to 0 and NIL.
+  The string argument is returned.  The default method provided by
+  FUNDAMENTAL-CHARACTER-OUTPUT-STREAM uses repeated calls to
+  STREAM-WRITE-CHAR."))
 
 (defmethod stream-write-string ((stream fundamental-character-output-stream)
 				string &optional (start 0) end)
@@ -188,14 +254,19 @@
   string)
 
 (defgeneric stream-terpri (stream)
-  (:documentation "Outputs a new line to the Stream."))
+  (:documentation
+   "Writes an end of line, as for TERPRI.  Returns NIL.  The default
+  method does (STREAM-WRITE-CHAR stream #\NEWLINE)."))
 
 (defmethod stream-terpri ((stream fundamental-character-output-stream))
   (stream-write-char stream #\Newline))
 
 (defgeneric stream-fresh-line (stream)
-  (:documentation "Outputs a new line to the Stream if it is not positioned at the begining of
-   a line.  Returns T if it output a new line, nil otherwise."))
+  (:documentation
+   "Outputs a new line to the Stream if it is not positioned at the
+  begining of a line.  Returns T if it output a new line, nil
+  otherwise. Used by FRESH-LINE. The default method uses
+  STREAM-START-LINE-P and STREAM-TERPRI."))
 
 (defmethod stream-fresh-line ((stream fundamental-character-output-stream))
   (unless (stream-start-line-p stream)
@@ -203,28 +274,38 @@
     t))
 
 (defgeneric stream-finish-output (stream)
-  (:documentation "Attempts to ensure that all output sent to the Stream has reached its
-   destination, and only then returns false."))
+  (:documentation
+   "Attempts to ensure that all output sent to the Stream has reached
+  its destination, and only then returns false. Implements
+  FINISH-OUTPUT.  The default method does nothing."))
 
 (defmethod stream-finish-output ((stream fundamental-output-stream))
   nil)
 
 (defgeneric stream-force-output (stream)
-  (:documentation "Attempts to force any buffered output to be sent."))
+  (:documentation
+   "Attempts to force any buffered output to be sent. Implements
+  FORCE-OUTPUT.  The default method does nothing."))
 
 (defmethod stream-force-output ((stream fundamental-output-stream))
   nil)
 
 (defgeneric stream-clear-output (stream)
-  (:documentation "Clears the given output Stream."))
+  (:documentation
+   "Clears the given output Stream. Implements CLEAR-OUTPUT.  The
+  default method does nothing."))
 
 (defmethod stream-clear-output ((stream fundamental-output-stream))
   nil)
 
 (defgeneric stream-advance-to-column (stream column)
-  (:documentation "Write enough space to the stream so that the next character is
-  written to the given column. Returns true if successful, or false if not
-  supported."))
+  (:documentation
+   "Writes enough blank space so that the next character will be
+  written at the specified column.  Returns true if the operation is
+  successful, or NIL if it is not supported for this stream.  This is
+  intended for use by by PPRINT and FORMAT ~T.  The default method uses
+  STREAM-LINE-COLUMN and repeated calls to STREAM-WRITE-CHAR with a
+  #\SPACE character; it returns NIL if STREAM-LINE-COLUMN returns NIL."))
 
 (defmethod stream-advance-to-column ((stream fundamental-character-output-stream)
 				     column)
@@ -237,12 +318,22 @@
 
 
 ;;; Binary streams.
+;;;
+;;; Binary streams can be created by defining a class that includes
+;;; either FUNDAMENTAL-BINARY-INPUT-STREAM or
+;;; FUNDAMENTAL-BINARY-OUTPUT-STREAM (or both) and defining a method
+;;; for STREAM-ELEMENT-TYPE and for one or both of the following
+;;; generic functions.
 
 (defgeneric stream-read-byte (stream)
-  (:documentation "Returns an integer of :eof."))
+  (:documentation
+   "Used by READ-BYTE; returns either an integer, or the symbol :EOF
+  if the stream is at end-of-file."))
 
 (defgeneric stream-write-byte (stream integer)
-  (:documentation "Writes integer to stream, returning integer."))
+  (:documentation
+   "Implements WRITE-BYTE; writes the integer to the stream and
+  returns the integer as the result."))
 
 
 ;;; Example character output stream encapsulating a lisp-stream.
-- 
GitLab