1 ;;;; Gray streams implementation for SBCL, based on the Gray streams
2 ;;;; implementation for CMU CL, based on the stream-definition-by-user
3 ;;;; proposal by David N. Gray.
5 ;;;; This software is part of the SBCL system. See the README file for
8 ;;;; This software is in the public domain and is provided with
9 ;;;; absolutely no warranty. See the COPYING and CREDITS files for
10 ;;;; more information.
12 (in-package "SB-GRAY")
14 ;;; BUG-OR-ERROR: because we have extensible streams, wherewith the
15 ;;; user is responsible for some of the protocol implementation, it's
16 ;;; not necessarily a bug in SBCL itself if we fall through to one of
17 ;;; these default methods.
19 ;;; FIXME: there's a lot of similarity in these Gray stream
20 ;;; implementation generic functions. All of them could (maybe
21 ;;; should?) have two default methods: one on STREAM calling
22 ;;; BUG-OR-ERROR, and one on T signalling a TYPE-ERROR.
23 (defmacro bug-or-error (stream fun)
25 "~@<The stream ~S has no suitable method for ~S, ~
26 and so has fallen through to this method. If you think that this is ~
27 a bug, please report it to the applicable authority (bugs in SBCL itself ~
28 should go to the mailing lists referenced from ~
29 <http://www.sbcl.org/>).~@:>"
32 (fmakunbound 'stream-element-type)
34 (defgeneric stream-element-type (stream)
37 "Return a type specifier for the kind of object returned by the
38 STREAM. The class FUNDAMENTAL-CHARACTER-STREAM provides a default method
39 which returns CHARACTER."))
41 (defmethod stream-element-type ((stream ansi-stream))
42 (ansi-stream-element-type stream))
44 (defmethod stream-element-type ((stream fundamental-character-stream))
47 (defmethod stream-element-type ((stream stream))
48 (bug-or-error stream 'stream-element-type))
50 (defmethod stream-element-type ((non-stream t))
51 (error 'type-error :datum non-stream :expected-type 'stream))
53 (defgeneric pcl-open-stream-p (stream)
56 "Return true if STREAM is not closed. A default method is provided
57 by class FUNDAMENTAL-STREAM which returns true if CLOSE has not been
58 called on the stream."))
60 (defmethod pcl-open-stream-p ((stream ansi-stream))
61 (ansi-stream-open-stream-p stream))
63 (defmethod pcl-open-stream-p ((stream fundamental-stream))
64 (stream-open-p stream))
66 (defmethod pcl-open-stream-p ((stream stream))
67 (bug-or-error stream 'open-stream-p))
69 (defmethod pcl-open-stream-p ((non-stream t))
70 (error 'type-error :datum non-stream :expected-type 'stream))
72 ;;; bootstrapping hack
73 (pcl-open-stream-p (make-string-output-stream))
74 (setf (fdefinition 'open-stream-p) #'pcl-open-stream-p)
76 (defgeneric pcl-close (stream &key abort)
79 "Close the given STREAM. No more I/O may be performed, but
80 inquiries may still be made. If :ABORT is true, an attempt is made
81 to clean up the side effects of having created the stream."))
83 (defmethod pcl-close ((stream ansi-stream) &key abort)
84 (ansi-stream-close stream abort))
86 (defmethod pcl-close ((stream fundamental-stream) &key abort)
87 (declare (ignore abort))
88 (setf (stream-open-p stream) nil)
91 (setf (fdefinition 'close) #'pcl-close)
94 (fmakunbound 'input-stream-p)
96 (defgeneric input-stream-p (stream)
98 (:documentation "Can STREAM perform input operations?"))
100 (defmethod input-stream-p ((stream ansi-stream))
101 (ansi-stream-input-stream-p stream))
103 (defmethod input-stream-p ((stream fundamental-stream))
106 (defmethod input-stream-p ((stream fundamental-input-stream))
109 (defmethod input-stream-p ((stream stream))
110 (bug-or-error stream 'input-stream-p))
112 (defmethod input-stream-p ((non-stream t))
113 (error 'type-error :datum non-stream :expected-type 'stream)))
116 (fmakunbound 'interactive-stream-p)
118 (defgeneric interactive-stream-p (stream)
120 (:documentation "Is STREAM an interactive stream?"))
122 (defmethod interactive-stream-p ((stream ansi-stream))
123 (funcall (ansi-stream-misc stream) stream :interactive-p))
125 (defmethod interactive-stream-p ((stream fundamental-stream))
128 (defmethod interactive-stream-p ((stream stream))
129 (bug-or-error stream 'interactive-stream-p))
131 (defmethod interactive-stream-p ((non-stream t))
132 (error 'type-error :datum non-stream :expected-type 'stream)))
135 (fmakunbound 'output-stream-p)
137 (defgeneric output-stream-p (stream)
139 (:documentation "Can STREAM perform output operations?"))
141 (defmethod output-stream-p ((stream ansi-stream))
142 (ansi-stream-output-stream-p stream))
144 (defmethod output-stream-p ((stream fundamental-stream))
147 (defmethod output-stream-p ((stream fundamental-output-stream))
150 (defmethod output-stream-p ((stream stream))
151 (bug-or-error stream 'output-stream-p))
153 (defmethod output-stream-p ((non-stream t))
154 (error 'type-error :datum non-stream :expected-type 'stream)))
156 ;;; character input streams
158 ;;; A character input stream can be created by defining a class that
159 ;;; includes FUNDAMENTAL-CHARACTER-INPUT-STREAM and defining methods
160 ;;; for the generic functions below.
162 (defgeneric stream-read-char (stream)
165 "Read one character from the stream. Return either a
166 character object, or the symbol :EOF if the stream is at end-of-file.
167 Every subclass of FUNDAMENTAL-CHARACTER-INPUT-STREAM must define a
168 method for this function."))
170 (defgeneric stream-unread-char (stream character)
173 "Un-do the last call to STREAM-READ-CHAR, as in UNREAD-CHAR.
174 Return NIL. Every subclass of FUNDAMENTAL-CHARACTER-INPUT-STREAM
175 must define a method for this function."))
177 (defgeneric stream-read-char-no-hang (stream)
180 "This is used to implement READ-CHAR-NO-HANG. It returns either a
181 character, or NIL if no input is currently available, or :EOF if
182 end-of-file is reached. The default method provided by
183 FUNDAMENTAL-CHARACTER-INPUT-STREAM simply calls STREAM-READ-CHAR; this
184 is sufficient for file streams, but interactive streams should define
187 (defmethod stream-read-char-no-hang ((stream fundamental-character-input-stream))
188 (stream-read-char stream))
190 (defgeneric stream-peek-char (stream)
193 "This is used to implement PEEK-CHAR; this corresponds to PEEK-TYPE of NIL.
194 It returns either a character or :EOF. The default method calls
195 STREAM-READ-CHAR and STREAM-UNREAD-CHAR."))
197 (defmethod stream-peek-char ((stream fundamental-character-input-stream))
198 (let ((char (stream-read-char stream)))
199 (unless (eq char :eof)
200 (stream-unread-char stream char))
203 (defgeneric stream-listen (stream)
206 "This is used by LISTEN. It returns true or false. The default method uses
207 STREAM-READ-CHAR-NO-HANG and STREAM-UNREAD-CHAR. Most streams should
208 define their own method since it will usually be trivial and will
209 always be more efficient than the default method."))
211 (defmethod stream-listen ((stream fundamental-character-input-stream))
212 (let ((char (stream-read-char-no-hang stream)))
213 (when (characterp char)
214 (stream-unread-char stream char)
217 (defgeneric stream-read-line (stream)
220 "This is used by READ-LINE. A string is returned as the first value. The
221 second value is true if the string was terminated by end-of-file
222 instead of the end of a line. The default method uses repeated
223 calls to STREAM-READ-CHAR."))
225 (defmethod stream-read-line ((stream fundamental-character-input-stream))
226 (let ((res (make-string 80))
230 (let ((ch (stream-read-char stream)))
232 (return (values (%shrink-vector res index) t)))
234 (when (char= ch #\newline)
235 (return (values (%shrink-vector res index) nil)))
238 (let ((new (make-string len)))
241 (setf (schar res index) ch)
244 (defgeneric stream-clear-input (stream)
247 "This is like CL:CLEAR-INPUT, but for Gray streams, returning NIL.
248 The default method does nothing."))
250 (defmethod stream-clear-input ((stream fundamental-character-input-stream))
252 (defmethod stream-clear-input ((stream stream))
253 (bug-or-error stream 'stream-clear-input))
254 (defmethod stream-clear-input ((non-stream t))
255 (error 'type-error :datum non-stream :expected-type 'stream))
257 (defgeneric stream-read-sequence (stream seq &optional start end)
260 "This is like CL:READ-SEQUENCE, but for Gray streams."))
262 ;;; Destructively modify SEQ by reading elements from STREAM. That
263 ;;; part of SEQ bounded by START and END is destructively modified by
264 ;;; copying successive elements into it from STREAM. If the end of
265 ;;; file for STREAM is reached before copying all elements of the
266 ;;; subsequence, then the extra elements near the end of sequence are
267 ;;; not updated, and the index of the next element is returned.
268 (defun basic-io-type-stream-read-sequence (stream seq start end read-fun)
269 (declare (type sequence seq)
272 (type sequence-end end)
273 (type function read-fun)
275 (let ((end (or end (length seq))))
276 (declare (type index end))
279 (do ((rem (nthcdr start seq) (rest rem))
281 ((or (endp rem) (>= i end)) i)
282 (declare (type list rem)
284 (let ((el (funcall read-fun stream)))
287 (setf (first rem) el))))
289 (with-array-data ((data seq) (offset-start start) (offset-end end))
290 (do ((i offset-start (1+ i)))
291 ((>= i offset-end) end)
292 (declare (type index i))
293 (let ((el (funcall read-fun stream)))
295 (return (+ start (- i offset-start))))
296 (setf (aref data i) el))))))))
298 (defmethod stream-read-sequence ((stream fundamental-character-input-stream)
300 &optional (start 0) (end nil))
301 (basic-io-type-stream-read-sequence stream seq start end
304 (defmethod stream-read-sequence ((stream fundamental-binary-input-stream)
306 &optional (start 0) (end nil))
307 (basic-io-type-stream-read-sequence stream seq start end
311 ;;; character output streams
313 ;;; A character output stream can be created by defining a class that
314 ;;; includes FUNDAMENTAL-CHARACTER-OUTPUT-STREAM and defining methods
315 ;;; for the generic functions below.
317 (defgeneric stream-write-char (stream character)
320 "Write CHARACTER to STREAM and return CHARACTER. Every
321 subclass of FUNDAMENTAL-CHARACTER-OUTPUT-STREAM must have a method
322 defined for this function."))
324 (defgeneric stream-line-column (stream)
327 "Return the column number where the next character
328 will be written, or NIL if that is not meaningful for this stream.
329 The first column on a line is numbered 0. This function is used in
330 the implementation of PPRINT and the FORMAT ~T directive. For every
331 character output stream class that is defined, a method must be
332 defined for this function, although it is permissible for it to
333 always return NIL."))
335 (defmethod stream-line-column ((stream fundamental-character-output-stream))
338 ;;; STREAM-LINE-LENGTH is a CMU CL extension to Gray streams.
339 ;;; FIXME: Should we support it? Probably not..
340 (defgeneric stream-line-length (stream)
342 (:documentation "Return the stream line length or NIL."))
344 (defmethod stream-line-length ((stream fundamental-character-output-stream))
347 (defgeneric stream-start-line-p (stream)
350 "Is STREAM known to be positioned at the beginning of a line?
351 It is permissible for an implementation to always return
352 NIL. This is used in the implementation of FRESH-LINE. Note that
353 while a value of 0 from STREAM-LINE-COLUMN also indicates the
354 beginning of a line, there are cases where STREAM-START-LINE-P can be
355 meaningfully implemented although STREAM-LINE-COLUMN can't be. For
356 example, for a window using variable-width characters, the column
357 number isn't very meaningful, but the beginning of the line does have
358 a clear meaning. The default method for STREAM-START-LINE-P on class
359 FUNDAMENTAL-CHARACTER-OUTPUT-STREAM uses STREAM-LINE-COLUMN, so if
360 that is defined to return NIL, then a method should be provided for
361 either STREAM-START-LINE-P or STREAM-FRESH-LINE."))
363 (defmethod stream-start-line-p ((stream fundamental-character-output-stream))
364 (eql (stream-line-column stream) 0))
366 (defgeneric stream-write-string (stream string &optional start end)
369 "This is used by WRITE-STRING. It writes the string to the stream,
370 optionally delimited by start and end, which default to 0 and NIL.
371 The string argument is returned. The default method provided by
372 FUNDAMENTAL-CHARACTER-OUTPUT-STREAM uses repeated calls to
373 STREAM-WRITE-CHAR."))
375 (defmethod stream-write-string ((stream fundamental-character-output-stream)
376 string &optional (start 0) end)
377 (declare (string string)
379 (let ((end (or end (length string))))
380 (declare (fixnum end))
381 (do ((pos start (1+ pos)))
383 (declare (type index pos))
384 (stream-write-char stream (aref string pos))))
387 (defgeneric stream-terpri (stream)
390 "Writes an end of line, as for TERPRI. Returns NIL. The default
391 method does (STREAM-WRITE-CHAR stream #\NEWLINE)."))
393 (defmethod stream-terpri ((stream fundamental-character-output-stream))
394 (stream-write-char stream #\Newline))
396 (defgeneric stream-fresh-line (stream)
399 "Outputs a new line to the Stream if it is not positioned at the
400 begining of a line. Returns T if it output a new line, nil
401 otherwise. Used by FRESH-LINE. The default method uses
402 STREAM-START-LINE-P and STREAM-TERPRI."))
404 (defmethod stream-fresh-line ((stream fundamental-character-output-stream))
405 (unless (stream-start-line-p stream)
406 (stream-terpri stream)
409 (defgeneric stream-finish-output (stream)
412 "Attempts to ensure that all output sent to the Stream has reached
413 its destination, and only then returns false. Implements
414 FINISH-OUTPUT. The default method does nothing."))
416 (defmethod stream-finish-output ((stream fundamental-output-stream))
418 (defmethod stream-finish-output ((stream stream))
419 (bug-or-error stream 'stream-finish-output))
420 (defmethod stream-finish-output ((non-stream t))
421 (error 'type-error :datum non-stream :expected-type 'stream))
423 (defgeneric stream-force-output (stream)
426 "Attempts to force any buffered output to be sent. Implements
427 FORCE-OUTPUT. The default method does nothing."))
429 (defmethod stream-force-output ((stream fundamental-output-stream))
431 (defmethod stream-force-output ((stream stream))
432 (bug-or-error stream 'stream-force-output))
433 (defmethod stream-force-output ((non-stream t))
434 (error 'type-error :datum non-stream :expected-type 'stream))
436 (defgeneric stream-clear-output (stream)
439 "This is like CL:CLEAR-OUTPUT, but for Gray streams: clear the given
440 output STREAM. The default method does nothing."))
442 (defmethod stream-clear-output ((stream fundamental-output-stream))
444 (defmethod stream-clear-output ((stream stream))
445 (bug-or-error stream 'stream-clear-output))
446 (defmethod stream-clear-output ((non-stream t))
447 (error 'type-error :datum non-stream :expected-type 'stream))
449 (defgeneric stream-advance-to-column (stream column)
452 "Write enough blank space so that the next character will be
453 written at the specified column. Returns true if the operation is
454 successful, or NIL if it is not supported for this stream. This is
455 intended for use by by PPRINT and FORMAT ~T. The default method uses
456 STREAM-LINE-COLUMN and repeated calls to STREAM-WRITE-CHAR with a
457 #\SPACE character; it returns NIL if STREAM-LINE-COLUMN returns NIL."))
459 (defmethod stream-advance-to-column ((stream fundamental-character-output-stream)
461 (let ((current-column (stream-line-column stream)))
463 (let ((fill (- column current-column)))
465 (stream-write-char stream #\Space)))
468 (defgeneric stream-write-sequence (stream seq &optional start end)
471 "This is like CL:WRITE-SEQUENCE, but for Gray streams."))
473 ;;; Write the elements of SEQ bounded by START and END to STREAM.
474 (defun basic-io-type-stream-write-sequence (stream seq start end write-fun)
475 (declare (type sequence seq)
478 (type sequence-end end)
479 (type function write-fun)
481 (let ((end (or end (length seq))))
482 (declare (type index start end))
485 (do ((rem (nthcdr start seq) (rest rem))
487 ((or (endp rem) (>= i end)) seq)
488 (declare (type list rem)
490 (funcall write-fun stream (first rem))))
492 (do ((i start (1+ i)))
494 (declare (type index i))
495 (funcall write-fun stream (aref seq i)))))))
497 (defmethod stream-write-sequence ((stream fundamental-character-output-stream)
499 &optional (start 0) (end nil))
502 (stream-write-string stream seq start end))
504 (basic-io-type-stream-write-sequence stream seq start end
505 #'stream-write-char))))
510 ;;; Binary streams can be created by defining a class that includes
511 ;;; either FUNDAMENTAL-BINARY-INPUT-STREAM or
512 ;;; FUNDAMENTAL-BINARY-OUTPUT-STREAM (or both) and defining a method
513 ;;; for STREAM-ELEMENT-TYPE and for one or both of the following
514 ;;; generic functions.
516 (defgeneric stream-read-byte (stream)
519 "Used by READ-BYTE; returns either an integer, or the symbol :EOF
520 if the stream is at end-of-file."))
522 (defmethod stream-read-byte ((stream stream))
523 (bug-or-error stream 'stream-read-byte))
524 (defmethod stream-read-byte ((non-stream t))
525 (error 'type-error :datum non-stream :expected-type 'stream))
527 (defgeneric stream-write-byte (stream integer)
530 "Implements WRITE-BYTE; writes the integer to the stream and
531 returns the integer as the result."))
533 (defmethod stream-write-byte ((stream stream) integer)
534 (bug-or-error stream 'stream-write-byte))
535 (defmethod stream-write-byte ((non-stream t) integer)
536 (error 'type-error :datum non-stream :expected-type 'stream))
538 ;; Provide a reasonable default for binary Gray streams. We might be
539 ;; able to do better by specializing on the sequence type, but at
540 ;; least the behaviour is reasonable. --tony 2003/05/08.
541 (defmethod stream-write-sequence ((stream fundamental-binary-output-stream)
543 &optional (start 0) (end nil))
544 (basic-io-type-stream-write-sequence stream seq start end
545 #'stream-write-byte))
547 (defgeneric stream-file-position (stream &optional position-spec)
550 "Used by FILE-POSITION. Returns or changes the current position within STREAM."))
552 (defmethod stream-file-position ((stream ansi-stream) &optional position-spec)
553 (ansi-stream-file-position stream position-spec))
555 (defmethod stream-file-position ((stream t) &optional position-spec)
556 (declare (ignore stream position-spec))
560 ;;; This is not in the Gray stream proposal, so it is left here
563 ;;; example character output stream encapsulating a lisp-stream
564 (defun make-character-output-stream (lisp-stream)
565 (declare (type lisp-stream lisp-stream))
566 (make-instance 'character-output-stream :lisp-stream lisp-stream))
568 (defmethod open-stream-p ((stream character-output-stream))
569 (open-stream-p (character-output-stream-lisp-stream stream)))
571 (defmethod close ((stream character-output-stream) &key abort)
572 (close (character-output-stream-lisp-stream stream) :abort abort))
574 (defmethod input-stream-p ((stream character-output-stream))
575 (input-stream-p (character-output-stream-lisp-stream stream)))
577 (defmethod output-stream-p ((stream character-output-stream))
578 (output-stream-p (character-output-stream-lisp-stream stream)))
580 (defmethod stream-write-char ((stream character-output-stream) character)
581 (write-char character (character-output-stream-lisp-stream stream)))
583 (defmethod stream-line-column ((stream character-output-stream))
584 (charpos (character-output-stream-lisp-stream stream)))
586 (defmethod stream-line-length ((stream character-output-stream))
587 (line-length (character-output-stream-lisp-stream stream)))
589 (defmethod stream-finish-output ((stream character-output-stream))
590 (finish-output (character-output-stream-lisp-stream stream)))
592 (defmethod stream-force-output ((stream character-output-stream))
593 (force-output (character-output-stream-lisp-stream stream)))
595 (defmethod stream-clear-output ((stream character-output-stream))
596 (clear-output (character-output-stream-lisp-stream stream)))
598 ;;; example character input stream encapsulating a lisp-stream
600 (defun make-character-input-stream (lisp-stream)
601 (declare (type lisp-stream lisp-stream))
602 (make-instance 'character-input-stream :lisp-stream lisp-stream))
604 (defmethod open-stream-p ((stream character-input-stream))
605 (open-stream-p (character-input-stream-lisp-stream stream)))
607 (defmethod close ((stream character-input-stream) &key abort)
608 (close (character-input-stream-lisp-stream stream) :abort abort))
610 (defmethod input-stream-p ((stream character-input-stream))
611 (input-stream-p (character-input-stream-lisp-stream stream)))
613 (defmethod output-stream-p ((stream character-input-stream))
614 (output-stream-p (character-input-stream-lisp-stream stream)))
616 (defmethod stream-read-char ((stream character-input-stream))
617 (read-char (character-input-stream-lisp-stream stream) nil :eof))
619 (defmethod stream-unread-char ((stream character-input-stream) character)
620 (unread-char character (character-input-stream-lisp-stream stream)))
622 (defmethod stream-read-char-no-hang ((stream character-input-stream))
623 (read-char-no-hang (character-input-stream-lisp-stream stream) nil :eof))
626 (defmethod stream-peek-char ((stream character-input-stream))
627 (peek-char nil (character-input-stream-lisp-stream stream) nil :eof))
630 (defmethod stream-listen ((stream character-input-stream))
631 (listen (character-input-stream-lisp-stream stream)))
633 (defmethod stream-clear-input ((stream character-input-stream))
634 (clear-input (character-input-stream-lisp-stream stream)))