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.
If an end of file_2 occurs and eof-error-p is false, the eof-value is returned.
(with-open-file (s "temp-bytes"
:direction :output
:element-type 'unsigned-byte)
(write-byte 101 s)) => 101
(with-open-file (s "temp-bytes" :element-type 'unsigned-byte)
(format t "~S ~S" (read-byte s) (read-byte s nil 'eof)))
|> 101 EOF
=> NIL
Modifies stream.
Should signal an error of type type-error if stream is not a stream.
Should signal an error of type error if stream is not a binary input stream.
If there are no bytes remaining in the stream and eof-error-p is true, an error of type end-of-file is signaled.
section read-char [Function] ,
section read-sequence [Function] ,
section write-byte [Function]
write-byte byte stream => byte
byte---an integer of the stream element type of stream.
stream---a binary output stream.
write-byte writes one byte, byte, to stream.
(with-open-file (s "temp-bytes"
:direction :output
:element-type 'unsigned-byte)
(write-byte 101 s)) => 101
stream is modified.
The element type of the stream.
Should signal an error of type type-error if stream is not a stream. Should signal an error of type error if stream is not a binary output stream.
Might signal an error of type type-error if byte is not an integer of the stream element type of stream.
section read-byte [Function] , section write-char [Function] ,
section write-sequence [Function]
peek-char {&optional peek-type input-stream eof-error-p
eof-value recursive-p} => char
peek-type---a character or t or nil.
input-stream---input stream designator. The default is standard input.
eof-error-p---a generalized boolean. The default is true.
eof-value---an object. The default is nil.
recursive-p---a generalized boolean. The default is false.
char---a character or the eof-value.
peek-char obtains the next character in input-stream without actually reading it, thus leaving the character to be read at a later time. It can also be used to skip over and discard intervening characters in the input-stream until a particular character is found.
If peek-type is not supplied or nil, peek-char returns the next character to be read from input-stream, without actually removing it from input-stream. The next time input is done from input-stream, the character will still be there. If peek-type is t, then peek-char skips over whitespace_2 characters, but not comments, and then performs the peeking operation on the next character. The last character examined, the one that starts an object, is not removed from input-stream. If peek-type is a character, then peek-char skips over input characters until a character that is char= to that character is found; that character is left in input-stream.
If an end of file_2 occurs and eof-error-p is false, eof-value is returned.
{ }{If recursive-p is true, this call is expected to be embedded in a higher-level call to read or a similar function used by the Lisp reader.}
When input-stream is an echo stream, characters that are only peeked at are not echoed. In the case that peek-type is not nil, the characters that are passed by peek-char are treated as if by read-char, and so are echoed unless they have been marked otherwise by unread-char.
(with-input-from-string (input-stream " 1 2 3 4 5")
(format t "~S ~S ~S"
(peek-char t input-stream)
(peek-char #\4 input-stream)
(peek-char nil input-stream)))
|> #\1 #\4 #\4
=> NIL
*readtable*, *standard-input*, *terminal-io*.
If eof-error-p is true and an end of file_2 occurs an error of type end-of-file is signaled.
If peek-type is a character, an end of file_2 occurs, and eof-error-p is true, an error of type end-of-file is signaled.
If recursive-p is true and an end of file_2 occurs, an error of type end-of-file is signaled.
read-char {&optional input-stream eof-error-p eof-value recursive-p} => char
input-stream---an input stream designator. The default is standard input.
eof-error-p---a generalized boolean. The default is true.
eof-value---an object. The default is nil.
recursive-p---a generalized boolean. The default is false.
char---a character or the eof-value.
read-char returns the next character from input-stream.
When input-stream is an echo stream, the character is echoed on input-stream the first time the character is seen. Characters that are not echoed by read-char are those that were put there by unread-char and hence are assumed to have been echoed already by a previous call to read-char.
{ }{If recursive-p is true, this call is expected to be embedded in a higher-level call to read or a similar function used by the Lisp reader.}
If an end of file_2 occurs and eof-error-p is false, eof-value is returned.
(with-input-from-string (is "0123")
(do ((c (read-char is) (read-char is nil 'the-end)))
((not (characterp c)))
(format t "~S " c)))
|> #\0 #\1 #\2 #\3
=> NIL
*standard-input*, *terminal-io*.
If an end of file_2 occurs before a character can be read, and eof-error-p is true, an error of type end-of-file is signaled.
section read-byte [Function] ,
section read-sequence [Function] ,
section write-char [Function] , @xref{read; read-preserving-whitespace}
The corresponding output function is write-char.
read-char-no-hang {&optional input-stream eof-error-p
eof-value recursive-p} => char
input-stream -- an input stream designator. The default is standard input.
eof-error-p---a generalized boolean. The default is true.
eof-value---an object. The default is nil.
recursive-p---a generalized boolean. The default is false.
char---a character or nil or the eof-value.
read-char-no-hang returns a character from input-stream if such a character is available. If no character is available, read-char-no-hang returns nil.
{ }{If recursive-p is true, this call is expected to be embedded in a higher-level call to read or a similar function used by the Lisp reader.}
If an end of file_2 occurs and eof-error-p is false, eof-value is returned.
;; This code assumes an implementation in which a newline is not
;; required to terminate input from the console.
(defun test-it ()
(unread-char (read-char))
(list (read-char-no-hang)
(read-char-no-hang)
(read-char-no-hang)))
=> TEST-IT
;; Implementation A, where a Newline is not required to terminate
;; interactive input on the console.
(test-it)
|> |>>a<<|
=> (#\a NIL NIL)
;; Implementation B, where a Newline is required to terminate
;; interactive input on the console, and where that Newline remains
;; on the input stream.
(test-it)
|> |>>a{[<--~]}<<|
=> (#\a #\Newline NIL)
*standard-input*, *terminal-io*.
If an end of file_2 occurs when eof-error-p is true, an error of type end-of-file is signaled .
section listen [Function]
read-char-no-hang is exactly like read-char, except that if it would be necessary to wait in order to get a character (as from a keyboard), nil is immediately returned without waiting.
terpri {&optional output-stream} => nil
fresh-line {&optional output-stream} => generalized-boolean
output-stream -- an output stream designator. The default is standard output.
generalized-boolean---a generalized boolean.
terpri outputs a newline to output-stream.
fresh-line is similar to terpri but outputs a newline only if the output-stream is not already at the start of a line. If for some reason this cannot be determined, then a newline is output anyway. fresh-line returns true if it outputs a newline; otherwise it returns false.
(with-output-to-string (s)
(write-string "some text" s)
(terpri s)
(terpri s)
(write-string "more text" s))
=> "some text
more text"
(with-output-to-string (s)
(write-string "some text" s)
(fresh-line s)
(fresh-line s)
(write-string "more text" s))
=> "some text
more text"
The output-stream is modified.
*standard-output*, *terminal-io*.
None.
[Reviewer Note by Barmar: What if stream is closed?]
terpri is identical in effect to
(write-char #\Newline output-stream)
unread-char character {&optional input-stream} => nil
character---a character; must be the last character that was read from input-stream.
input-stream---an input stream designator. The default is standard input.
unread-char places character back onto the front of input-stream so that it will again be the next character in input-stream.
When input-stream is an echo stream, no attempt is made to undo any echoing of the character that might already have been done on input-stream. However, characters placed on input-stream by unread-char are marked in such a way as to inhibit later riptionment-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.
If an end of file_2 occurs and eof-error-p is false, the eof-value is returned.
(with-open-file (s "temp-bytes"
:direction :output
:element-type 'unsigned-byte)
(write-byte 101 s)) => 101
(with-open-file (s "temp-bytes" :element-type 'unsigned-byte)
(format t "~S ~S" (read-byte s) (read-byte s nil 'eof)))
|> 101 EOF
=> NIL
Modifies stream.
Should signal an error of type type-error if stream is not a stream.
Should signal an error of type error if stream is not a binary input stream.
If there are no bytes remaining in the stream and eof-error-p is true, an error of type end-of-file is signaled.
section read-char [Function] ,
section read-sequence [Function] ,
section write-byte [Function]
write-byte byte stream => byte
byte---an integer of the stream element type of stream.
stream---a binary output stream.
write-byte writes one byte, byte, to stream.
(with-open-file (s "temp-bytes"
:direction :output
:element-type 'unsigned-byte)
(write-byte 101 s)) => 101
stream is modified.
The element type of the stream.
Should signal an error of type type-error if stream is not a stream. Should signal an error of type error if stream is not a binary output stream.
Might signal an error of type type-error if byte is not an integer of the stream element type of stream.
section read-byte [Function] , section write-char [Function] ,
section write-sequence [Function]
peek-char {&optional peek-type input-stream eof-error-p
eof-value recursive-p} => char
peek-type---a character or t or nil.
input-stream---input stream designator. The default is standard input.
eof-error-p---a generalized boolean. The default is true.
eof-value---an object. The default is nil.
recursive-p---a generalized boolean. The default is false.
char---a character or the eof-value.
peek-char obtains the next character in input-stream without actually reading it, thus leaving the character to be read at a later time. It can also be used to skip over and discard intervening characters in the input-stream until a particular character is found.
If peek-type is not supplied or nil, peek-char returns the next character to be read from input-stream, without actually removing it from input-stream. The next time input is done from input-stream, the character will still be there. If peek-type is t, then peek-char skips over whitespace_2 characters, but not comments, and then performs the peeking operation on the next character. The last character examined, the one that starts an object, is not removed from input-stream. If peek-type is a character, then peek-char skips over input characters until a character that is char= to that character is found; that character is left in input-stream.
If an end of file_2 occurs and eof-error-p is false, eof-value is returned.
{ }{If recursive-p is true, this call is expected to be embedded in a higher-level call to read or a similar function used by the Lisp reader.}
When input-stream is an echo stream, characters that are only peeked at are not echoed. In the case that peek-type is not nil, the characters that are passed by peek-char are treated as if by read-char, and so are echoed unless they have been marked otherwise by unread-char.
(with-input-from-string (input-stream " 1 2 3 4 5")
(format t "~S ~S ~S"
(peek-char t input-stream)
(peek-char #\4 input-stream)
(peek-char nil input-stream)))
|> #\1 #\4 #\4
=> NIL
*readtable*, *standard-input*, *terminal-io*.
If eof-error-p is true and an end of file_2 occurs an error of type end-of-file is signaled.
If peek-type is a character, an end of file_2 occurs, and eof-error-p is true, an error of type end-of-file is signaled.
If recursive-p is true and an end of file_2 occurs, an error of type end-of-file is signaled.
read-char {&optional input-stream eof-error-p eof-value recursive-p} => char
input-stream---an input stream designator. The default is standard input.
eof-error-p---a generalized boolean. The default is true.
eof-value---an object. The default is nil.
recursive-p---a generalized boolean. The default is false.
char---a character or the eof-value.
read-char returns the next character from input-stream.
When input-stream is an echo stream, the character is echoed on input-stream the first time the character is seen. Characters that are not echoed by read-char are those that were put there by unread-char and hence are assumed to have been echoed already by a previous call to read-char.
{ }{If recursive-p is true, this call is expected to be embedded in a higher-level call to read or a similar function used by the Lisp reader.}
If an end of file_2 occurs and eof-error-p is false, eof-value is returned.
(with-input-from-string (is "0123")
(do ((c (read-char is) (read-char is nil 'the-end)))
((not (characterp c)))
(format t "~S " c)))
|> #\0 #\1 #\2 #\3
=> NIL
*standard-input*, *terminal-io*.
If an end of file_2 occurs before a character can be read, and eof-error-p is true, an error of type end-of-file is signaled.
section read-byte [Function] ,
section read-sequence [Function] ,
section write-char [Function] , @xref{read; read-preserving-whitespace}
The corresponding output function is write-char.
read-char-no-hang {&optional input-stream eof-error-p
eof-value recursive-p} => char
input-stream -- an input stream designator. The default is standard input.
eof-error-p---a generalized boolean. The default is true.
eof-value---an object. The default is nil.
recursive-p---a generalized boolean. The default is false.
char---a character or nil or the eof-value.
read-char-no-hang returns a character from input-stream if such a character is available. If no character is available, read-char-no-hang returns nil.
{ }{If recursive-p is true, this call is expected to be embedded in a higher-level call to read or a similar function used by the Lisp reader.}
If an end of file_2 occurs and eof-error-p is false, eof-value is returned.
;; This code assumes an implementation in which a newline is not
;; required to terminate input from the console.
(defun test-it ()
(unread-char (read-char))
(list (read-char-no-hang)
(read-char-no-hang)
(read-char-no-hang)))
=> TEST-IT
;; Implementation A, where a Newline is not required to terminate
;; interactive input on the console.
(test-it)
|> |>>a<<|
=> (#\a NIL NIL)
;; Implementation B, where a Newline is required to terminate
;; interactive input on the console, and where that Newline remains
;; on the input stream.
(test-it)
|> |>>a{[<--~]}<<|
=> (#\a #\Newline NIL)
*standard-input*, *terminal-io*.
If an end of file_2 occurs when eof-error-p is true, an error of type end-of-file is signaled .
section listen [Function]
read-char-no-hang is exactly like read-char, except that if it would be necessary to wait in order to get a character (as from a keyboard), nil is immediately returned without waiting.
terpri {&optional output-stream} => nil
fresh-line {&optional output-stream} => generalized-boolean
output-stream -- an output stream designator. The default is standard output.
generalized-boolean---a generalized boolean.
terpri outputs a newline to output-stream.
fresh-line is similar to terpri but outputs a newline only if the output-stream is not already at the start of a line. If for some reason this cannot be determined, then a newline is output anyway. fresh-line returns true if it outputs a newline; otherwise it returns false.
(with-output-to-string (s)
(write-string "some text" s)
(terpri s)
(terpri s)
(write-string "more text" s))
=> "some text
more text"
(with-output-to-string (s)
(write-string "some text" s)
(fresh-line s)
(fresh-line s)
(write-string "more text" s))
=> "some text
more text"
The output-stream is modified.
*standard-output*, *terminal-io*.
None.
[Reviewer Note by Barmar: What if stream is closed?]
terpri is identical in effect to
(write-char #\Newline output-stream)
unread-char character {&optional input-stream} => nil
character---a character; must be the last character that was read from input-stream.
input-stream---an input stream designator. The default is standard input.
unread-char places character back onto the front of input-stream so that it will again be the next character in input-stream.
When input-stream is an echo stream, no attempt is made to undo any echoing of the character that might already have been done on input-stream. However, characters placed on input-stream by unread-char are marked in such a way as to inhibit later riptionment-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.
If an end of file_2 occurs and eof-error-p is false, the eof-value is returned.
(with-open-file (s "temp-bytes"
:direction :output
:element-type 'unsigned-byte)
(write-byte 101 s)) => 101
(with-open-file (s "temp-bytes" :element-type 'unsigned-byte)
(format t "~S ~S" (read-byte s) (read-byte s nil 'eof)))
|> 101 EOF
=> NIL
Modifies stream.
Should signal an error of type type-error if stream is not a stream.
Should signal an error of type error if stream is not a binary input stream.
If there are no bytes remaining in the stream and eof-error-p is true, an error of type end-of-file is signaled.
section read-char [Function] ,
section read-sequence [Function] ,
section write-byte [Function]
write-byte byte stream => byte
byte---an integer of the stream element type of stream.
stream---a binary output stream.
write-byte writes one byte, byte, to stream.
(with-open-file (s "temp-bytes"
:direction :output
:element-type 'unsigned-byte)
(write-byte 101 s)) => 101
stream is modified.
The element type of the stream.
Should signal an error of type type-error if stream is not a stream. Should signal an error of type error if stream is not a binary output stream.
Might signal an error of type type-error if byte is not an integer of the stream element type of stream.
section read-byte [Function] , section write-char [Function] ,
section write-sequence [Function]
peek-char {&optional peek-type input-stream eof-error-p
eof-value recursive-p} => char
peek-type---a character or t or nil.
input-stream---input stream designator. The default is standard input.
eof-error-p---a generalized boolean. The default is true.
eof-value---an object. The default is nil.
recursive-p---a generalized boolean. The default is false.
char---a character or the eof-value.
peek-char obtains the next character in input-stream without actually reading it, thus leaving the character to be read at a later time. It can also be used to skip over and discard intervening characters in the input-stream until a particular character is found.
If peek-type is not supplied or nil, peek-char returns the next character to be read from input-stream, without actually removing it from input-stream. The next time input is done from input-stream, the character will still be there. If peek-type is t, then peek-char skips over whitespace_2 characters, but not comments, and then performs the peeking operation on the next character. The last character examined, the one that starts an object, is not removed from input-stream. If peek-type is a character, then peek-char skips over input characters until a character that is char= to that character is found; that character is left in input-stream.
If an end of file_2 occurs and eof-error-p is false, eof-value is returned.
{ }{If recursive-p is true, this call is expected to be embedded in a higher-level call to read or a similar function used by the Lisp reader.}
When input-stream is an echo stream, characters that are only peeked at are not echoed. In the case that peek-type is not nil, the characters that are passed by peek-char are treated as if by read-char, and so are echoed unless they have been marked otherwise by unread-char.
(with-input-from-string (input-stream " 1 2 3 4 5")
(format t "~S ~S ~S"
(peek-char t input-stream)
(peek-char #\4 input-stream)
(peek-char nil input-stream)))
|> #\1 #\4 #\4
=> NIL
*readtable*, *standard-input*, *terminal-io*.
If eof-error-p is true and an end of file_2 occurs an error of type end-of-file is signaled.
If peek-type is a character, an end of file_2 occurs, and eof-error-p is true, an error of type end-of-file is signaled.
If recursive-p is true and an end of file_2 occurs, an error of type end-of-file is signaled.
read-char {&optional input-stream eof-error-p eof-value recursive-p} => char
input-stream---an input stream designator. The default is standard input.
eof-error-p---a generalized boolean. The default is true.
eof-value---an object. The default is nil.
recursive-p---a generalized boolean. The default is false.
char---a character or the eof-value.
read-char returns the next character from input-stream.
When input-stream is an echo stream, the character is echoed on input-stream the first time the character is seen. Characters that are not echoed by read-char are those that were put there by unread-char and hence are assumed to have been echoed already by a previous call to read-char.
{ }{If recursive-p is true, this call is expected to be embedded in a higher-level call to read or a similar function used by the Lisp reader.}
If an end of file_2 occurs and eof-error-p is false, eof-value is returned.
(with-input-from-string (is "0123")
(do ((c (read-char is) (read-char is nil 'the-end)))
((not (characterp c)))
(format t "~S " c)))
|> #\0 #\1 #\2 #\3
=> NIL
*standard-input*, *terminal-io*.
If an end of file_2 occurs before a character can be read, and eof-error-p is true, an error of type end-of-file is signaled.
section read-byte [Function] ,
section read-sequence [Function] ,
section write-char [Function] , @xref{read; read-preserving-whitespace}
The corresponding output function is write-char.
read-char-no-hang {&optional input-stream eof-error-p
eof-value recursive-p} => char
input-stream -- an input stream designator. The default is standard input.
eof-error-p---a generalized boolean. The default is true.
eof-value---an object. The default is nil.
recursive-p---a generalized boolean. The default is false.
char---a character or nil or the eof-value.
read-char-no-hang returns a character from input-stream if such a character is available. If no character is available, read-char-no-hang returns nil.
{ }{If recursive-p is true, this call is expected to be embedded in a higher-level call to read or a similar function used by the Lisp reader.}
If an end of file_2 occurs and eof-error-p is false, eof-value is returned.
;; This code assumes an implementation in which a newline is not
;; required to terminate input from the console.
(defun test-it ()
(unread-char (read-char))
(list (read-char-no-hang)
(read-char-no-hang)
(read-char-no-hang)))
=> TEST-IT
;; Implementation A, where a Newline is not required to terminate
;; interactive input on the console.
(test-it)
|> |>>a<<|
=> (#\a NIL NIL)
;; Implementation B, where a Newline is required to terminate
;; interactive input on the console, and where that Newline remains
;; on the input stream.
(test-it)
|> |>>a{[<--~]}<<|
=> (#\a #\Newline NIL)
*standard-input*, *terminal-io*.
If an end of file_2 occurs when eof-error-p is true, an error of type end-of-file is signaled .
section listen [Function]
read-char-no-hang is exactly like read-char, except that if it would be necessary to wait in order to get a character (as from a keyboard), nil is immediately returned without waiting.
terpri {&optional output-stream} => nil
fresh-line {&optional output-stream} => generalized-boolean
output-stream -- an output stream designator. The default is standard output.
generalized-boolean---a generalized boolean.
terpri outputs a newline to output-stream.
fresh-line is similar to terpri but outputs a newline only if the output-stream is not already at the start of a line. If for some reason this cannot be determined, then a newline is output anyway. fresh-line returns true if it outputs a newline; otherwise it returns false.
(with-output-to-string (s)
(write-string "some text" s)
(terpri s)
(terpri s)
(write-string "more text" s))
=> "some text
more text"
(with-output-to-string (s)
(write-string "some text" s)
(fresh-line s)
(fresh-line s)
(write-string "more text" s))
=> "some text
more text"
The output-stream is modified.
*standard-output*, *terminal-io*.
None.
[Reviewer Note by Barmar: What if stream is closed?]
terpri is identical in effect to
(write-char #\Newline output-stream)
unread-char character {&optional input-stream} => nil
character---a character; must be the last character that was read from input-stream.
input-stream---an input stream designator. The default is standard input.
unread-char places character back onto the front of input-stream so that it will again be the next character in input-stream.
When input-stream is an echo stream, no attempt is made to undo any echoing of the character that might already have been done on input-stream. However, characters placed on input-stream by unread-char are marked in such a way as to inhibit later riptionment-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.
If an end of file_2 occurs and eof-error-p is false, the eof-value is returned.
(with-open-file (s "temp-bytes"
:direction :output
:element-type 'unsigned-byte)
(write-byte 101 s)) => 101
(with-open-file (s "temp-bytes" :element-type 'unsigned-byte)
(format t "~S ~S" (read-byte s) (read-byte s nil 'eof)))
|> 101 EOF
=> NIL
Modifies stream.
Should signal an error of type type-error if stream is not a stream.
Should signal an error of type error if stream is not a binary input stream.
If there are no bytes remaining in the stream and eof-error-p is true, an error of type end-of-file is signaled.
section read-char [Function] ,
section read-sequence [Function] ,
section write-byte [Function]
write-byte byte stream => byte
byte---an integer of the stream element type of stream.
stream---a binary output stream.
write-byte writes one byte, byte, to stream.
(with-open-file (s "temp-bytes"
:direction :output
:element-type 'unsigned-byte)
(write-byte 101 s)) => 101
stream is modified.
The element type of the stream.
Should signal an error of type type-error if stream is not a stream. Should signal an error of type error if stream is not a binary output stream.
Might signal an error of type type-error if byte is not an integer of the stream element type of stream.
section read-byte [Function] , section write-char [Function] ,
section write-sequence [Function]
peek-char {&optional peek-type input-stream eof-error-p
eof-value recursive-p} => char
peek-type---a character or t or nil.
input-stream---input stream designator. The default is standard input.
eof-error-p---a generalized boolean. The default is true.
eof-value---an object. The default is nil.
recursive-p---a generalized boolean. The default is false.
char---a character or the eof-value.
peek-char obtains the next character in input-stream without actually reading it, thus leaving the character to be read at a later time. It can also be used to skip over and discard intervening characters in the input-stream until a particular character is found.
If peek-type is not supplied or nil, peek-char returns the next character to be read from input-stream, without actually removing it from input-stream. The next time input is done from input-stream, the character will still be there. If peek-type is t, then peek-char skips over whitespace_2 characters, but not comments, and then performs the peeking operation on the next character. The last character examined, the one that starts an object, is not removed from input-stream. If peek-type is a character, then peek-char skips over input characters until a character that is char= to that character is found; that character is left in input-stream.
If an end of file_2 occurs and eof-error-p is false, eof-value is returned.
{ }{If recursive-p is true, this call is expected to be embedded in a higher-level call to read or a similar function used by the Lisp reader.}
When input-stream is an echo stream, characters that are only peeked at are not echoed. In the case that peek-type is not nil, the characters that are passed by peek-char are treated as if by read-char, and so are echoed unless they have been marked otherwise by unread-char.
(with-input-from-string (input-stream " 1 2 3 4 5")
(format t "~S ~S ~S"
(peek-char t input-stream)
(peek-char #\4 input-stream)
(peek-char nil input-stream)))
|> #\1 #\4 #\4
=> NIL
*readtable*, *standard-input*, *terminal-io*.
If eof-error-p is true and an end of file_2 occurs an error of type end-of-file is signaled.
If peek-type is a character, an end of file_2 occurs, and eof-error-p is true, an error of type end-of-file is signaled.
If recursive-p is true and an end of file_2 occurs, an error of type end-of-file is signaled.
read-char {&optional input-stream eof-error-p eof-value recursive-p} => char
input-stream---an input stream designator. The default is standard input.
eof-error-p---a generalized boolean. The default is true.
eof-value---an object. The default is nil.
recursive-p---a generalized boolean. The default is false.
char---a character or the eof-value.
read-char returns the next character from input-stream.
When input-stream is an echo stream, the character is echoed on input-stream the first time the character is seen. Characters that are not echoed by read-char are those that were put there by unread-char and hence are assumed to have been echoed already by a previous call to read-char.
{ }{If recursive-p is true, this call is expected to be embedded in a higher-level call to read or a similar function used by the Lisp reader.}
If an end of file_2 occurs and eof-error-p is false, eof-value is returned.
(with-input-from-string (is "0123")
(do ((c (read-char is) (read-char is nil 'the-end)))
((not (characterp c)))
(format t "~S " c)))
|> #\0 #\1 #\2 #\3
=> NIL
*standard-input*, *terminal-io*.
If an end of file_2 occurs before a character can be read, and eof-error-p is true, an error of type end-of-file is signaled.
section read-byte [Function] ,
section read-sequence [Function] ,
section write-char [Function] , @xref{read; read-preserving-whitespace}
The corresponding output function is write-char.
read-char-no-hang {&optional input-stream eof-error-p
eof-value recursive-p} => char
input-stream -- an input stream designator. The default is standard input.
eof-error-p---a generalized boolean. The default is true.
eof-value---an object. The default is nil.
recursive-p---a generalized boolean. The default is false.
char---a character or nil or the eof-value.
read-char-no-hang returns a character from input-stream if such a character is available. If no character is available, read-char-no-hang returns nil.
{ }{If recursive-p is true, this call is expected to be embedded in a higher-level call to read or a similar function used by the Lisp reader.}
If an end of file_2 occurs and eof-error-p is false, eof-value is returned.
;; This code assumes an implementation in which a newline is not
;; required to terminate input from the console.
(defun test-it ()
(unread-char (read-char))
(list (read-char-no-hang)
(read-char-no-hang)
(read-char-no-hang)))
=> TEST-IT
;; Implementation A, where a Newline is not required to terminate
;; interactive input on the console.
(test-it)
|> |>>a<<|
=> (#\a NIL NIL)
;; Implementation B, where a Newline is required to terminate
;; interactive input on the console, and where that Newline remains
;; on the input stream.
(test-it)
|> |>>a{[<--~]}<<|
=> (#\a #\Newline NIL)
*standard-input*, *terminal-io*.
If an end of file_2 occurs when eof-error-p is true, an error of type end-of-file is signaled .
section listen [Function]
read-char-no-hang is exactly like read-char, except that if it would be necessary to wait in order to get a character (as from a keyboard), nil is immediately returned without waiting.
terpri {&optional output-stream} => nil
fresh-line {&optional output-stream} => generalized-boolean
output-stream -- an output stream designator. The default is standard output.
generalized-boolean---a generalized boolean.
terpri outputs a newline to output-stream.
fresh-line is similar to terpri but outputs a newline only if the output-stream is not already at the start of a line. If for some reason this cannot be determined, then a newline is output anyway. fresh-line returns true if it outputs a newline; otherwise it returns false.
(with-output-to-string (s)
(write-string "some text" s)
(terpri s)
(terpri s)
(write-string "more text" s))
=> "some text
more text"
(with-output-to-string (s)
(write-string "some text" s)
(fresh-line s)
(fresh-line s)
(write-string "more text" s))
=> "some text
more text"
The output-stream is modified.
*standard-output*, *terminal-io*.
None.
[Reviewer Note by Barmar: What if stream is closed?]
terpri is identical in effect to
(write-char #\Newline output-stream)
unread-char character {&optional input-stream} => nil
character---a character; must be the last character that was read from input-stream.
input-stream---an input stream designator. The default is standard input.
unread-char places character back onto the front of input-stream so that it will again be the next character in input-stream.
When input-stream is an echo stream, no attempt is made to undo any echoing of the character that might already have been done on input-stream. However, characters placed on input-stream by unread-char are marked in such a way as to inhibit later riptionment-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.
If an end of file_2 occurs and eof-error-p is false, the eof-value is returned.
(with-open-file (s "temp-bytes"
:direction :output
:element-type 'unsigned-byte)
(write-byte 101 s)) => 101
(with-open-file (s "temp-bytes" :element-type 'unsigned-byte)
(format t "~S ~S" (read-byte s) (read-byte s nil 'eof)))
|> 101 EOF
=> NIL
Modifies stream.
Should signal an error of type type-error if stream is not a stream.
Should signal an error of type error if stream is not a binary input stream.
If there are no bytes remaining in the stream and eof-error-p is true, an error of type end-of-file is signaled.
section read-char [Function] ,
section read-sequence [Function] ,
section write-byte [Function]
write-byte byte stream => byte
byte---an integer of the stream element type of stream.
stream---a binary output stream.
write-byte writes one byte, byte, to stream.
(with-open-file (s "temp-bytes"
:direction :output
:element-type 'unsigned-byte)
(write-byte 101 s)) => 101
stream is modified.
The element type of the stream.
Should signal an error of type type-error if stream is not a stream. Should signal an error of type error if stream is not a binary output stream.
Might signal an error of type type-error if byte is not an integer of the stream element type of stream.
section read-byte [Function] , section write-char [Function] ,
section write-sequence [Function]
peek-char {&optional peek-type input-stream eof-error-p
eof-value recursive-p} => char
peek-type---a character or t or nil.
input-stream---input stream designator. The default is standard input.
eof-error-p---a generalized boolean. The default is true.
eof-value---an object. The default is nil.
recursive-p---a generalized boolean. The default is false.
char---a character or the eof-value.
peek-char obtains the next character in input-stream without actually reading it, thus leaving the character to be read at a later time. It can also be used to skip over and discard intervening characters in the input-stream until a particular character is found.
If peek-type is not supplied or nil, peek-char returns the next character to be read from input-stream, without actually removing it from input-stream. The next time input is done from input-stream, the character will still be there. If peek-type is t, then peek-char skips over whitespace_2 characters, but not comments, and then performs the peeking operation on the next character. The last character examined, the one that starts an object, is not removed from input-stream. If peek-type is a character, then peek-char skips over input characters until a character that is char= to that character is found; that character is left in input-stream.
If an end of file_2 occurs and eof-error-p is false, eof-value is returned.
{ }{If recursive-p is true, this call is expected to be embedded in a higher-level call to read or a similar function used by the Lisp reader.}
When input-stream is an echo stream, characters that are only peeked at are not echoed. In the case that peek-type is not nil, the characters that are passed by peek-char are treated as if by read-char, and so are echoed unless they have been marked otherwise by unread-char.
(with-input-from-string (input-stream " 1 2 3 4 5")
(format t "~S ~S ~S"
(peek-char t input-stream)
(peek-char #\4 input-stream)
(peek-char nil input-stream)))
|> #\1 #\4 #\4
=> NIL
*readtable*, *standard-input*, *terminal-io*.
If eof-error-p is true and an end of file_2 occurs an error of type end-of-file is signaled.
If peek-type is a character, an end of file_2 occurs, and eof-error-p is true, an error of type end-of-file is signaled.
If recursive-p is true and an end of file_2 occurs, an error of type end-of-file is signaled.
read-char {&optional input-stream eof-error-p eof-value recursive-p} => char
input-stream---an input stream designator. The default is standard input.
eof-error-p---a generalized boolean. The default is true.
eof-value---an object. The default is nil.
recursive-p---a generalized boolean. The default is false.
char---a character or the eof-value.
read-char returns the next character from input-stream.
When input-stream is an echo stream, the character is echoed on input-stream the first time the character is seen. Characters that are not echoed by read-char are those that were put there by unread-char and hence are assumed to have been echoed already by a previous call to read-char.
{ }{If recursive-p is true, this call is expected to be embedded in a higher-level call to read or a similar function used by the Lisp reader.}
If an end of file_2 occurs and eof-error-p is false, eof-value is returned.
(with-input-from-string (is "0123")
(do ((c (read-char is) (read-char is nil 'the-end)))
((not (characterp c)))
(format t "~S " c)))
|> #\0 #\1 #\2 #\3
=> NIL
*standard-input*, *terminal-io*.
If an end of file_2 occurs before a character can be read, and eof-error-p is true, an error of type end-of-file is signaled.
section read-byte [Function] ,
section read-sequence [Function] ,
section write-char [Function] , @xref{read; read-preserving-whitespace}
The corresponding output function is write-char.
read-char-no-hang {&optional input-stream eof-error-p
eof-value recursive-p} => char
input-stream -- an input stream designator. The default is standard input.
eof-error-p---a generalized boolean. The default is true.
eof-value---an object. The default is nil.
recursive-p---a generalized boolean. The default is false.
char---a character or nil or the eof-value.
read-char-no-hang returns a character from input-stream if such a character is available. If no character is available, read-char-no-hang returns nil.
{ }{If recursive-p is true, this call is expected to be embedded in a higher-level call to read or a similar function used by the Lisp reader.}
If an end of file_2 occurs and eof-error-p is false, eof-value is returned.
;; This code assumes an implementation in which a newline is not
;; required to terminate input from the console.
(defun test-it ()
(unread-char (read-char))
(list (read-char-no-hang)
(read-char-no-hang)
(read-char-no-hang)))
=> TEST-IT
;; Implementation A, where a Newline is not required to terminate
;; interactive input on the console.
(test-it)
|> |>>a<<|
=> (#\a NIL NIL)
;; Implementation B, where a Newline is required to terminate
;; interactive input on the console, and where that Newline remains
;; on the input stream.
(test-it)
|> |>>a{[<--~]}<<|
=> (#\a #\Newline NIL)
*standard-input*, *terminal-io*.
If an end of file_2 occurs when eof-error-p is true, an error of type end-of-file is signaled .
section listen [Function]
read-char-no-hang is exactly like read-char, except that if it would be necessary to wait in order to get a character (as from a keyboard), nil is immediately returned without waiting.
terpri {&optional output-stream} => nil
fresh-line {&optional output-stream} => generalized-boolean
output-stream -- an output stream designator. The default is standard output.
generalized-boolean---a generalized boolean.
terpri outputs a newline to output-stream.
fresh-line is similar to terpri but outputs a newline only if the output-stream is not already at the start of a line. If for some reason this cannot be determined, then a newline is output anyway. fresh-line returns true if it outputs a newline; otherwise it returns false.
(with-output-to-string (s)
(write-string "some text" s)
(terpri s)
(terpri s)
(write-string "more text" s))
=> "some text
more text"
(with-output-to-string (s)
(write-string "some text" s)
(fresh-line s)
(fresh-line s)
(write-string "more text" s))
=> "some text
more text"
The output-stream is modified.
*standard-output*, *terminal-io*.
None.
[Reviewer Note by Barmar: What if stream is closed?]
terpri is identical in effect to
(write-char #\Newline output-stream)
unread-char character {&optional input-stream} => nil
character---a character; must be the last character that was read from input-stream.
input-stream---an input stream designator. The default is standard input.
unread-char places character back onto the front of input-stream so that it will again be the next character in input-stream.
When input-stream is an echo stream, no attempt is made to undo any echoing of the character that might already have been done on input-stream. However, characters placed on input-stream by unread-char are marked in such a way as to inhibit later riptionment-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.
If an end of file_2 occurs and eof-error-p is false, the eof-value is returned.
(with-open-file (s "temp-bytes"
:direction :output
:element-type 'unsigned-byte)
(write-byte 101 s)) => 101
(with-open-file (s "temp-bytes" :element-type 'unsigned-byte)
(format t "~S ~S" (read-byte s) (read-byte s nil 'eof)))
|> 101 EOF
=> NIL
Modifies stream.
Should signal an error of type type-error if stream is not a stream.
Should signal an error of type error if stream is not a binary input stream.
If there are no bytes remaining in the stream and eof-error-p is true, an error of type end-of-file is signaled.
section read-char [Function] ,
section read-sequence [Function] ,
section write-byte [Function]
write-byte byte stream => byte
byte---an integer of the stream element type of stream.
stream---a binary output stream.
write-byte writes one byte, byte, to stream.
(with-open-file (s "temp-bytes"
:direction :output
:element-type 'unsigned-byte)
(write-byte 101 s)) => 101
stream is modified.
The element type of the stream.
Should signal an error of type type-error if stream is not a stream. Should signal an error of type error if stream is not a binary output stream.
Might signal an error of type type-error if byte is not an integer of the stream element type of stream.
section read-byte [Function] , section write-char [Function] ,
section write-sequence [Function]
peek-char {&optional peek-type input-stream eof-error-p
eof-value recursive-p} => char
peek-type---a character or t or nil.
input-stream---input stream designator. The default is standard input.
eof-error-p---a generalized boolean. The default is true.
eof-value---an object. The default is nil.
recursive-p---a generalized boolean. The default is false.
char---a character or the eof-value.
peek-char obtains the next character in input-stream without actually reading it, thus leaving the character to be read at a later time. It can also be used to skip over and discard intervening characters in the input-stream until a particular character is found.
If peek-type is not supplied or nil, peek-char returns the next character to be read from input-stream, without actually removing it from input-stream. The next time input is done from input-stream, the character will still be there. If peek-type is t, then peek-char skips over whitespace_2 characters, but not comments, and then performs the peeking operation on the next character. The last character examined, the one that starts an object, is not removed from input-stream. If peek-type is a character, then peek-char skips over input characters until a character that is char= to that character is found; that character is left in input-stream.
If an end of file_2 occurs and eof-error-p is false, eof-value is returned.
{ }{If recursive-p is true, this call is expected to be embedded in a higher-level call to read or a similar function used by the Lisp reader.}
When input-stream is an echo stream, characters that are only peeked at are not echoed. In the case that peek-type is not nil, the characters that are passed by peek-char are treated as if by read-char, and so are echoed unless they have been marked otherwise by unread-char.
(with-input-from-string (input-stream " 1 2 3 4 5")
(format t "~S ~S ~S"
(peek-char t input-stream)
(peek-char #\4 input-stream)
(peek-char nil input-stream)))
|> #\1 #\4 #\4
=> NIL
*readtable*, *standard-input*, *terminal-io*.
If eof-error-p is true and an end of file_2 occurs an error of type end-of-file is signaled.
If peek-type is a character, an end of file_2 occurs, and eof-error-p is true, an error of type end-of-file is signaled.
If recursive-p is true and an end of file_2 occurs, an error of type end-of-file is signaled.
read-char {&optional input-stream eof-error-p eof-value recursive-p} => char
input-stream---an input stream designator. The default is standard input.
eof-error-p---a generalized boolean. The default is true.
eof-value---an object. The default is nil.
recursive-p---a generalized boolean. The default is false.
char---a character or the eof-value.
read-char returns the next character from input-stream.
When input-stream is an echo stream, the character is echoed on input-stream the first time the character is seen. Characters that are not echoed by read-char are those that were put there by unread-char and hence are assumed to have been echoed already by a previous call to read-char.
{ }{If recursive-p is true, this call is expected to be embedded in a higher-level call to read or a similar function used by the Lisp reader.}
If an end of file_2 occurs and eof-error-p is false, eof-value is returned.
(with-input-from-string (is "0123")
(do ((c (read-char is) (read-char is nil 'the-end)))
((not (characterp c)))
(format t "~S " c)))
|> #\0 #\1 #\2 #\3
=> NIL
*standard-input*, *terminal-io*.
If an end of file_2 occurs before a character can be read, and eof-error-p is true, an error of type end-of-file is signaled.
section read-byte [Function] ,
section read-sequence [Function] ,
section write-char [Function] , @xref{read; read-preserving-whitespace}
The corresponding output function is write-char.
read-char-no-hang {&optional input-stream eof-error-p
eof-value recursive-p} => char
input-stream -- an input stream designator. The default is standard input.
eof-error-p---a generalized boolean. The default is true.
eof-value---an object. The default is nil.
recursive-p---a generalized boolean. The default is false.
char---a character or nil or the eof-value.
read-char-no-hang returns a character from input-stream if such a character is available. If no character is available, read-char-no-hang returns nil.
{ }{If recursive-p is true, this call is expected to be embedded in a higher-level call to read or a similar function used by the Lisp reader.}
If an end of file_2 occurs and eof-error-p is false, eof-value is returned.
;; This code assumes an implementation in which a newline is not
;; required to terminate input from the console.
(defun test-it ()
(unread-char (read-char))
(list (read-char-no-hang)
(read-char-no-hang)
(read-char-no-hang)))
=> TEST-IT
;; Implementation A, where a Newline is not required to terminate
;; interactive input on the console.
(test-it)
|> |>>a<<|
=> (#\a NIL NIL)
;; Implementation B, where a Newline is required to terminate
;; interactive input on the console, and where that Newline remains
;; on the input stream.
(test-it)
|> |>>a{[<--~]}<<|
=> (#\a #\Newline NIL)
*standard-input*, *terminal-io*.
If an end of file_2 occurs when eof-error-p is true, an error of type end-of-file is signaled .
section listen [Function]
read-char-no-hang is exactly like read-char, except that if it would be necessary to wait in order to get a character (as from a keyboard), nil is immediately returned without waiting.
terpri {&optional output-stream} => nil
fresh-line {&optional output-stream} => generalized-boolean
output-stream -- an output stream designator. The default is standard output.
generalized-boolean---a generalized boolean.
terpri outputs a newline to output-stream.
fresh-line is similar to terpri but outputs a newline only if the output-stream is not already at the start of a line. If for some reason this cannot be determined, then a newline is output anyway. fresh-line returns true if it outputs a newline; otherwise it returns false.
(with-output-to-string (s)
(write-string "some text" s)
(terpri s)
(terpri s)
(write-string "more text" s))
=> "some text
more text"
(with-output-to-string (s)
(write-string "some text" s)
(fresh-line s)
(fresh-line s)
(write-string "more text" s))
=> "some text
more text"
The output-stream is modified.
*standard-output*, *terminal-io*.
None.
[Reviewer Note by Barmar: What if stream is closed?]
terpri is identi