A stream @IGindex{stream} is an object that can be used with an input or output function to identify an appropriate source or sink of characters or bytes for that operation. A character @IGindex{character} stream @IGindex{stream} is a source or sink of characters. A binary @IGindex{binary} stream @IGindex{stream} is a source or sink of bytes.
Some operations may be performed on any kind of stream; Figure 21--1 provides a list of standardized operations that are potentially useful with any kind of stream.
close stream-element-type input-stream-p streamp interactive-stream-p with-open-stream output-stream-p
Figure 21--1: Some General-Purpose Stream Operations
Other operations are only meaningful on certain stream types. For example, read-char is only defined for character streams and read-byte is only defined for binary streams.
A stream, whether a character stream or a binary stream, can be an input @IGindex{input} stream @IGindex{stream} (source of data), an output @IGindex{output} stream @IGindex{stream} (sink for data), both, or (e.g., when ":direction :probe" is given to open) neither.
Figure 21--2 shows operators relating to input streams.
clear-input read-byte read-from-string listen read-char read-line peek-char read-char-no-hang read-preserving-whitespace read read-delimited-list unread-char
Figure 21--2: Operators relating to Input Streams.
Figure 21--3 shows operators relating to output streams.
clear-output prin1 write finish-output prin1-to-string write-byte force-output princ write-char format princ-to-string write-line fresh-line print write-string pprint terpri write-to-string
Figure 21--3: Operators relating to Output Streams.
A stream that is both an input stream and an output stream is called a bidirectional @IGindex{bidirectional} stream @IGindex{stream} . See the functions input-stream-p and output-stream-p.
Any of the operators listed in Figure~21--2 or Figure~21--3 can be used with bidirectional streams. In addition, Figure 21--4 shows a list of operators that relate specificaly to bidirectional streams.
y-or-n-p yes-or-no-p
Figure 21--4: Operators relating to Bidirectional Streams.
Streams are either open @IGindex{open} or closed @IGindex{closed} .
Except as explicitly specified otherwise, operations that create and return streams return open streams.
The action of closing a stream marks the end of its use as a source or sink of data, permitting the implementation to reclaim its internal data structures, and to free any external resources which might have been locked by the stream when it was opened.
Except as explicitly specified otherwise, the consequences are undefined when a closed stream is used where a stream is called for.
Coercion of streams to pathnames is permissible for closed streams; in some situations, such as for a truename computation, the result might be different for an open stream and for that same stream once it has been closed.
An interactive stream @IGindex{interactive stream} is one on which it makes sense to perform interactive querying.
The precise meaning of an interactive stream is implementation-defined, and may depend on the underlying operating system. Some examples of the things that an implementation might choose to use as identifying characteristics of an interactive stream include:
The general intent of having some streams be classified as interactive streams is to allow them to be distinguished from streams containing batch (or background or command-file) input. Output to batch streams is typically discarded or saved for later viewing, so interactive queries to such streams might not have the expected effect.
Terminal I/O might or might not be an interactive stream.
Some streams, called file streams @IGindex{file stream} , provide access to files. An object of class file-stream is used to represent a file stream.
The basic operation for opening a file is open, which typically returns a file stream (see its dictionary entry for details). The basic operation for closing a stream is close. The macro with-open-file is useful to express the common idiom of opening a file for the duration of a given body of code, and assuring that the resulting stream is closed upon exit from that body.
The class stream has a number of subclasses defined by this specification. Figure 21--5 shows some information about these subclasses.
Class Related Operators broadcast-stream make-broadcast-stream broadcast-stream-streams concatenated-stream make-concatenated-stream concatenated-stream-streams echo-stream make-echo-stream echo-stream-input-stream echo-stream-output-stream string-stream make-string-input-stream with-input-from-string make-string-output-stream with-output-to-string get-output-stream-string synonym-stream make-synonym-stream synonym-stream-symbol two-way-stream make-two-way-stream two-way-stream-input-stream two-way-stream-output-stream
Figure 21--5: Defined Names related to Specialized Streams
Variables whose values must be streams are sometimes called stream variables @IGindex{stream variable} .
Certain stream variables are defined by this specification to be the proper source of input or output in various situations where no specific stream has been specified instead. A complete list of such standardized stream variables appears in Figure 21--6. The consequences are undefined if at any time the value of any of these variables is not an open stream.
Glossary Term Variable Name debug I/O *debug-io* error output *error-output* query I/O *query-io* standard input *standard-input* standard output *standard-output* terminal I/O *terminal-io* trace output *trace-output*
Figure 21--6: Standardized Stream Variables
Note that, by convention, standardized stream variables have names ending in "-input*" if they must be input streams, ending in "-output*" if they must be output streams, or ending in "-io*" if they must be bidirectional streams.
User programs may assign or bind any standardized stream variable except *terminal-io*.
The operators in Figure 21--7 accept stream arguments that might be either open or closed streams.
broadcast-stream-streams file-author pathnamep close file-namestring probe-file compile-file file-write-date rename-file compile-file-pathname host-namestring streamp concatenated-stream-streams load synonym-stream-symbol delete-file logical-pathname translate-logical-pathname directory merge-pathnames translate-pathname directory-namestring namestring truename dribble open two-way-stream-input-stream echo-stream-input-stream open-stream-p two-way-stream-output-stream echo-stream-ouput-stream parse-namestring wild-pathname-p ed pathname with-open-file enough-namestring pathname-match-p
Figure 21--7: Operators that accept either Open or Closed Streams
The operators in Figure 21--8 accept stream arguments that must be open streams.
clear-input output-stream-p read-char-no-hang clear-output peek-char read-delimited-list file-length pprint read-line file-position pprint-fill read-preserving-whitespace file-string-length pprint-indent stream-element-type finish-output pprint-linear stream-external-format force-output pprint-logical-block terpri format pprint-newline unread-char fresh-line pprint-tab with-open-stream get-output-stream-string pprint-tabular write input-stream-p prin1 write-byte interactive-stream-p princ write-char listen print write-line make-broadcast-stream print-object write-string make-concatenated-stream print-unreadable-object y-or-n-p make-echo-stream read yes-or-no-p make-synonym-stream read-byte make-two-way-stream read-char
Figure 21--8: Operators that accept Open Streams only
The consequences are undefined if any component of a composite stream is closed before the composite stream is closed.
The consequences are undefined if the synonym stream symbol is not bound to an open stream from the time of the synonym stream's creation until the time it is closed.
stream, t
A stream is an object that can be used with an input or output function to identify an appropriate source or sink of characters or bytes for that operation.
For more complete information, see section Stream Concepts.
section Stream Concepts, section Printing Other Objects, {section Printer}, {section Reader}
broadcast-stream, stream, t
A broadcast stream is an output stream which has associated with it a set of zero or more output streams such that any output sent to the broadcast stream gets passed on as output to each of the associated output streams. (If a broadcast stream has no component streams, then all output to the broadcast stream is discarded.)
The set of operations that may be performed on a broadcast stream is the intersection of those for its associated output streams.
Some output operations (e.g., fresh-line) return values based on the state of the stream at the time of the operation.
Since these values might differ for each of the component streams, it is necessary to describe their return value specifically:
For any output operations not having their return values explicitly specified above or elsewhere in this document, it is defined that the values returned by such an operation are the values resulting from performing the operation on the last of its component streams; the values resulting from performing the operation on all preceding streams are discarded. If there are no component streams, the value is implementation-dependent.
section broadcast-stream-streams [Function] , section make-broadcast-stream [Function]
concatenated-stream, stream, t
A concatenated stream is an input stream which is a composite stream of zero or more other input streams, such that the sequence of data which can be read from the concatenated stream is the same as the concatenation of the sequences of data which could be read from each of the constituent streams.
Input from a concatenated stream is taken from the first of the associated input streams until it reaches end of file_1; then that stream is discarded, and subsequent input is taken from the next input stream, and so on. An end of file on the associated input streams is always managed invisibly by the concatenated stream---the only time a client of a concatenated stream sees an end of file is when an attempt is made to obtain data from the concatenated stream but it has no remaining input streams from which to obtain such data.
section concatenated-stream-streams [Function] , section make-concatenated-stream [Function]
echo-stream, stream, t
An echo stream is a bidirectional stream that gets its input from an associated input stream and sends its output to an associated output stream.
All input taken from the input stream is echoed to the output stream. Whether the input is echoed immediately after it is encountered, or after it has been read from the input stream is implementation-dependent.
@xref{echo-stream-input-stream; echo-stream-output-stream} , echo-stream-output-stream, section make-echo-stream [Function]
file-stream, stream, t
An object of type file-stream is a stream the direct source or sink of which is a file. Such a stream is created explicitly by open and with-open-file, and implicitly by functions such as load that process files.
section load [Function] , section open [Function] , section with-open-file [macro]
string-stream, stream, t
A string stream is a stream which reads input from or writes output to an associated string.
The stream element type of a string stream is always a subtype of type character.
section make-string-input-stream [Function] , section make-string-output-stream [Function] , section with-input-from-string [Macro] , section with-output-to-string [Macro]
synonym-stream, stream, t
A stream that is an alias for another stream, which is the value of a dynamic variable whose name is the synonym stream symbol of the synonym stream.
Any operations on a synonym stream will be performed on the stream that is then the value of the dynamic variable named by the synonym stream symbol. If the value of the variable should change, or if the variable should be bound, then the stream will operate on the new value of the variable.
section make-synonym-stream [Function] , section synonym-stream-symbol [Function]
two-way-stream, stream, t
A bidirectional composite stream that receives its input from an associated input stream and sends its output to an associated output stream.
section make-two-way-stream [Function] , @xref{two-way-stream-input-stream; two-way-stream-output-stream} , two-way-stream-output-stream
input-stream-p stream => generalized-boolean
output-stream-p stream => generalized-boolean
stream---a stream.
generalized-boolean---a generalized boolean.
input-stream-p returns true if stream is an input stream; otherwise, returns false.
output-stream-p returns true if stream is an output stream; otherwise, returns false.
(input-stream-p *standard-input*) => true (input-stream-p *terminal-io*) => true (input-stream-p (make-string-output-stream)) => false (output-stream-p *standard-output*) => true (output-stream-p *terminal-io*) => true (output-stream-p (make-string-input-stream "jr")) => false
Should signal an error of type type-error if stream is not a stream.
interactive-stream-p stream => generalized-boolean
stream---a stream.
generalized-boolean---a generalized boolean.
Returns true if stream is an interactive stream; otherwise, returns false.
(when (> measured limit)
(let ((error (round (* (- measured limit) 100)
limit)))
(unless (if (interactive-stream-p *query-io*)
(yes-or-no-p "The frammis is out of tolerance by ~D
Is it safe to proceed? " error)
(< error 15)) ;15
(error "The frammis is out of tolerance by ~D
Should signal an error of type type-error if stream is not a stream.
section Stream Concepts
open-stream-p stream => generalized-boolean
stream---a stream.
generalized-boolean---a generalized boolean.
Returns true if stream is an open stream; otherwise, returns false.
Streams are open until they have been explicitly closed with close, or until they are implicitly closed due to exit from a with-output-to-string, with-open-file, with-input-from-string, or with-open-stream form.
(open-stream-p *standard-input*) => true
close.
Should signal an error of type type-error if stream is not a stream.
stream-element-type stream => typespec
stream---a stream.
typespec---a type specifier.
stream-element-type returns a type specifier that indicates the types of objects that may be read from or written to stream.
Streams created by open have an element type restricted to integer or a subtype of type character.
;; Note that the stream must accomodate at least the specified type,
;; but might accomodate other types. Further note that even if it does
;; accomodate exactly the specified type, the type might be specified in
;; any of several ways.
(with-open-file (s "test" :element-type '(integer 0 1)
:if-exists :error
:direction :output)
(stream-element-type s))
=> INTEGER
OR=> (UNSIGNED-BYTE 16)
OR=> (UNSIGNED-BYTE 8)
OR=> BIT
OR=> (UNSIGNED-BYTE 1)
OR=> (INTEGER 0 1)
OR=> (INTEGER 0 (2))
Should signal an error of type type-error if stream is not a stream.
streamp object => generalized-boolean
object---an object.
generalized-boolean---a generalized boolean.
Returns true if object is of type stream; otherwise, returns false.
streamp is unaffected by whether object, if it is a stream, is open or closed.
(streamp *terminal-io*) => true (streamp 1) => false
(streamp object) == (typep object 'stream)
read-byte stream {&optional eof-error-p eof-value} => byte
stream---a binary input stream.
eof-error-p---a generalized boolean. The default is true.
eof-value---an object. The default is nil.
byte---an integer, or the eof-value.
read-byte reads and returns one byte from stream.
Iftml#SEC1149">Stream Concepts, section Printing Other Objects, {section Printer}, {section Reader}
broadcast-stream, stream, t
A broadcast stream is an output stream which has associated with it a set of zero or more output streams such that any output sent to the broadcast stream gets passed on as output to each of the associated output streams. (If a broadcast stream has no component streams, then all output to the broadcast stream is discarded.)
The set of operations that may be performed on a broadcast stream is the intersection of those for its associated output streams.
Some output operations (e.g., fresh-line) return values based on the state of the stream at the time of the operation.
Since these values might differ for each of the component streams, it is necessary to describe their return value specifically:
For any output operations not having their return values explicitly specified above or elsewhere in this document, it is defined that the values returned by such an operation are the values resulting from performing the operation on the last of its component streams; the values resulting from performing the operation on all preceding streams are discarded. If there are no component streams, the value is implementation-dependent.
section broadcast-stream-streams [Function] , section make-broadcast-stream [Function]
concatenated-stream, stream, t
A concatenated stream is an input stream which is a composite stream of zero or more other input streams, such that the sequence of data which can be read from the concatenated stream is the same as the concatenation of the sequences of data which could be read from each of the constituent streams.
Input from a concatenated stream is taken from the first of the associated input streams until it reaches end of file_1; then that stream is discarded, and subsequent input is taken from the next input stream, and so on. An end of file on the associated input streams is always managed invisibly by the concatenated stream---the only time a client of a concatenated stream sees an end of file is when an attempt is made to obtain data from the concatenated stream but it has no remaining input streams from which to obtain such data.
section concatenated-stream-streams [Function] , section make-concatenated-stream [Function]
echo-stream, stream, t
An echo stream is a bidirectional stream that gets its input from an associated input stream and sends its output to an associated output stream.
All input taken from the input stream is echoed to the output stream. Whether the input is echoed immediately after it is encountered, or after it has been read from the input stream is implementation-dependent.
@xref{echo-stream-input-stream; echo-stream-output-stream} , echo-stream-output-stream, section make-echo-stream [Function]
file-stream, stream, t
An object of type file-stream is a stream the direct source or sink of which is a file. Such a stream is created explicitly by open and with-open-file, and implicitly by functions such as load that process files.
section load [Function] , section open [Function] , section with-open-file [macro]
string-stream, stream, t
A string stream is a stream which reads input from or writes output to an associated string.
The stream element type of a string stream is always a subtype of type character.
section make-string-input-stream [Function] , section make-string-output-stream [Function] , section with-input-from-string [Macro] , section with-output-to-string [Macro]
synonym-stream, stream, t
A stream that is an alias for another stream, which is the value of a dynamic variable whose name is the synonym stream symbol of the synonym stream.
Any operations on a synonym stream will be performed on the stream that is then the value of the dynamic variable named by the synonym stream symbol. If the value of the variable should change, or if the variable should be bound, then the stream will operate on the new value of the variable.
section make-synonym-stream [Function] , section synonym-stream-symbol [Function]
two-way-stream, stream, t
A bidirectional composite stream that receives its input from an associated input stream and sends its output to an associated output stream.
section make-two-way-stream [Function] , @xref{two-way-stream-input-stream; two-way-stream-output-stream} , two-way-stream-output-stream
input-stream-p stream => generalized-boolean
output-stream-p stream => generalized-boolean
stream---a stream.
generalized-boolean---a generalized boolean.
input-stream-p returns true if stream is an input stream; otherwise, returns false.
output-stream-p returns true if stream is an output stream; otherwise, returns false.
(input-stream-p *standard-input*) => true (input-stream-p *terminal-io*) => true (input-stream-p (make-string-output-stream)) => false (output-stream-p *standard-output*) => true (output-stream-p *terminal-io*) => true (output-stream-p (make-string-input-stream "jr")) => false
Should signal an error of type type-error if stream is not a stream.
interactive-stream-p stream => generalized-boolean
stream---a stream.
generalized-boolean---a generalized boolean.
Returns true if stream is an interactive stream; otherwise, returns false.
(when (> measured limit)
(let ((error (round (* (- measured limit) 100)
limit)))
(unless (if (interactive-stream-p *query-io*)
(yes-or-no-p "The frammis is out of tolerance by ~D
Is it safe to proceed? " error)
(< error 15)) ;15
(error "The frammis is out of tolerance by ~D
Should signal an error of type type-error if stream is not a stream.
section Stream Concepts
open-stream-p stream => generalized-boolean
stream---a stream.
generalized-boolean---a generalized boolean.
Returns true if stream is an open stream; otherwise, returns false.
Streams are open until they have been explicitly closed with close, or until they are implicitly closed due to exit from a with-output-to-string, with-open-file, with-input-from-string, or with-open-stream form.
(open-stream-p *standard-input*) => true
close.
Should signal an error of type type-error if stream is not a stream.
stream-element-type stream => typespec
stream---a stream.
typespec---a type specifier.
stream-element-type returns a type specifier that indicates the types of objects that may be read from or written to stream.
Streams created by open have an element type restricted to integer or a subtype of type character.
;; Note that the stream must accomodate at least the specified type,
;; but might accomodate other types. Further note that even if it does
;; accomodate exactly the specified type, the type might be specified in
;; any of several ways.
(with-open-file (s "test" :element-type '(integer 0 1)
:if-exists :error
:direction :output)
(stream-element-type s))
=> INTEGER
OR=> (UNSIGNED-BYTE 16)
OR=> (UNSIGNED-BYTE 8)
OR=> BIT
OR=> (UNSIGNED-BYTE 1)
OR=> (INTEGER 0 1)
OR=> (INTEGER 0 (2))
Should signal an error of type type-error if stream is not a stream.
streamp object => generalized-boolean
object---an object.
generalized-boolean---a generalized boolean.
Returns true if object is of type stream; otherwise, returns false.
streamp is unaffected by whether object, if it is a stream, is open or closed.
(streamp *terminal-io*) => true (streamp 1) => false
(streamp object) == (typep object 'stream)
read-byte stream {&optional eof-error-p eof-value} => byte
stream---a binary input stream.
eof-error-p---a generalized boolean. The default is true.
eof-value---an object. The default is nil.
byte---an integer, or the eof-value.
read-byte reads and returns one byte from stream.
Iftml#SEC1149">Stream Concepts, section Printing Other Objects, {section Printer}, {section Reader}
broadcast-stream, stream, t
A broadcast stream is an output stream which has associated with it a set of zero or more output streams such that any output sent to the broadcast stream gets passed on as output to each of the associated output streams. (If a broadcast stream has no component streams, then all output to the broadcast stream is discarded.)
The set of operations that may be performed on a broadcast stream is the intersection of those for its associated output streams.
Some output operations (e.g., fresh-line) return values based on the state of the stream at the time of the operation.
Since these values might differ for each of the component streams, it is necessary to describe their return value specifically:
For any output operations not having their return values explicitly specified above or elsewhere in this document, it is defined that the values returned by such an operation are the values resulting from performing the operation on the last of its component streams; the values resulting from performing the operation on all preceding streams are discarded. If there are no component streams, the value is implementation-dependent.
section broadcast-stream-streams [Function] , section make-broadcast-stream [Function]
concatenated-stream, stream, t
A concatenated stream is an input stream which is a composite stream of zero or more other input streams, such that the sequence of data which can be read from the concatenated stream is the same as the concatenation of the sequences of data which could be read from each of the constituent streams.
Input from a concatenated stream is taken from the first of the associated input streams until it reaches end of file_1; then that stream is discarded, and subsequent input is taken from the next input stream, and so on. An end of file on the associated input streams is always managed invisibly by the concatenated stream---the only time a client of a concatenated stream sees an end of file is when an attempt is made to obtain data from the concatenated stream but it has no remaining input streams from which to obtain such data.
section concatenated-stream-streams [Function] , section make-concatenated-stream [Function]
echo-stream, stream, t
An echo stream is a bidirectional stream that gets its input from an associated input stream and sends its output to an associated output stream.
All input taken from the input stream is echoed to the output stream. Whether the input is echoed immediately after it is encountered, or after it has been read from the input stream is implementation-dependent.
@xref{echo-stream-input-stream; echo-stream-output-stream} , echo-stream-output-stream, section make-echo-stream [Function]
file-stream, stream, t
An object of type file-stream is a stream the direct source or sink of which is a file. Such a stream is created explicitly by open and with-open-file, and implicitly by functions such as load that process files.
section load [Function] , section open [Function] , section with-open-file [macro]
string-stream, stream, t
A string stream is a stream which reads input from or writes output to an associated string.
The stream element type of a string stream is always a subtype of type character.
section make-string-input-stream [Function] , section make-string-output-stream [Function] , section with-input-from-string [Macro] , section with-output-to-string [Macro]
synonym-stream, stream, t
A stream that is an alias for another stream, which is the value of a dynamic variable whose name is the synonym stream symbol of the synonym stream.
Any operations on a synonym stream will be performed on the stream that is then the value of the dynamic variable named by the synonym stream symbol. If the value of the variable should change, or if the variable should be bound, then the stream will operate on the new value of the variable.
section make-synonym-stream [Function] , section synonym-stream-symbol [Function]
two-way-stream, stream, t
A bidirectional composite stream that receives its input from an associated input stream and sends its output to an associated output stream.
section make-two-way-stream [Function] , @xref{two-way-stream-input-stream; two-way-stream-output-stream} , two-way-stream-output-stream
input-stream-p stream => generalized-boolean
output-stream-p stream => generalized-boolean
stream---a stream.
generalized-boolean---a generalized boolean.
input-stream-p returns true if stream is an input stream; otherwise, returns false.
output-stream-p returns true if stream is an output stream; otherwise, returns false.
(input-stream-p *standard-input*) => true (input-stream-p *terminal-io*) => true (input-stream-p (make-string-output-stream)) => false (output-stream-p *standard-output*) => true (output-stream-p *terminal-io*) => true (output-stream-p (make-string-input-stream "jr")) => false
Should signal an error of type type-error if stream is not a stream.
interactive-stream-p stream => generalized-boolean
stream---a stream.
generalized-boolean---a generalized boolean.
Returns true if stream is an interactive stream; otherwise, returns false.
(when (> measured limit)
(let ((error (round (* (- measured limit) 100)
limit)))
(unless (if (interactive-stream-p *query-io*)
(yes-or-no-p "The frammis is out of tolerance by ~D
Is it safe to proceed? " error)
(< error 15)) ;15
(error "The frammis is out of tolerance by ~D
Should signal an error of type type-error if stream is not a stream.
section Stream Concepts
open-stream-p stream => generalized-boolean
stream---a stream.
generalized-boolean---a generalized boolean.
Returns true if stream is an open stream; otherwise, returns false.
Streams are open until they have been explicitly closed with close, or until they are implicitly closed due to exit from a with-output-to-string, with-open-file, with-input-from-string, or with-open-stream form.
(open-stream-p *standard-input*) => true
close.
Should signal an error of type type-error if stream is not a stream.
stream-element-type stream => typespec
stream---a stream.
typespec---a type specifier.
stream-element-type returns a type specifier that indicates the types of objects that may be read from or written to stream.
Streams created by open have an element type restricted to integer or a subtype of type character.
;; Note that the stream must accomodate at least the specified type,
;; but might accomodate other types. Further note that even if it does
;; accomodate exactly the specified type, the type might be specified in
;; any of several ways.
(with-open-file (s "test" :element-type '(integer 0 1)
:if-exists :error
:direction :output)
(stream-element-type s))
=> INTEGER
OR=> (UNSIGNED-BYTE 16)
OR=> (UNSIGNED-BYTE 8)
OR=> BIT
OR=> (UNSIGNED-BYTE 1)
OR=> (INTEGER 0 1)
OR=> (INTEGER 0 (2))
Should signal an error of type type-error if stream is not a stream.
streamp object => generalized-boolean
object---an object.
generalized-boolean---a generalized boolean.
Returns true if object is of type stream; otherwise, returns false.
streamp is unaffected by whether object, if it is a stream, is open or closed.
(streamp *terminal-io*) => true (streamp 1) => false
(streamp object) == (typep object 'stream)
read-byte stream {&optional eof-error-p eof-value} => byte
stream---a binary input stream.
eof-error-p---a generalized boolean. The default is true.
eof-value---an object. The default is nil.
byte---an integer, or the eof-value.
read-byte reads and returns one byte from stream.
Iftml#SEC1149">Stream Concepts, section Printing Other Objects, {section Printer}, {section Reader}
broadcast-stream, stream, t
A broadcast stream is an output stream which has associated with it a set of zero or more output streams such that any output sent to the broadcast stream gets passed on as output to each of the associated output streams. (If a broadcast stream has no component streams, then all output to the broadcast stream is discarded.)
The set of operations that may be performed on a broadcast stream is the intersection of those for its associated output streams.
Some output operations (e.g., fresh-line) return values based on the state of the stream at the time of the operation.
Since these values might differ for each of the component streams, it is necessary to describe their return value specifically:
For any output operations not having their return values explicitly specified above or elsewhere in this document, it is defined that the values returned by such an operation are the values resulting from performing the operation on the last of its component streams; the values resulting from performing the operation on all preceding streams are discarded. If there are no component streams, the value is implementation-dependent.
section broadcast-stream-streams [Function] , section make-broadcast-stream [Function]
concatenated-stream, stream, t
A concatenated stream is an input stream which is a composite stream of zero or more other input streams, such that the sequence of data which can be read from the concatenated stream is the same as the concatenation of the sequences of data which could be read from each of the constituent streams.
Input from a concatenated stream is taken from the first of the associated input streams until it reaches end of file_1; then that stream is discarded, and subsequent input is taken from the next input stream, and so on. An end of file on the associated input streams is always managed invisibly by the concatenated stream---the only time a client of a concatenated stream sees an end of file is when an attempt is made to obtain data from the concatenated stream but it has no remaining input streams from which to obtain such data.
section concatenated-stream-streams [Function] , section make-concatenated-stream [Function]
echo-stream, stream, t
An echo stream is a bidirectional stream that gets its input from an associated input stream and sends its output to an associated output stream.
All input taken from the input stream is echoed to the output stream. Whether the input is echoed immediately after it is encountered, or after it has been read from the input stream is implementation-dependent.
@xref{echo-stream-input-stream; echo-stream-output-stream} , echo-stream-output-stream, section make-echo-stream [Function]
file-stream, stream, t
An object of type file-stream is a stream the direct source or sink of which is a file. Such a stream is created explicitly by open and with-open-file, and implicitly by functions such as load that process files.
section load [Function] , section open [Function] , section with-open-file [macro]
string-stream, stream, t
A string stream is a stream which reads input from or writes output to an associated string.
The stream element type of a string stream is always a subtype of type character.
section make-string-input-stream [Function] , section make-string-output-stream [Function] , section with-input-from-string [Macro] , section with-output-to-string [Macro]
synonym-stream, stream, t
A stream that is an alias for another stream, which is the value of a dynamic variable whose name is the synonym stream symbol of the synonym stream.
Any operations on a synonym stream will be performed on the stream that is then the value of the dynamic variable named by the synonym stream symbol. If the value of the variable should change, or if the variable should be bound, then the stream will operate on the new value of the variable.
section make-synonym-stream [Function] , section synonym-stream-symbol [Function]
two-way-stream, stream, t
A bidirectional composite stream that receives its input from an associated input stream and sends its output to an associated output stream.
section make-two-way-stream [Function] , @xref{two-way-stream-input-stream; two-way-stream-output-stream} , two-way-stream-output-stream
input-stream-p stream => generalized-boolean
output-stream-p stream => generalized-boolean
stream---a stream.
generalized-boolean---a generalized boolean.
input-stream-p returns true if stream is an input stream; otherwise, returns false.
output-stream-p returns true if stream is an output stream; otherwise, returns false.
(input-stream-p *standard-input*) => true (input-stream-p *terminal-io*) => true (input-stream-p (make-string-output-stream)) => false (output-stream-p *standard-output*) => true (output-stream-p *terminal-io*) => true (output-stream-p (make-string-input-stream "jr")) => false
Should signal an error of type type-error if stream is not a stream.
interactive-stream-p stream => generalized-boolean
stream---a stream.
generalized-boolean---a generalized boolean.
Returns true if stream is an interactive stream; otherwise, returns false.
(when (> measured limit)
(let ((error (round (* (- measured limit) 100)
limit)))
(unless (if (interactive-stream-p *query-io*)
(yes-or-no-p "The frammis is out of tolerance by ~D
Is it safe to proceed? " error)
(< error 15)) ;15
(error "The frammis is out of tolerance by ~D
Should signal an error of type type-error if stream is not a stream.
section Stream Concepts
open-stream-p stream => generalized-boolean
stream---a stream.
generalized-boolean---a generalized boolean.
Returns true if stream is an open stream; otherwise, returns false.
Streams are open until they have been explicitly closed with close, or until they are implicitly closed due to exit from a with-output-to-string, with-open-file, with-input-from-string, or with-open-stream form.
(open-stream-p *standard-input*) => true
close.
Should signal an error of type type-error if stream is not a stream.
stream-element-type stream => typespec
stream---a stream.
typespec---a type specifier.
stream-element-type returns a type specifier that indicates the types of objects that may be read from or written to stream.
Streams created by open have an element type restricted to integer or a subtype of type character.
;; Note that the stream must accomodate at least the specified type,
;; but might accomodate other types. Further note that even if it does
;; accomodate exactly the specified type, the type might be specified in
;; any of several ways.
(with-open-file (s "test" :element-type '(integer 0 1)
:if-exists :error
:direction :output)
(stream-element-type s))
=> INTEGER
OR=> (UNSIGNED-BYTE 16)
OR=> (UNSIGNED-BYTE 8)
OR=> BIT
OR=> (UNSIGNED-BYTE 1)
OR=> (INTEGER 0 1)
OR=> (INTEGER 0 (2))
Should signal an error of type type-error if stream is not a stream.
streamp object => generalized-boolean
object---an object.
generalized-boolean---a generalized boolean.
Returns true if object is of type stream; otherwise, returns false.
streamp is unaffected by whether object, if it is a stream, is open or closed.
(streamp *terminal-io*) => true (streamp 1) => false
(streamp object) == (typep object 'stream)
read-byte stream {&optional eof-error-p eof-value} => byte
stream---a binary input stream.
eof-error-p---a generalized boolean. The default is true.
eof-value---an object. The default is nil.
byte---an integer, or the eof-value.
read-byte reads and returns one byte from stream.
Iftml#SEC1149">Stream Concepts, section Printing Other Objects, {section Printer}, {section Reader}
broadcast-stream, stream, t
A broadcast stream is an output stream which has associated with it a set of zero or more output streams such that any output sent to the broadcast stream gets passed on as output to each of the associated output streams. (If a broadcast stream has no component streams, then all output to the broadcast stream is discarded.)
The set of operations that may be performed on a broadcast stream is the intersection of those for its associated output streams.
Some output operations (e.g., fresh-line) return values based on the state of the stream at the time of the operation.
Since these values might differ for each of the component streams, it is necessary to describe their return value specifically:
For any output operations not having their return values explicitly specified above or elsewhere in this document, it is defined that the values returned by such an operation are the values resulting from performing the operation on the last of its component streams; the values resulting from performing the operation on all preceding streams are discarded. If there are no component streams, the value is implementation-dependent.
section broadcast-stream-streams [Function] , section make-broadcast-stream [Function]
concatenated-stream, stream, t
A concatenated stream is an input stream which is a composite stream of zero or more other input streams, such that the sequence of data which can be read from the concatenated stream is the same as the concatenation of the sequences of data which could be read from each of the constituent streams.
Input from a concatenated stream is taken from the first of the associated input streams until it reaches end of file_1; then that stream is discarded, and subsequent input is taken from the next input stream, and so on. An end of file on the associated input streams is always managed invisibly by the concatenated stream---the only time a client of a concatenated stream sees an end of file is when an attempt is made to obtain data from the concatenated stream but it has no remaining input streams from which to obtain such data.
section concatenated-stream-streams [Function] , section make-concatenated-stream [Function]
echo-stream, stream, t
An echo stream is a bidirectional stream that gets its input from an associated input stream and sends its output to an associated output stream.
All input taken from the input stream is echoed to the output stream. Whether the input is echoed immediately after it is encountered, or after it has been read from the input stream is implementation-dependent.
@xref{echo-stream-input-stream; echo-stream-output-stream} , echo-stream-output-stream, section make-echo-stream [Function]
file-stream, stream, t
An object of type file-stream is a stream the direct source or sink of which is a file. Such a stream is created explicitly by open and with-open-file, and implicitly by functions such as load that process files.
section load [Function] , section open [Function] , section with-open-file [macro]
string-stream, stream, t
A string stream is a stream which reads input from or writes output to an associated string.
The stream element type of a string stream is always a subtype of type character.
section make-string-input-stream [Function] , section make-string-output-stream [Function] , section with-input-from-string [Macro] , section with-output-to-string [Macro]
synonym-stream, stream, t
A stream that is an alias for another stream, which is the value of a dynamic variable whose name is the synonym stream symbol of the synonym stream.
Any operations on a synonym stream will be performed on the stream that is then the value of the dynamic variable named by the synonym stream symbol. If the value of the variable should change, or if the variable should be bound, then the stream will operate on the new value of the variable.
section make-synonym-stream [Function] , section synonym-stream-symbol [Function]
two-way-stream, stream, t
A bidirectional composite stream that receives its input from an associated input stream and sends its output to an associated output stream.
section make-two-way-stream [Function] , @xref{two-way-stream-input-stream; two-way-stream-output-stream} , two-way-stream-output-stream
input-stream-p stream => generalized-boolean
output-stream-p stream => generalized-boolean
stream---a stream.
generalized-boolean---a generalized boolean.
input-stream-p returns true if stream is an input stream; otherwise, returns false.
output-stream-p returns true if stream is an output stream; otherwise, returns false.
(input-stream-p *standard-input*) => true (input-stream-p *terminal-io*) => true (input-stream-p (make-string-output-stream)) => false (output-stream-p *standard-output*) => true (output-stream-p *terminal-io*) => true (output-stream-p (make-string-input-stream "jr")) => false
Should signal an error of type type-error if stream is not a stream.
interactive-stream-p stream => generalized-boolean
stream---a stream.
generalized-boolean---a generalized boolean.
Returns true if stream is an interactive stream; otherwise, returns false.
(when (> measured limit)
(let ((error (round (* (- measured limit) 100)
limit)))
(unless (if (interactive-stream-p *query-io*)
(yes-or-no-p "The frammis is out of tolerance by ~D
Is it safe to proceed? " error)
(< error 15)) ;15
(error "The frammis is out of tolerance by ~D
Should signal an error of type type-error if stream is not a stream.
section Stream Concepts
open-stream-p stream => generalized-boolean
stream---a stream.
generalized-boolean---a generalized boolean.
Returns true if stream is an open stream; otherwise, returns false.
Streams are open until they have been explicitly closed with close, or until they are implicitly closed due to exit from a with-output-to-string, with-open-file, with-input-from-string, or with-open-stream form.
(open-stream-p *standard-input*) => true
close.
Should signal an error of type type-error if stream is not a stream.
stream-element-type stream => typespec
stream---a stream.
typespec---a type specifier.
stream-element-type returns a type specifier that indicates the types of objects that may be read from or written to stream.
Streams created by open have an element type restricted to integer or a subtype of type character.
;; Note that the stream must accomodate at least the specified type,
;; but might accomodate other types. Further note that even if it does
;; accomodate exactly the specified type, the type might be specified in
;; any of several ways.
(with-open-file (s "test" :element-type '(integer 0 1)
:if-exists :error
:direction :output)
(stream-element-type s))
=> INTEGER
OR=> (UNSIGNED-BYTE 16)
OR=> (UNSIGNED-BYTE 8)
OR=> BIT
OR=> (UNSIGNED-BYTE 1)
OR=> (INTEGER 0 1)
OR=> (INTEGER 0 (2))
Should signal an error of type type-error if stream is not a stream.
streamp object => generalized-boolean
object---an object.
generalized-boolean---a generalized boolean.
Returns true if object is of type stream; otherwise, returns false.
streamp is unaffected by whether object, if it is a stream, is open or closed.
(streamp *terminal-io*) => true (streamp 1) => false
(streamp object) == (typep object 'stream)
read-byte stream {&optional eof-error-p eof-value} => byte
stream---a binary input stream.
eof-error-p---a generalized boolean. The default is true.
eof-value---an object. The default is nil.
byte---an integer, or the eof-value.
read-byte reads and returns one byte from stream.
Iftml#SEC1149">Stream Concepts, section Printing Other Objects, {section Printer}, {section Reader}
broadcast-stream, stream, t
A broadcast stream is an output stream which has associated with it a set of zero or more output streams such that any output sent to the broadcast stream gets passed on as output to each of the associated output streams. (If a broadcast stream has no component streams, then all output to the broadcast stream is discarded.)
The set of operations that may be performed on a broadcast stream is the intersection of those for its associated output streams.
Some output operations (e.g., fresh-line) return values based on the state of the stream at the time of the operation.
Since these values might differ for each of the component streams, it is necessary to describe their return value specifically:
For any output operations not having their return values explicitly specified above or elsewhere in this document, it is defined that the values returned by such an operation are the values resulting from performing the operation on the last of its component streams; the values resulting from performing the operation on all preceding streams are discarded. If there are no component streams, the value is implementation-dependent.
section broadcast-stream-streams [Function] , section make-broadcast-stream [Function]
concatenated-stream, stream, t
A concatenated stream is an input stream which is a composite stream of zero or more other input streams, such that the sequence of data which can be read from the concatenated stream is the same as the concatenation of the sequences of data which could be read from each of the constituent streams.
Input from a concatenated stream is taken from the first of the associated input streams until it reaches end of file_1; then that stream is discarded, and subsequent input is taken from the next input stream, and so on. An end of file on the associated input streams is always managed invisibly by the concatenated stream---the only time a client of a concatenated stream sees an end of file is when an attempt is made to obtain data from the concatenated stream but it has no remaining input streams from which to obtain such data.
section concatenated-stream-streams [Function] , section make-concatenated-stream [Function]
echo-stream, stream, t
An echo stream is a bidirectional stream that gets its input from an associated input stream and sends its output to an associated output stream.
All input taken from the input stream is echoed to the output stream. Whether the input is echoed immediately after it is encountered, or after it has been read from the input stream is implementation-dependent.
@xref{echo-stream-input-stream; echo-stream-output-stream} , echo-stream-output-stream, section make-echo-stream [Function]
file-stream, stream, t
An object of type file-stream is a stream the direct source or sink of which is a file. Such a stream is created explicitly by open and with-open-file, and implicitly by functions such as load that process files.
section load [Function] , section open [Function] , section with-open-file [macro]
string-stream, stream, t
A string stream is a stream which reads input from or writes output to an associated string.
The stream element type of a string stream is always a subtype of type character.
section make-string-input-stream [Function] , section make-string-output-stream [Function] , section with-input-from-string [Macro] , section with-output-to-string [Macro]
synonym-stream, stream, t
A stream that is an alias for another stream, which is the value of a dynamic variable whose name is the synonym stream symbol of the synonym stream.
Any operations on a synonym stream will be performed on the stream that is then the value of the dynamic variable named by the synonym stream symbol. If the value of the variable should change, or if the variable should be bound, then the stream will operate on the new value of the variable.
section make-synonym-stream [Function] , section synonym-stream-symbol [Function]
two-way-stream, stream, t
A bidirectional composite stream that receives its input from an associated input stream and sends its output to an associated output stream.
section make-two-way-stream [Function] , @xref{two-way-stream-input-stream; two-way-stream-output-stream} , two-way-stream-output-stream
input-stream-p stream => generalized-boolean
output-stream-p stream => generalized-boolean
stream---a stream.
generalized-boolean---a generalized boolean.
input-stream-p returns true if stream is an input stream; otherwise, returns false.
output-stream-p returns true if stream is an output stream; otherwise, returns false.
(input-stream-p *standard-input*) => true (input-stream-p *terminal-io*) => true (input-stream-p (make-string-output-stream)) => false (output-stream-p *standard-output*) => true (output-stream-p *terminal-io*) => true (output-stream-p (make-string-input-stream "jr")) => false
Should signal an error of type type-error if stream is not a stream.
interactive-stream-p stream => generalized-boolean
stream---a stream.
generalized-boolean---a generalized boolean.
Returns true if stream is an interactive stream; otherwise, returns false.
(when (> measured limit)
(let ((error (round (* (- measured limit) 100)
limit)))
(unless (if (interactive-stream-p *query-io*)
(yes-or-no-p "The frammis is out of tolerance by ~D
Is it safe to proceed? " error)
(< error 15)) ;15
(error "The frammis is out of tolerance by ~D
Should signal an error of type type-error if stream is not a stream.
section Stream Concepts
open-stream-p stream => generalized-boolean
stream---a stream.
generalized-boolean---a generalized boolean.
Returns true if stream is an open stream; otherwise, returns false.
Streams are open until they have been explicitly closed with close, or until they are implicitly closed due to exit from a with-output-to-string, with-open-file, with-input-from-string, or with-open-stream form.
(open-stream-p *standard-input*) => true
close.
Should signal an error of type type-error if stream is not a stream.
stream-element-type stream => typespec
stream---a stream.
typespec---a type specifier.
stream-element-type returns a type specifier that indicates the types of objects that may be read from or written to stream.
Streams created by open have an element type restricted to integer or a subtype of type character.
;; Note that the stream must accomodate at least the specified type,
;; but might accomodate other types. Further note that even if it does
;; accomodate exactly the specified type, the type might be specified in
;; any of several ways.
(with-open-file (s "test" :element-type '(integer 0 1)
:if-exists :error
:direction :output)
(stream-element-type s))
=> INTEGER
OR=> (UNSIGNED-BYTE 16)
OR=> (UNSIGNED-BYTE 8)
OR=> BIT
OR=> (UNSIGNED-BYTE 1)
OR=> (INTEGER 0 1)
OR=> (INTEGER 0 (2))
Should signal an error of type type-error if stream is not a stream.
streamp object => generalized-boolean
object---an object.
generalized-boolean---a generalized boolean.
Returns true if object is of type stream; otherwise, returns false.
streamp is unaffected by whether object, if it is a stream, is open or closed.
(streamp *terminal-io*) => true (streamp 1) => false
(streamp object) == (typep object 'stream)
read-byte stream {&optional eof-error-p eof-value} => byte
stream---a binary input stream.
eof-error-p---a generalized boolean. The default is true.
eof-value---an object. The default is nil.
byte---an integer, or the eof-value.
read-byte reads and returns one byte from stream.
Iftml#SEC1149">Stream Concepts, section Printing Other Objects, {section Printer}, {section Reader}
broadcast-stream, stream, t
A broadcast stream is an output stream which has associated with it a set of zero or more output streams such that any output sent to the broadcast stream gets passed on as output to each of the associated output streams. (If a broadcast stream has no component streams, then all output to the broadcast stream is discarded.)
The set of operations that may be performed on a broadcast stream is the intersection of those for its associated output streams.
Some output operations (e.g., fresh-line) return values based on the state of the stream at the time of the operation.
Since these values might differ for each of the component streams, it is necessary to describe their return value specifically:
For any output operations not having their return values explicitly specified above or elsewhere in this document, it is defined that the values returned by such an operation are the values resulting from performing the operation on the last of its component streams; the values resulting from performing the operation on all preceding streams are discarded. If there are no component streams, the value is implementation-dependent.
section broadcast-stream-streams [Function] , section make-broadcast-stream [Function]
concatenated-stream, stream, t
A concatenated stream is an input stream which is a composite stream of zero or more other input streams, such that the sequence of data which can be read from the concatenated stream is the same as the concatenation of the sequences of data which could be read from each of the constituent streams.
Input from a concatenated stream is taken from the first of the associated input streams until it reaches end of file_1; then that stream is discarded, and subsequent input is taken from the next input stream, and so on. An end of file on the associated input streams is always managed invisibly by the concatenated stream---the only time a client of a concatenated stream sees an end of file is when an attempt is made to obtain data from the concatenated stream but it has no remaining input streams from which to obtain such data.
section concatenated-stream-streams [Function] , section make-concatenated-stream [Function]
echo-stream, stream, t
An echo stream is a bidirectional stream that gets its input from an associated input stream and sends its output to an associated output stream.
All input taken from the input stream is echoed to the output stream. Whether the input is echoed immediately after it is encountered, or after it has been read from the input stream is implementation-dependent.
@xref{echo-stream-input-stream; echo-stream-output-stream} , echo-stream-output-stream, section make-echo-stream [Function]
file-stream, stream, t
An object of type file-stream is a stream the direct source or sink of which is a file. Such a stream is created explicitly by open and with-open-file, and implicitly by functions such as load that process files.
section load [Function] , section open [Function] , section with-open-file [macro]
string-stream, stream, t
A string stream is a stream which reads input from or writes output to an associated string.
The stream element type of a string stream is always a subtype of type character.
section make-string-input-stream [Function] , section make-string-output-stream [Function] , section with-input-from-string [Macro] , section with-output-to-string [Macro]
synonym-stream, stream, t
A stream that is an alias for another stream, which is the value of a dynamic variable whose name is the synonym stream symbol of the synonym stream.
Any operations on a synonym stream will be performed on the stream that is then the value of the dynamic variable named by the synonym stream symbol. If the value of the variable should change, or if the variable should be bound, then the stream will operate on the new value of the variable.
section make-synonym-stream [Function] , section synonym-stream-symbol [Function]
two-way-stream, stream, t
A bidirectional composite stream that receives its input from an associated input stream and sends its output to an associated output stream.
section make-two-way-stream [Function] , @xref{two-way-stream-input-stream; two-way-stream-output-stream} , two-way-stream-output-stream
input-stream-p stream => generalized-boolean
output-stream-p stream => generalized-boolean
stream---a stream.
generalized-boolean---a generalized boolean.
input-stream-p returns true if stream is an input stream; otherwise, returns false.
output-stream-p returns true if stream is an output stream; otherwise, returns false.
(input-stream-p *standard-input*) => true (input-stream-p *terminal-io*) => true (input-stream-p (make-string-output-stream)) => false (output-stream-p *standard-output*) => true (output-stream-p *terminal-io*) => true (output-stream-p (make-string-input-stream "jr")) => false
Should signal an error of type type-error if stream is not a stream.
interactive-stream-p stream => generalized-boolean
stream---a stream.
generalized-boolean---a generalized boolean.