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 re-echo by read-char.
It is an error to invoke unread-char twice consecutively on the same stream without an intervening call to read-char (or some other input operation which implicitly reads characters) on that stream.
Invoking peek-char or read-char commits all previous characters. The consequences of invoking unread-char on any character preceding that which is returned by peek-char (including those passed over by peek-char that has a non-nil peek-type) are unspecified. In particular, the consequences of invoking unread-char after peek-char are unspecified.
(with-input-from-string (is "0123")
(dotimes (i 6)
(let ((c (read-char is)))
(if (evenp i) (format t "~&~S ~S~
|> 0 #\0
|> 2 #\1
|> 4 #\2
=> NIL
*standard-input*, *terminal-io*.
section peek-char [Function] , section read-char [Function] , section Stream Concepts
unread-char is intended to be an efficient mechanism for allowing the Lisp reader and other parsers to perform one-character lookahead in input-stream.
write-char character {&optional output-stream} => character
character---a character.
output-stream -- an output stream designator. The default is standard output.
write-char outputs character to output-stream.
(write-char #\a) |> a => #\a (with-output-to-string (s) (write-char #\a s) (write-char #\Space s) (write-char #\b s)) => "a b"
The output-stream is modified.
*standard-output*, *terminal-io*.
section read-char [Function] , section write-byte [Function] ,
section write-sequence [Function]
read-line {&optional input-stream eof-error-p eof-value recursive-p}
=> line, missing-newline-p
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.
line---a string or the eof-value.
missing-newline-p---a generalized boolean.
Reads from input-stream a line of text that is terminated by a newline or end of file.
{ }{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.}
The primary value, line, is the line that is read, represented as a string (without the trailing newline, if any). If eof-error-p is false and the end of file for input-stream is reached before any characters are read, eof-value is returned as the line.
The secondary value, missing-newline-p, is a generalized boolean that is false if the line was terminated by a newline, or true if the line was terminated by the end of file for input-stream (or if the line is the eof-value).
(setq a "line 1 line2") => "line 1 line2" (read-line (setq input-stream (make-string-input-stream a))) => "line 1", false (read-line input-stream) => "line2", true (read-line input-stream nil nil) => NIL, true
*standard-input*, *terminal-io*.
If an end of file_2 occurs before any characters are read in the line, an error is signaled if eof-error-p is true.
@xref{read; read-preserving-whitespace}
The corresponding output function is write-line.
write-string string {&optional output-stream {&key} start end} => string
write-line string {&optional output-stream {&key} start end} => string
string---a string.
output-stream -- an output stream designator. The default is standard output.
start, end---bounding index designators of string. The defaults for start and end are 0 and nil, respectively.
write-string writes the characters of the subsequence of string bounded by start and end to output-stream. write-line does the same thing, but then outputs a newline afterwards.
(prog1 (write-string "books" nil :end 4) (write-string "worms"))
|> bookworms
=> "books"
(progn (write-char #\*)
(write-line "test12" *standard-output* :end 5)
(write-line "*test2")
(write-char #\*)
nil)
|> *test1
|> *test2
|> *
=> NIL
*standard-output*, *terminal-io*.
section read-line [Function] , section write-char [Function]
write-line and write-string return string, not the substring bounded by start and end.
(write-string string)
== (dotimes (i (length string)
(write-char (char string i)))
(write-line string)
== (prog1 (write-string string) (terpri))
read-sequence sequence stream {&key start end} => position
sequence---a sequence.
stream---an input stream.
start, end---bounding index designators of sequence. The defaults for start and end are 0 and nil, respectively.
position---an integer greater than or equal to zero, and less than or equal to the length of the sequence.
Destructively modifies sequence by replacing the elements of sequence bounded by start and end with elements read from stream.
Sequence is destructively modified by copying successive elements into it from stream. If the end of file for stream is reached before copying all elements of the subsequence, then the extra elements near the end of sequence are not updated.
Position is the index of the first element of sequence that was not updated, which might be less than end because the end of file was reached.
(defvar *data* (make-array 15 :initial-element nil)) (values (read-sequence *data* (make-string-input-stream "test string")) *data*) => 11, #(#\t #\e #\s #\t #\Space #\s #\t #\r #\i #\n #\g NIL NIL NIL NIL)
Modifies stream and sequence.
Should be prepared to signal an error of type type-error if sequence is not a proper sequence. Should signal an error of type type-error if start is not a non-negative integer. Should signal an error of type type-error if end is not a non-negative integer or nil.
Might signal an error of type type-error if an element read from the stream is not a member of the element type of the sequence.
section Compiler Terminology, section write-sequence [Function] , section read-line [Function]
read-sequence is identical in effect to iterating over the indicated subsequence and reading one element at a time from stream and storing it into sequence, but may be more efficient than the equivalent loop. An efficient implementation is more likely to exist for the case where the sequence is a vector with the same element type as the stream.
write-sequence sequence stream {&key start end} => sequence
sequence---a sequence.
stream---an output stream.
start, end---bounding index designators of sequence. The defaults for start and end are 0 and nil, respectively.
write-sequence writes the elements of the subsequence of sequence bounded by start and end to stream.
(write-sequence "bookworms" *standard-output* :end 4) |> book => "bookworms"
Modifies stream.
Should be prepared to signal an error of type type-error if sequence is not a proper sequence. Should signal an error of type type-error if start is not a non-negative integer. Should signal an error of type type-error if end is not a non-negative integer or nil.
Might signal an error of type type-error if an element of the bounded sequence is not a member of the stream element type of the stream.
section Compiler Terminology, section read-sequence [Function] , @xref{write-string; write-line} , write-line
write-sequence is identical in effect to iterating over the indicated subsequence and writing one element at a time to stream, but may be more efficient than the equivalent loop. An efficient implementation is more likely to exist for the case where the sequence is a vector with the same element type as the stream.
file-length stream => length
stream---a stream associated with a file.
length---a non-negative integer or nil.
file-length returns the length of stream, or nil if the length cannot be determined.
For a binary file, the length is measured in units of the element type of the stream.
(with-open-file (s "decimal-digits.text"
:direction :output :if-exists :error)
(princ "0123456789" s)
(truename s))
=> #P"A:>Joe>decimal-digits.text.1"
(with-open-file (s "decimal-digits.text")
(file-length s))
=> 10
Should signal an error of type type-error if stream is not a stream associated with a file.
section open [Function]
file-position stream => position
file-position stream position-spec => success-p
stream---a stream.
position-spec---a file position designator.
position---a file position or nil.
success-p---a generalized boolean.
Returns or changes the current position within a stream.
When position-spec is not supplied, file-position returns the current file position in the stream, or nil if this cannot be determined.
When position-spec is supplied, the file position in stream is set to that file position (if possible). file-position returns true if the repositioning is performed successfully, or false if it is not.
An integer returned by file-position of one argument should be acceptable as position-spec for use with the same file.
For a character file, performing a single read-char or write-char operation may cause the file position to be increased by more than 1 because of character-set translations (such as translating between the Common Lisp #\Newline character and an external ASCII carriage-return/line-feed sequence) and other aspects of the implementation. For a binary file, every read-byte or write-byte operation increases the file position by 1.
(defun tester ()
(let ((noticed '()) file-written)
(flet ((notice (x) (push x noticed) x))
(with-open-file (s "test.bin"
:element-type '(unsigned-byte 8)
:direction :output
:if-exists :error)
(notice (file-position s)) ;1
(write-byte 5 s)
(write-byte 6 s)
(let ((p (file-position s)))
(notice p) ;2
(notice (when p (file-position s (1- p))))) ;3
(write-byte 7 s)
(notice (file-position s)) ;4
(setq file-written (truename s)))
(with-open-file (s file-written
:element-type '(unsigned-byte 8)
:direction :input)
(notice (file-position s)) ;5
(let ((length (file-length s)))
(notice length) ;6
(when length
(dotimes (i length)
(notice (read-byte s)))))) ;7,...
(nreverse noticed))))
=> tester
(tester)
=> (0 2 T 2 0 2 5 7)
OR=> (0 2 NIL 3 0 3 5 6 7)
OR=> (NIL NIL NIL NIL NIL NIL)
When the position-spec argument is supplied, the file position in the stream might be moved.
The value returned by file-position increases monotonically as input or output operations are performed.
If position-spec is supplied, but is too large or otherwise inappropriate, an error is signaled.
section file-length [Function] , section file-string-length [Function] , section open [Function]
Implementations that have character files represented as a sequence of records of bounded size might choose to encode the file position as, for example, <<record-number>>*<<max-record-size>>+<<character-within-record>>. This is a valid encoding because it increases monotonically as each character is read or written, though not necessarily by 1 at each step. An integer might then be considered "inappropriate" as position-spec to file-position if, when decoded into record number and character number, it turned out that the supplied record was too short for the specified character number.
file-string-length stream object => length
stream---an output character file stream.
object---a string or a character.
length---a non-negative integer, or nil.
file-string-length returns the difference between what (file-position stream) would be after writing object and its current value, or nil if this cannot be determined.
The returned value corresponds to the current state of stream at the time of the call and might not be the same if it is called again when the state of the stream has changed.
open filespec {&key direction element-type
if-exists if-does-not-exist
external-format}
=> stream
filespec---a pathname designator.
direction---one of :input, :output, :io, or :probe. The default is :input.
element-type---a type specifier for recognizable subtype of character; or a type specifier for a finite recognizable subtype of integer; or one of the symbols signed-byte, unsigned-byte, or :default. The default is character.
if-exists---one of :error, :new-version, :rename, :rename-and-delete, :overwrite, :append, :supersede, or nil. The default is :new-version if the version component of filespec is :newest, or :error otherwise.
if-does-not-exist---one of :error, :create, or nil. The default is :error if direction is :input or if-exists is :overwrite or :append; :create if direction is :output or :io, and if-exists is neither :overwrite nor :append; or nil when direction is :probe.
external-format---an external file format designator. The default is :default.
stream---a file stream or nil.
open creates, opens, and returns a file stream that is connected to the file specified by filespec. Filespec is the name of the file to be opened. If the filespec designator is a stream, that stream is not closed first or otherwise affected.
The keyword arguments to open specify the characteristics of the file stream that is returned, and how to handle errors.
If direction is :input or :probe, or if if-exists is not :new-version and the version component of the filespec is :newest, then the file opened is that file already existing in the file system that has a version greater than that of any other file in the file system whose other pathname components are the same as those of filespec.
An implementation is required to recognize all of the open keyword options and to do something reasonable in the context of the host operating system. For example, if a file system does not support distinct file versions and does not distinguish the notions of deletion and expunging, :new-version might be treated the same as :rename or :supersede, and :rename-and-delete might be treated the same as :supersede.
When a file is opened, a file stream is constructed to serve as the file system's ambassador to the Lisp environment; operations on the file stream are reflected by operations on the file in the file system.
A file can be deleted, renamed, or destructively modified by open.
For information about opening relative pathnames, see section Merging Pathnames.
(open filespec :direction :probe) => #<Closed Probe File Stream...>
(setq q (merge-pathnames (user-homedir-pathname) "test"))
=> #<PATHNAME :HOST NIL :DEVICE device-name :DIRECTORY directory-name
:NAME "test" :TYPE NIL :VERSION :NEWEST>
(open filespec :if-does-not-exist :create) => #<Input File Stream...>
(setq s (open filespec :direction :probe)) => #<Closed Probe File Stream...>
(truename s) => #<PATHNAME :HOST NIL :DEVICE device-name :DIRECTORY
directory-name :NAME filespec :TYPE extension :VERSION 1>
(open s :direction :output :if-exists nil) => NIL
The nature and state of the host computer's file system.
If if-exists is :error, (subject to the constraints on the meaning of if-exists listed above), an error of type file-error is signaled.
If if-does-not-exist is :error (subject to the constraints on the meaning of if-does-not-exist listed above), an error of type file-error is signaled.
If it is impossible for an implementation to handle some option in a manner close to what is specified here, an error of type error might be signaled.
An error of type file-error is signaled if (wild-pathname-p filespec) returns true.
An error of type error is signaled if the external-format is not understood by the implementation.
The various file systems in existence today have widely differing capabilities, and some aspects of the file system are beyond the scope of this specification to define. A given implementation might not be able to support all of these options in exactly the manner stated. An implementation is required to recognize all of these option keywords and to try to do something "reasonable" in the context of the host file system. Where necessary to accomodate the file system, an implementation deviate slightly from the semantics specified here without being disqualified for consideration as a conforming implementation. If it is utterly impossible for an implementation to handle some option in a manner similar to what is specified here, it may simply signal an error.
With regard to the :element-type option, if a type is requested that is not supported by the file system, a substitution of types such as that which goes on in upgrading is permissible. As a minimum requirement, it should be the case that opening an output stream to a file in a given element type and later opening an input stream to the same file in the same element type should work compatibly.
section with-open-file [macro] , section close [Function] , pathname, logical-pathname,
section Merging Pathnames,
section Pathnames as Filenames
open does not automatically close the file when an abnormal exit occurs.
When element-type is a subtype of character, read-char and/or write-char can be used on the resulting file stream.
When element-type is a subtype of integer, read-byte and/or write-byte can be used on the resulting file stream.
When element-type is :default, the type can be determined by using stream-element-type.
stream-external-format stream => format
stream---a file stream.
format---an external file format.
Returns an external file format designator for the stream.
(with-open-file (stream "test" :direction :output) (stream-external-format stream)) => :DEFAULT OR=> :ISO8859/1-1987 OR=> (:ASCII :SAIL) OR=> ACME::PROPRIETARY-FILE-FORMAT-17 OR=> #<FILE-FORMAT :ISO646-1983 2343673>
the :external-format argument to the function section open [Function] and the section with-open-file [macro] macro.
The format returned is not necessarily meaningful to other implementations.
with-open-file (stream filespec {options}{*)
{declaration}{*}
{form}{*}}
=> results
stream -- a variable.
filespec---a pathname designator.
options -- forms; evaluated.
declaration---a declare expression; not evaluated.
forms---an implicit progn.
results---the values returned by the forms.
with-open-file uses open to create a file stream
to file named by filespec. Filespec is the name of the file to be opened. Options are used as keyword arguments to open.
The stream object to which the stream variable is bound has dynamic extent; its extent ends when the form is exited.
with-open-file evaluates the forms as an implicit progn with stream bound to
the value returned by open.
When control leaves the body, either normally or abnormally (such as by use of throw), the file is automatically closed. If a new output file is being written, and control leaves abnormally, the file is aborted and the file system is left, so far as possible, as if the file had never been opened.
It is possible by the use of :if-exists nil or :if-does-not-exist nil for stream to be bound to nil.
Users of :if-does-not-exist nil should check for a valid stream.
The consequences are undefined if an attempt is made to assign the stream variable. The compiler may choose to issue a warning if such an attempt is detected.
(setq p (merge-pathnames "test"))
=> #<PATHNAME :HOST NIL :DEVICE device-name :DIRECTORY directory-name
:NAME "test" :TYPE NIL :VERSION :NEWEST>
(with-open-file (s p :direction :output :if-exists :supersede)
(format s "Here are a couple~
(with-open-file (s p)
(do ((l (read-line s) (read-line s nil 'eof)))
((eq l 'eof) "Reached end of file.")
(format t "~&*** ~A~
|> *** Here are a couple
|> *** of test data lines
=> "Reached end of file."
;; Normally one would not do this intentionally because it is ;; not perspicuous, but beware when using :IF-DOES-NOT-EXIST NIL ;; that this doesn't happen to you accidentally... (with-open-file (foo "no-such-file" :if-does-not-exist nil) (read foo)) |> |>>hello?<<| => HELLO? ;This value was read from the terminal, not a file! ;; Here's another bug to avoid... (with-open-file (foo "no-such-file" :direction :output :if-does-not-exist nil) (format foo "Hello")) => "Hello" ;FORMAT got an argument of NIL!
Creates a stream to the file named by filename (upon entry), and closes the stream (upon exit). In some implementations, the file might be locked in some way while it is open. If the stream is an output stream, a file might be created.
The host computer's file system.
See the function open.
section open [Function] , section close [Function] , pathname, logical-pathname,
section Pathnames as Filenames
close stream {&key abort} => result
stream---a stream (either open or closed).
abort---a generalized boolean. The default is false.
result---t if the stream was open at the time it was received as an argument, or implementation-dependent otherwise.
close closes stream. Closing a stream means that it may no longer be used in input or output operations. The act of closing a file stream ends the association between the stream and its associated file; the transaction with the file system is terminated, and input/output may no longer be performed on the stream.
If abort is true, an attempt is made to clean up any side effects of having created stream. If stream performs output to a file that was created when the stream was created, the file is deleted and any previously existing file is not superseded.
It is permissible to close an already closed stream, but in that case the result is implementation-dependent.
After stream is closed, it is still possible to perform the following query operations upon it:
streamp, pathname, truename, merge-pathnames, pathname-host, pathname-device, pathname-directory,pathname-name, pathname-type, pathname-version, namestring, file-namestring, directory-namestring, host-namestring, enough-namestring, open, probe-file, and directory.
The effect of close on a constructed stream is to close the argument stream only. There is no effect on the constituents of composite streams.
For a stream created with make-string-output-stream, the result of get-output-stream-string is unspecified after close.
(setq s (make-broadcast-stream)) => #<BROADCAST-STREAM> (close s) => T (output-stream-p s) => true
The stream is closed (if necessary). If abort is true and the stream is an output file stream, its associated file might be deleted.
section open [Function]
with-open-stream (var stream)
{declaration}{*
{form}{*}}
=> {result}{*}
var---a variable name.
stream---a form; evaluated to produce a stream.
declaration---a declare expression; not evaluated.
forms---an implicit progn.
results---the values returned by the forms.
with-open-stream performs a series of operations on stream, returns a value, and then closes the stream.
Var is bound to the value of stream, and then forms are executed as an implicit progn. stream is automatically closed on exit from with-open-stream, no matter whether the exit is normal or abnormal.
The stream has dynamic extent; its extent ends when the form is exited.
The consequences are undefined if an attempt is made to assign the the variable var with the forms.
(with-open-stream (s (make-string-input-stream "1 2 3 4"))
(+ (read s) (read s) (read s))) => 6
The stream is closed (upon exit).
section close [Function]
listen {&optional input-stream} => generalized-boolean
input-stream---an input stream designator. The default is standard input.
generalized-boolean---a generalized boolean.
Returns true if there is a character immediately available from input-stream; otherwise, returns false. On a non-interactive input-stream, listen returns true except when at end of file_1. If an end of file is encountered, listen returns false. listen is intended to be used when input-stream obtains characters from an interactive device such as a keyboard.
(progn (unread-char (read-char)) (list (listen) (read-char))) |> |>>1<<| => (T #\1) (progn (clear-input) (listen)) => NIL ;Unless you're a very fast typist!
*standard-input*
section interactive-stream-p [Function] , section read-char-no-hang [Function]
clear-input {&optional input-stream} => nil
input-stream---an input stream designator. The default is standard input.
Clears any available input from input-stream.
If clear-input does not make sense for input-stream, then clear-input does nothing.
;; The exact I/O behavior of this example might vary from implementation
;; to implementation depending on the kind of interactive buffering that
;; occurs. (The call to SLEEP here is intended to help even out the
;; differences in implementations which do not do line-at-a-time buffering.)
(defun read-sleepily (&optional (clear-p nil) (zzz 0))
(list (progn (print '>) (read))
;; Note that input typed within the first ZZZ seconds
;; will be discarded.
(progn (print '>)
(if zzz (sleep zzz))
(print '>>)
(if clear-p (clear-input))
(read))))
(read-sleepily)
|> > |>>10<<|
|> >
|> >> |>>20<<|
=> (10 20)
(read-sleepily t)
|> > |>>10<<|
|> >
|> >> |>>20<<|
=> (10 20)
(read-sleepily t 10)
|> > |>>10<<|
|> > |>>20<<| ; Some implementations won't echo typeahead here.
|> >> |>>30<<|
=> (10 30)
The input-stream is modified.
*standard-input*
Should signal an error of type type-error if input-stream is not a stream designator.
clear-output
finish-output {&optional output-stream} => nil
force-output {&optional output-stream} => nil
clear-output {&optional output-stream} => nil
output-stream---an output stream designator. The default is standard output.
finish-output, force-output, and clear-output exercise control over the internal handling of buffered stream output.
finish-output attempts to ensure that any buffered output sent to output-stream has reached its destination, and then returns.
force-output initiates the emptying of any internal buffers but does not wait for completion or acknowledgment to return.
clear-output attempts to abort any outstanding output operation in progress in order to allow as little output as possible to continue to the destination.
If any of these operations does not make sense for output-stream, then it does nothing. The precise actions of these functions are implementation-dependent.
;; Implementation A (progn (princ "am i seen?") (clear-output)) => NIL ;; Implementation B (progn (princ "am i seen?") (clear-output)) |> am i seen? => NIL
*standard-output*
Should signal an error of type type-error if output-stream is not a stream designator.
section clear-input [Function]
y-or-n-p {&optional control {&rest} arguments} => generalized-boolean
yes-or-no-p {&optional control {&rest} arguments} => generalized-boolean
control---a format control.
arguments---format arguments for control.
generalized-boolean---a generalized boolean.
These functions ask a question and parse a response from the user. They return true if the answer is affirmative, or false if the answer is negative.
y-or-n-p is for asking the user a question whose answer is either "yes" or "no." It is intended that the reply require the user to answer a yes-or-no question with a single character. yes-or-no-p is also for asking the user a question whose answer is either "Yes" or "No." It is intended that the reply require the user to take more action than just a single keystroke, such as typing the full word yes or no followed by a newline.
y-or-n-p types out a message (if supplied), reads an answer in some implementation-dependent manner (intended to be short and simple, such as reading a single character such as Y or N). yes-or-no-p types out a message (if supplied), attracts the user's attention (for example, by ringing the terminal's bell), and reads an answer in some implementation-dependent manner (intended to be multiple characters, such as YES or NO).
If format-control is supplied and not nil, then a fresh-line operation is performed; then a message is printed as if format-control and arguments were given to format. In any case, yes-or-no-p and y-or-n-p will provide a prompt such as "(Y or N)" or "(Yes or No)" if appropriate.
All input and output are performed using query I/O.
(y-or-n-p "(t or nil) given by") |> (t or nil) given by (Y or N) |>>Y<<| => true (yes-or-no-p "a ~S message" 'frightening) |> a FRIGHTENING message (Yes or No) |>>no<<| => false (y-or-n-p "Produce listing file?") |> Produce listing file? |> Please respond with Y or N. |>>n<<| => false
Output to and input from query I/O will occur.
*query-io*.
section format [Function]
yes-or-no-p and yes-or-no-p do not add question marks to the end of the prompt string, so any desired question mark or other punctuation should be explicitly included in the text query.
make-synonym-stream symbol => synonym-stream
symbol---a symbol that names a dynamic variable.
synonym-stream---a synonym stream.
Returns a synonym stream whose synonym stream symbol is symbol.
(setq a-stream (make-string-input-stream "a-stream")
b-stream (make-string-input-stream "b-stream"))
=> #<String Input Stream>
(setq s-stream (make-synonym-stream 'c-stream))
=> #<SYNONYM-STREAM for C-STREAM>
(setq c-stream a-stream)
=> #<String Input Stream>
(read s-stream) => A-STREAM
(setq c-stream b-stream)
=> #<String Input Stream>
(read s-stream) => B-STREAM
Should signal type-error if its argument is not a symbol.
section Stream Concepts
synonym-stream-symbol synonym-stream => symbol
synonym-stream---a synonym stream.
symbol---a symbol.
Returns the symbol whose symbol-value the synonym-stream is using.
section make-synonym-stream [Function]
broadcast-stream-streams broadcast-stream => streams
broadcast-stream---a broadcast stream.
streams---a list of streams.
Returns a list of output streams that constitute all the streams to which the broadcast-stream is broadcasting.
make-broadcast-stream {&rest streams} => broadcast-stream
stream---an output stream.
broadcast-stream---a broadcast stream.
Returns a broadcast stream.
(setq a-stream (make-string-output-stream)
b-stream (make-string-output-stream)) => #<String Output Stream>
(format (make-broadcast-stream a-stream b-stream)
"this will go to both streams") => NIL
(get-output-stream-string a-stream) => "this will go to both streams"
(get-output-stream-string b-stream) => "this will go to both streams"
Should signal an error of type type-error if any stream is not an output stream.
section broadcast-stream-streams [Function]
make-two-way-stream input-stream output-stream => two-way-stream
input-stream---a stream.
output-stream---a stream.
two-way-stream---a two-way stream.
Returns a two-way stream that gets its input from input-stream and sends its output to output-stream.
(with-output-to-string (out)
(with-input-from-string (in "input...")
(let ((two (make-two-way-stream in out)))
(format two "output...")
(setq what-is-read (read two))))) => "output..."
what-is-read => INPUT...
Should signal an error of type type-error if input-stream is not an input stream. Should signal an error of type type-error if output-stream is not an output stream.
[Function]
two-way-stream-input-stream two-way-stream => input-stream
two-way-stream-output-stream two-way-stream => output-stream
two-way-stream---a two-way stream.
input-stream---an input stream.
output-stream---an output stream.
two-way-stream-input-stream returns the stream from which two-way-stream receives input.
two-way-stream-output-stream returns the stream to which two-way-stream sends output.
echo-stream-input-stream echo-stream => input-stream
echo-stream-output-stream echo-stream => output-stream
echo-stream---an echo stream.
input-stream---an input stream.
output-stream---an output stream.
echo-stream-input-stream returns the input stream from which echo-stream receives input.
echo-stream-output-stream returns the output stream to which echo-stream sends output.
make-echo-stream input-stream output-stream => echo-stream
input-stream---an input stream.
output-stream---an output stream.
echo-stream---an echo stream.
Creates and returns an echo stream that takes input from input-stream and sends output to output-stream.
(let ((out (make-string-output-stream)))
(with-open-stream
(s (make-echo-stream
(make-string-input-stream "this-is-read-and-echoed")
out))
(read s)
(format s " * this-is-direct-output")
(get-output-stream-string out)))
=> "this-is-read-and-echoed * this-is-direct-output"
@xref{echo-stream-input-stream; echo-stream-output-stream} , echo-stream-output-stream, section make-two-way-stream [Function]
concatenated-stream-streams concatenated-stream => streams
concatenated-stream -- a concatenated stream.
streams---a list of input streams.
Returns a list of input streams that constitute the ordered set of streams the concatenated-stream still has to read from, starting with the current one it is reading from. The list may be empty if no more streams remain to be read.
The consequences are undefined if the list structure of the streams is ever modified.
make-concatenated-stream {&rest input-streams} => concatenated-stream
input-stream---an input stream.
concatenated-stream---a concatenated stream.
Returns a concatenated stream that has the indicated input-streams initially associated with it.
(read (make-concatenated-stream
(make-string-input-stream "1")
(make-string-input-stream "2"))) => 12
Should signal type-error if any argument is not an input stream.
section concatenated-stream-streams [Function]
get-output-stream-string string-output-stream => string
string-output-stream---a stream.
string---a string.
Returns a string containing, in order, all the characters that have been output to string-output-stream. This operation clears any characters on string-output-stream, so the string contains only those characters which have been output since the last call to get-output-stream-string or since the creation of the string-output-stream, whichever occurred most recently.
(setq a-stream (make-string-output-stream)
a-string "abcdefghijklm") => "abcdefghijklm"
(write-string a-string a-stream) => "abcdefghijklm"
(get-output-stream-string a-stream) => "abcdefghijklm"
(get-output-stream-string a-stream) => ""
The string-output-stream is cleared.
The consequences are undefined if stream-output-string is closed.
The consequences are undefined if string-output-stream is a stream that was not produced by make-string-output-stream.
The consequences are undefined if string-output-stream was created implicitly by with-output-to-string or format.
section make-string-output-stream [Function]
make-string-input-stream string {&optional start end} => string-stream
string---a string.
start, end---bounding index designators of string. The defaults for start and end are 0 and nil, respectively.
string-stream---an input string stream.
Returns an input string stream. This stream will supply, in order, the characters in the substring of string bounded by start and end. After the last character has been supplied, the string stream will then be at end of file.
(let ((string-stream (make-string-input-stream "1 one ")))
(list (read string-stream nil nil)
(read string-stream nil nil)
(read string-stream nil nil)))
=> (1 ONE NIL)
(read (make-string-input-stream "prefixtargetsuffix" 6 12)) => TARGET
section with-input-from-string [Macro]
make-string-output-stream {&key element-type} => string-stream
element-type---a type specifier. The default is character.
string-stream---an output string stream.
Returns
an output string stream that accepts characters and makes available (via get-output-stream-string) a string that contains the characters that were actually output.
The element-type names the type of the elements of the string; a string is constructed of the most specialized type that can accommodate elements of that element-type.
(let ((s (make-string-output-stream))) (write-string "testing... " s) (prin1 1234 s) (get-output-stream-string s)) => "testing... 1234"
None..
section get-output-stream-string [Function] , section with-output-to-string [Macro]
with-input-from-string (var string {&key index start end)
{declaration}{*}
{form}{*}}
=> {result}{*}
var---a variable name.
string---a form; evaluated to produce a string.
index---a place.
start, end---bounding index designators of string. The defaults for start and end are 0 and nil, respectively.
declaration---a declare expression; not evaluated.
forms---an implicit progn.
result---the values returned by the forms.
Creates an
input string stream,
provides an opportunity to perform operations on the stream (returning zero or more values), and then closes the string stream.
String is evaluated first, and var is bound to a character input string stream that supplies characters from the subsequence of the resulting string bounded by start and end. The body is executed as an implicit progn.
The input string stream is automatically closed on exit from with-input-from-string, no matter whether the exit is normal or abnormal.
The input string stream to which the variable var is bound has dynamic extent; its extent ends when the form is exited.
The index is a pointer within the string to be advanced. If with-input-from-string is exited normally, then index will have as its value the index into the string indicating the first character not read which is (length string) if all characters were used. The place specified by index is not updated as reading progresses, but only at the end of the operation.
start and index may both specify the same variable, which is a pointer within the string to be advanced, perhaps repeatedly by some containing loop.
The consequences are undefined if an attempt is made to assign the variable var.
(with-input-from-string (s "XXX1 2 3 4xxx"
:index ind
:start 3 :end 10)
(+ (read s) (read s) (read s))) => 6
ind => 9
(with-input-from-string (s "Animal Crackers" :index j :start 6)
(read s)) => CRACKERS
The variable j is set to 15.
The value of the place named by index, if any, is modified.
section make-string-input-stream [Function] ,
section Traversal Rules and Side Effects
with-output-to-string (var {&optional string-form {&key} element-type)
{declaration}{*}
{form}{*}}
=> {result}{*}
var---a variable name.
string-form---a form or nil; if non-nil, evaluated to produce string.
string---a string that has a fill pointer.
element-type---a type specifier; evaluated.
The default is character.
declaration---a declare expression; not evaluated.
forms---an implicit progn.
results---If a string-form is not supplied or nil, a string; otherwise, the values returned by the forms.
with-output-to-string creates a
character output stream, performs a series of operations that may send results to this stream, and then closes the stream.
The element-type names the type of the elements of the stream; a stream is constructed of the most specialized type that can accommodate elements of the given type.
The body is executed as an implicit progn with var bound to an output string stream. All output to that string stream is saved in a string.
If string is supplied, element-type is ignored, and the output is incrementally appended to string as if by use of vector-push-extend.
The output stream is automatically closed on exit from with-output-from-string, no matter whether the exit is normal or abnormal.
The output string stream to which the variable var is bound has dynamic extent; its extent ends when the form is exited.
If no string is provided, then with-output-from-string
produces a stream that accepts characters and returns a string of the indicated element-type.
If string is provided, with-output-to-string returns the results of evaluating the last form.
The consequences are undefined if an attempt is made to assign the variable var.
(setq fstr (make-array '(0) :element-type 'base-char
:fill-pointer 0 :adjustable t)) => ""
(with-output-to-string (s fstr)
(format s "here's some output")
(input-stream-p s)) => false
fstr => "here's some output"
The string is modified.
The consequences are undefined if destructive modifications are performed directly on the string during the dynamic extent of the call.
section make-string-output-stream [Function] , vector-push-extend,
section Traversal Rules and Side Effects
[Variable]
For *standard-input*: an input stream
For *error-output*, *standard-output*, and *trace-output*: an output stream.
For *debug-io*, *query-io*: a bidirectional stream.
implementation-dependent, but it must be an open stream that is not a generalized synonym stream to an I/O customization variables but that might be a generalized synonym stream to the value of some I/O customization variable. The initial value might also be a generalized synonym stream to either the symbol *terminal-io* or to the stream that is its value.
These variables are collectively called the standardized I/O customization variables. They can be bound or assigned in order to change the default destinations for input and/or output used by various standardized operators and facilities.
The value of *debug-io*, called debug I/O, is a stream to be used for interactive debugging purposes.
The value of *error-output*, called error output, is a stream to which warnings and non-interactive error messages should be sent.
The value of *query-io*, called query I/O, is a bidirectional stream to be used when asking questions of the user. The question should be output to this stream, and the answer read from it.
The value of *standard-input*, called standard input, is a stream that is used by many operators as a default source of input when no specific input stream is explicitly supplied.
The value of *standard-output*, called standard output, is a stream that is used by many operators as a default destination for output when no specific output stream is explicitly supplied.
The value of *trace-output*, called trace output, is the stream on which traced functions (see trace) and the time macro print their output.
(with-output-to-string (*error-output*)
(warn "this string is sent to *error-output*"))
=> "Warning: this string is sent to *error-output*
" ;The exact format of this string is implementation-dependent.
(with-input-from-string (*standard-input* "1001")
(+ 990 (read))) => 1991
(progn (setq out (with-output-to-string (*standard-output*)
(print "print and format t send things to")
(format t "*standard-output* now going to a string")))
:done)
=> :DONE
out
=> "
\"print and format t send things to\" *standard-output* now going to a string"
(defun fact (n) (if (< n 2) 1 (* n (fact (- n 1)))))
=> FACT
(trace fact)
=> (FACT)
;; Of course, the format of traced output is implementation-dependent.
(with-output-to-string (*trace-output*)
(fact 3))
=> "
1 Enter FACT 3
| 2 Enter FACT 2
| 3 Enter FACT 1
| 3 Exit FACT 1
| 2 Exit FACT 2
1 Exit FACT 6"
*terminal-io*, synonym-stream, section Time , @xref{trace; untrace} , {section Conditions}, {section Reader}, {section Printer}
The intent of the constraints on the initial value of the I/O customization variables is to ensure that it is always safe to bind or assign such a variable to the value of another I/O customization variable, without unduly restricting implementation flexibility.
It is common for an implementation to make the initial values of *debug-io* and *query-io* be the same stream, and to make the initial values of *error-output* and *standard-output* be the same stream.
The functions y-or-n-p and yes-or-no-p use query I/O for their input and output.
In the normal Lisp read-eval-print loop, input is read from standard input. Many input functions, including read and read-char, take a stream argument that defaults to standard input.
In the normal Lisp read-eval-print loop, output is sent to standard output. Many output functions, including print and write-char, take a stream argument that defaults to standard output.
A program that wants, for example, to divert output to a file should do so by binding *standard-output*; that way error messages sent to *error-output* can still get to the user by going through *terminal-io* (if *error-output* is bound to *terminal-io*), which is usually what is desired.
a bidirectional stream.
implementation-dependent, but it must be an open stream that is not a generalized synonym stream to an I/O customization variables but that might be a generalized synonym stream to the value of some I/O customization variable.
The value of *terminal-io*, called terminal I/O, is ordinarily a bidirectional stream that connects to the user's console. Typically, writing to this stream would cause the output to appear on a display screen, for example, and reading from the stream would accept input from a keyboard. It is intended that standard input functions such as read and read-char, when used with this stream, cause echoing of the input into the output side of the stream. The means by which this is accomplished are implementation-dependent.
The effect of changing the value of *terminal-io*, either by binding or assignment, is implementation-defined.
(progn (prin1 'foo) (prin1 'bar *terminal-io*)) |> FOOBAR => BAR (with-output-to-string (*standard-output*) (prin1 'foo) (prin1 'bar *terminal-io*)) |> BAR => "FOO"
*debug-io*, *error-output*, *query-io*, *standard-input*, *standard-output*, *trace-output*
stream-error, error, serious-condition, condition, t
The type stream-error consists of error conditions that are related to receiving input from or sending output to a stream. The "offending stream" is initialized by the :stream initialization argument to make-condition, and is accessed by the function stream-error-stream.
section stream-error-stream [Function]
stream-error-stream condition => stream
condition---a condition of type stream-error.
stream---a stream.
Returns the offending stream of a condition of type stream-error.
(with-input-from-string (s "(FOO")
(handler-case (read s)
(end-of-file (c)
(format nil "~&End of file on ~S." (stream-error-stream c)))))
"End of file on #<String Stream>."
stream-error, section Conditions
end-of-file, stream-error, error, serious-condition, condition, t
The type end-of-file consists of error conditions related to read operations that are done on streams that have no more data.
section stream-error-stream [Function]
Go to the first, previous, next, last section, table of contents.