1
;;;; Copyright (c) 2004, Juan Jose Garcia-Ripoll
3
;;;; This program is free software; you can redistribute it and/or
4
;;;; modify it under the terms of the GNU Library General Public
5
;;;; License as published by the Free Software Foundation; either
6
;;;; version 2 of the License, or (at your option) any later version.
8
;;;; See file '../Copyright' for full details.
9
;;;; The CLOS IO library.
14
;;; This is the generic function interface for CLOS streams.
16
;;; The following is a port of SBCL's implementation of Gray Streams. Minor
17
;;; caveats with respect to the proposal are that we rather keep CLOSE,
18
;;; STREAM-ELEMENT-TYPE, INPUT-STREAM-P, OUTPUT-STREAM-P and OPEN-STREAM-P
19
;;; these as normal functions that call the user extensible EXT:STREAM-{CLOSE,
20
;;; ELT-TYPE, INPUT-P, OUTPUT-P, OPEN-P}.
23
(defgeneric stream-advance-to-column (stream column)
25
"Write enough blank space so that the next character will be
26
written at the specified column. Returns true if the operation is
27
successful, or NIL if it is not supported for this stream. This is
28
intended for use by by PPRINT and FORMAT ~T. The default method uses
29
STREAM-LINE-COLUMN and repeated calls to STREAM-WRITE-CHAR with a
30
#\SPACE character; it returns NIL if STREAM-LINE-COLUMN returns NIL."))
32
(defgeneric stream-clear-input (stream)
34
"This is like CL:CLEAR-INPUT, but for Gray streams, returning NIL.
35
The default method does nothing."))
37
(defgeneric stream-clear-output (stream)
39
"This is like CL:CLEAR-OUTPUT, but for Gray streams: clear the given
40
output STREAM. The default method does nothing."))
42
(defgeneric stream-close (stream &key abort)
44
"Close the given STREAM. No more I/O may be performed, but
45
inquiries may still be made. If :ABORT is true, an attempt is made
46
to clean up the side effects of having created the stream."))
48
(defgeneric stream-elt-type (stream)
50
"Return a type specifier for the kind of object returned by the
51
STREAM. The class FUNDAMENTAL-CHARACTER-STREAM provides a default method
52
which returns CHARACTER."))
54
(defgeneric stream-finish-output (stream)
56
"Attempts to ensure that all output sent to the Stream has reached
57
its destination, and only then returns false. Implements
58
FINISH-OUTPUT. The default method does nothing."))
60
(defgeneric stream-force-output (stream)
62
"Attempts to force any buffered output to be sent. Implements
63
FORCE-OUTPUT. The default method does nothing."))
65
(defgeneric stream-fresh-line (stream)
67
"Outputs a new line to the Stream if it is not positioned at the
68
begining of a line. Returns T if it output a new line, nil
69
otherwise. Used by FRESH-LINE. The default method uses
70
STREAM-START-LINE-P and STREAM-TERPRI."))
72
(defgeneric stream-input-p (stream)
73
(:documentation "Can STREAM perform input operations?"))
75
(defgeneric stream-interactive-p (stream)
76
(:documentation "Is stream interactive (For instance, a tty)?"))
78
(defgeneric stream-line-column (stream)
80
"Return the column number where the next character
81
will be written, or NIL if that is not meaningful for this stream.
82
The first column on a line is numbered 0. This function is used in
83
the implementation of PPRINT and the FORMAT ~T directive. For every
84
character output stream class that is defined, a method must be
85
defined for this function, although it is permissible for it to
88
(defgeneric stream-listen (stream)
91
"This is used by LISTEN. It returns true or false. The default method uses
92
STREAM-READ-CHAR-NO-HANG and STREAM-UNREAD-CHAR. Most streams should
93
define their own method since it will usually be trivial and will
94
always be more efficient than the default method."))
96
(defgeneric stream-open-p (stream)
98
"Return true if STREAM is not closed. A default method is provided
99
by class FUNDAMENTAL-STREAM which returns true if CLOSE has not been
100
called on the stream."))
102
(defgeneric stream-output-p (stream)
103
(:documentation "Can STREAM perform output operations?"))
105
(defgeneric stream-peek-char (stream)
107
"This is used to implement PEEK-CHAR; this corresponds to PEEK-TYPE of NIL.
108
It returns either a character or :EOF. The default method calls
109
STREAM-READ-CHAR and STREAM-UNREAD-CHAR."))
111
(defgeneric stream-read-byte (stream)
113
"Used by READ-BYTE; returns either an integer, or the symbol :EOF
114
if the stream is at end-of-file."))
116
(defgeneric stream-read-char (stream)
118
"Read one character from the stream. Return either a
119
character object, or the symbol :EOF if the stream is at end-of-file.
120
Every subclass of FUNDAMENTAL-CHARACTER-INPUT-STREAM must define a
121
method for this function."))
123
(defgeneric stream-read-char-no-hang (stream)
125
"This is used to implement READ-CHAR-NO-HANG. It returns either a
126
character, or NIL if no input is currently available, or :EOF if
127
end-of-file is reached. The default method provided by
128
FUNDAMENTAL-CHARACTER-INPUT-STREAM simply calls STREAM-READ-CHAR; this
129
is sufficient for file streams, but interactive streams should define
132
(defgeneric stream-read-line (stream)
134
"This is used by READ-LINE. A string is returned as the first value. The
135
second value is true if the string was terminated by end-of-file
136
instead of the end of a line. The default method uses repeated
137
calls to STREAM-READ-CHAR."))
139
(defgeneric stream-read-sequence (stream seq &optional start end)
141
"This is like CL:READ-SEQUENCE, but for Gray streams."))
143
(defgeneric stream-start-line-p (stream)
145
"Is STREAM known to be positioned at the beginning of a line?
146
It is permissible for an implementation to always return
147
NIL. This is used in the implementation of FRESH-LINE. Note that
148
while a value of 0 from STREAM-LINE-COLUMN also indicates the
149
beginning of a line, there are cases where STREAM-START-LINE-P can be
150
meaningfully implemented although STREAM-LINE-COLUMN can't be. For
151
example, for a window using variable-width characters, the column
152
number isn't very meaningful, but the beginning of the line does have
153
a clear meaning. The default method for STREAM-START-LINE-P on class
154
FUNDAMENTAL-CHARACTER-OUTPUT-STREAM uses STREAM-LINE-COLUMN, so if
155
that is defined to return NIL, then a method should be provided for
156
either STREAM-START-LINE-P or STREAM-FRESH-LINE."))
158
(defgeneric stream-terpri (stream)
160
"Writes an end of line, as for TERPRI. Returns NIL. The default
161
method does (STREAM-WRITE-CHAR stream #\NEWLINE)."))
163
(defgeneric stream-unread-char (stream character)
165
"Un-do the last call to STREAM-READ-CHAR, as in UNREAD-CHAR.
166
Return NIL. Every subclass of FUNDAMENTAL-CHARACTER-INPUT-STREAM
167
must define a method for this function."))
169
(defgeneric stream-write-byte (stream integer)
171
"Implements WRITE-BYTE; writes the integer to the stream and
172
returns the integer as the result."))
174
(defgeneric stream-write-char (stream character)
176
"Write CHARACTER to STREAM and return CHARACTER. Every
177
subclass of FUNDAMENTAL-CHARACTER-OUTPUT-STREAM must have a method
178
defined for this function."))
180
(defgeneric stream-write-string (stream string &optional start end)
182
"This is used by WRITE-STRING. It writes the string to the stream,
183
optionally delimited by start and end, which default to 0 and NIL.
184
The string argument is returned. The default method provided by
185
FUNDAMENTAL-CHARACTER-OUTPUT-STREAM uses repeated calls to
186
STREAM-WRITE-CHAR."))
188
(defgeneric stream-write-sequence (stream seq &optional start end)
190
"This is like CL:WRITE-SEQUENCE, but for Gray streams."))
194
;;; Our class hierarchy looks like the one from Gray streams
196
;;; character output streams
198
;;; A character output stream can be created by defining a class that
199
;;; includes FUNDAMENTAL-CHARACTER-OUTPUT-STREAM and defining methods
200
;;; for the generic functions below.
204
;;; Binary streams can be created by defining a class that includes
205
;;; either FUNDAMENTAL-BINARY-INPUT-STREAM or
206
;;; FUNDAMENTAL-BINARY-OUTPUT-STREAM (or both) and defining a method
207
;;; for STREAM-ELEMENT-TYPE and for one or both of the following
208
;;; generic functions.
211
(defclass fundamental-stream (standard-object stream)
212
((open-p :initform t :accessor stream-open-p))
213
(:documentation "the base class for all CLOS streams"))
215
(defclass fundamental-input-stream (fundamental-stream) nil)
217
(defclass fundamental-output-stream (fundamental-stream) nil)
219
(defclass fundamental-character-stream (fundamental-stream) nil)
221
(defclass fundamental-binary-stream (fundamental-stream) nil)
223
(defclass fundamental-character-input-stream
224
(fundamental-input-stream fundamental-character-stream) nil)
226
(defclass fundamental-character-output-stream
227
(fundamental-output-stream fundamental-character-stream) nil)
229
(defclass fundamental-binary-input-stream
230
(fundamental-input-stream fundamental-binary-stream) nil)
232
(defclass fundamental-binary-output-stream
233
(fundamental-output-stream fundamental-binary-stream) nil)
237
;;; The following methods constitute default implementations.
240
(defun bug-or-error (stream fun)
241
(declare (ext::c-local))
242
(error "The stream ~S has no suitable method for ~S." stream fun))
244
;; STREAM-ADVANCE-TO-COLUMN
246
(defmethod stream-advance-to-column ((stream fundamental-character-output-stream)
248
(let ((current-column (stream-line-column stream)))
250
(let ((fill (- column current-column)))
252
(stream-write-char stream #\Space)))
258
(defmethod stream-clear-input ((stream fundamental-character-input-stream))
260
(defmethod stream-clear-input ((stream stream))
261
(bug-or-error stream 'stream-clear-input))
262
(defmethod stream-clear-input ((non-stream t))
263
(error 'type-error :datum non-stream :expected-type 'stream))
268
(defmethod stream-clear-output ((stream fundamental-output-stream))
270
(defmethod stream-clear-output ((stream stream))
271
(bug-or-error stream 'stream-clear-output))
272
(defmethod stream-clear-output ((non-stream t))
273
(error 'type-error :datum non-stream :expected-type 'stream))
278
(defmethod stream-close ((stream fundamental-stream) &key abort)
279
(declare (ignore abort))
280
(setf (stream-open-p stream) nil)
284
;; STREAM-ELEMENT-TYPE
286
(defmethod stream-elt-type ((stream fundamental-character-stream))
289
(defmethod stream-elt-type ((stream stream))
290
(bug-or-error stream 'stream-elt-type))
292
(defmethod stream-elt-type ((non-stream t))
293
(error 'type-error :datum non-stream :expected-type 'stream))
298
(defmethod stream-finish-output ((stream fundamental-output-stream))
300
(defmethod stream-finish-output ((stream stream))
301
(bug-or-error stream 'stream-finish-output))
302
(defmethod stream-finish-output ((non-stream t))
303
(error 'type-error :datum non-stream :expected-type 'stream))
308
(defmethod stream-force-output ((stream fundamental-output-stream))
310
(defmethod stream-force-output ((stream stream))
311
(bug-or-error stream 'stream-force-output))
312
(defmethod stream-force-output ((non-stream t))
313
(error 'type-error :datum non-stream :expected-type 'stream))
318
(defmethod stream-fresh-line ((stream fundamental-character-output-stream))
319
(unless (stream-start-line-p stream)
320
(stream-terpri stream)
326
(defmethod stream-input-p ((stream fundamental-stream))
329
(defmethod stream-input-p ((stream fundamental-input-stream))
332
(defmethod stream-input-p ((stream stream))
333
(bug-or-error stream 'stream-input-p))
335
(defmethod stream-input-p ((non-stream t))
336
(error 'type-error :datum non-stream :expected-type 'stream))
339
;; INTERACTIVE-STREAM-P
341
(defmethod stream-interactive-p ((stream stream))
342
(bug-or-error stream 'stream-interactive-p))
344
(defmethod stream-interactive-p ((non-stream t))
345
(error 'type-error :datum non-stream :expected-type 'stream))
349
(defmethod stream-line-column ((stream fundamental-character-output-stream))
355
(defmethod stream-listen ((stream fundamental-character-input-stream))
356
(let ((char (stream-read-char-no-hang stream)))
357
(when (characterp char)
358
(stream-unread-char stream char)
364
(defmethod stream-open-p ((stream fundamental-stream))
365
(stream-open-p stream))
367
(defmethod stream-open-p ((stream stream))
368
(bug-or-error stream 'open-stream-p))
370
(defmethod stream-open-p ((non-stream t))
371
(error 'type-error :datum non-stream :expected-type 'stream))
376
(defmethod stream-output-p ((stream fundamental-stream))
379
(defmethod stream-output-p ((stream fundamental-output-stream))
382
(defmethod stream-output-p ((stream stream))
383
(bug-or-error stream 'stream-output-p))
385
(defmethod stream-output-p ((non-stream t))
386
(error 'type-error :datum non-stream :expected-type 'stream))
391
(defmethod stream-peek-char ((stream fundamental-character-input-stream))
392
(let ((char (stream-read-char stream)))
393
(unless (eq char :eof)
394
(stream-unread-char stream char))
400
(defmethod stream-read-byte ((stream stream))
401
(bug-or-error stream 'stream-read-byte))
402
(defmethod stream-read-byte ((non-stream t))
403
(error 'type-error :datum non-stream :expected-type 'stream))
408
(defmethod stream-read-char-no-hang ((stream fundamental-character-input-stream))
409
(stream-read-char stream))
414
(defmethod stream-read-line ((stream fundamental-character-input-stream))
415
(let ((res (make-string 80))
419
(let ((ch (stream-read-char stream)))
421
(return (values (shrink-vector res index) t)))
423
(when (char= ch #\newline)
424
(return (values (shrink-vector res index) nil)))
427
(let ((new (make-string len)))
430
(setf (schar res index) ch)
436
(defmethod stream-read-sequence ((stream fundamental-character-input-stream)
438
&optional (start 0) (end nil))
439
(si::do-read-sequence seq stream start end))
441
(defmethod stream-read-sequence ((stream fundamental-binary-input-stream)
443
&optional (start 0) (end nil))
444
(si::do-read-sequence seq stream start end))
449
(defmethod stream-start-line-p ((stream fundamental-character-output-stream))
450
(eql (stream-line-column stream) 0))
455
(defmethod stream-write-byte ((stream stream) integer)
456
(bug-or-error stream 'stream-write-byte))
457
(defmethod stream-write-byte ((non-stream t) integer)
458
(error 'type-error :datum non-stream :expected-type 'stream))
463
(defmethod stream-write-sequence ((stream fundamental-character-output-stream)
465
&optional (start 0) (end nil))
466
(si::do-write-sequence seq stream start end))
468
(defmethod stream-write-sequence ((stream fundamental-binary-output-stream)
470
&optional (start 0) (end nil))
471
(si::do-write-sequence seq stream start end))
475
(defmethod stream-write-string ((stream fundamental-character-output-stream)
476
string &optional (start 0) end)
477
(declare (string string)
479
(let ((end (or end (length string))))
480
(declare (fixnum end))
481
(do ((pos start (1+ pos)))
483
(declare (type index pos))
484
(stream-write-char stream (aref string pos))))
490
(defmethod stream-terpri ((stream fundamental-character-output-stream))
491
(stream-write-char stream #\Newline))