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