Streams
The aim of the stream design presented here is an open architecture for
programming with streams, which should be applicable when the interface to
some object can be characterized by either serial access to, or delivery of,
objects.
The two specific objectives are: (i) transfer of objects between a process and
disk storage; (ii) transfer of objects between one process and another.
The fundamental purpose of a stream object in the scheme presented here is to
provide an interface between two objects through the two functions
read, for streams from which objects are received, and
write, for streams to which objects are sent.
Stream classes
<stream> :
class
This is the root of the stream class hierarchy and also
defines the basic stream class. Initialization options
- read-action : <function>
- A
function which is called by the <stream>
generic-read method. The accessor for this slot is
called stream-read-action.
- write-action : <function>
-
A function which is called by the <stream>
generic-write method. The accessor for this slot is
called stream-write-action.
The following accessor functions are defined for <stream>
- stream-lock
- A lock, to be used to allow exclusive access
to a stream.
- stream-source
- An object to which the stream is
connected and from which input is read.
- stream-sink
- An object to which the stream is
connected and to which ouptut is written.
- stream-buffer
- An object which is used to buffer data by
some subclasses of <stream>. Its default value is
().
- stream-buffer-size
- The maximum number of objects
that can be stored in
stream-buffer. Its default value is
0.
The transaction unit of <stream> is
<object>.
streamp :
function
Arguments
- object
- Returns object, if it is a stream,
otherwise ().
from-stream :
function
A constructor function of one argument for
<stream> which returns a stream whose
stream-read-action is the given argument.
to-stream :
function
A constructor function of one argument for
<stream> which returns a stream whose
stream-write-action is the given argument.
<buffered-
stream> : class
This class specializes
<stream> by the use of a buffer which may grow arbitrarily
large. The transaction unit of <buffered-stream> is
<object>.
<fixed-
buffered-stream> : class
This class
specializes <buffered-stream> by placing a bound on the
growth of the buffer. The transaction unit of
<fixed-buffere-stream> is <object>.
<file-
stream> : class
This class specializes
<fixed-buffered-stream> by providing an interface to data
stored in files on disk. The transaction unit of <file-stream>
is <character>.
The following additional accessor functions are defined for
<file-stream>
- file-stream-filename
- The path identifying the file
system object associated with the stream.
- file-stream-mode
- The mode of the connection between
the stream and the file system object (usually either read or write).
- file-stream-buffer-position
- A key identifying the current
position in the stream's buffer.
Stream operators
connect :
function
Arguments
- source
- The source object from which the stream will
read data.
- sink
- The sink object to which the stream will write
data.
- [options]
- An optional argument for specifying
implementation-defined options.
Connects source to sink according to the
class-specific behaviours of generic-connect.
generic-connect :
generic-function
This is a function of three arguments:
source, sink and options
as described for connect.
generic-connect :
method
Specialized arguments
- (source <stream>)
- The
stream which is to be the source of
sink
- (sink <stream>)
- The
stream which is to be the sink of
source.
- (options <list>)
- A list of
implementation-defined options.
Connects the source of sink to source and
the sink of source to sink. The return
value is ().
generic-connect :
method
Specialized arguments
- (source <path>)
- A path
name.
- (sink <file-stream>)
- The
stream via which data will be received from the file named by
path.
- (options <list>)
- A list of
implementation-defined options
Opens the object identified by the path source for reading
and connects sink to it. Hereafter, sink
may be used for reading data from sink, until
sink is disconnected or reconnected. Implementation-defined
options for the opening of files may be specified using the third argument. See
also open-input-file.
generic-connect :
method
Specialized arguments
- (source <file-stream>)
- The
stream via which data will be sent to the file named by
path.
- (sink <path>)
- A path
name.
- (options <list>)
- A list of
implementation-defined options
Opens the object identifed by the path sink for writing and
connects source to it. Hereafter, source
may be used for writing data to sink, until
source is disconnected or reconnected.
Implementation-defined options for the opening of files may be specified using
the third argument. See also open-output-file.
reconnect :
generic-function
Generic arguments
- (s1 <stream>)
- A stream.
- (s2 <stream>)
- A stream.
Transfers the source and sink connections of s1 to s2,
leaving s1 disconnected.
reconnect :
method
Specialized arguments
- (s1 <stream>)
- A stream.
- (s2 <stream>)
- A stream.
Implements the reconnect operation for objects of class
<stream>.
disconnect :
generic-function
Generic arguments
- (s <stream>)
- A stream.
Disconnects the stream s from its source and/or
its sink.
disconnect :
method
Specialized arguments
- (s <stream>)
- A stream.
Implements the diconnect operation for objects of class
<stream>.
disconnect :
method
Specialized arguments
- (s <file-stream>)
- A stream.
Implements the diconnect operation for objects of class
<file-stream>. In particular, this involves closing the file
associated with the stream.
Stream objects
stdin :
<file-stream>
The standard input stream, which is a file-stream and whose transaction unit
is therefore character. In Posix compliant configurations, this object is
initialized from the Posix stdin object. Note that although
stdin itself is a constant binding, it may be connected to
different files by the reconnect operation.
lispin :
<stream>
The standard lisp input stream, and its transaction unit is object. This stream
is initially connected to stdin (although not necessarily
directly), thus a read operation on lispin
will case characters to be read from stdin and construct and
return an object corresponding to the next lisp expression. Note that although
lispin itself is a constant binding, it may be connected to
different source streams by the reconnect operation.
stdout :
<file-stream>
The standard output stream, which is a file-stream and whose transaction unit
is therefore character. In Posix compliant configurations, this object is
initialized from the Posix stdout object. Note that although
stdout itself is a constant binding, it may be connected to
different files by the reconnect operation.
stderr :
<file-stream>
The standard error stream, which is a file-stream and whose transaction unit
is therefore character. In Posix compliant configurations, this object is
initialized from the Posix stderr object. Note that although
stderr itself is a constant binding, it may be connected to
different files by the reconnect operation.
Buffer management
fill-buffer :
generic-function
Generic arguments
- (stream <buffered-stream>)
-
A stream.
The buffer associated with stream is refilled from its
source. This function returns a count of the number of items read.
This function is guaranteed to be called when an attempt is made to read from
a buffered stream whose buffer is either empty, or from which all the items
have been read.
fill-buffer :
method
Specialized arguments
- (stream <buffered-stream>)
-
A stream.
fill-buffer :
method
Specialized arguments
- (stream <file-stream>)
- A
stream.
flush-buffer :
generic-function
Generic arguments
- (s <buffered-stream>)
- A
stream.
The contents of the buffer associated with stream is flushed to its
sink. If this operation succeeds, a true value is
returned, otherwise the result is (). This function is guaranteed to
be called when an attempt is made to write to a buffered stream whose buffer
is full.
flush-buffer :
method
Specialized arguments
- (stream <buffered-stream>)
-
A stream.
Implements the flush-buffer operation for objects of class
<buffered-stream>.
flush-buffer :
method
Specialized arguments
- (stream <file-stream>)
- A
stream.
Implements the flush-buffer operation for objects of class
<file-stream>. This method is called both when the buffer is
full and after a newline character is written to the buffer.
<end-of-
stream> :
<stream-condition>
Signalled when end-of-stream is called when encountering
the end of the stream.
See also:
generic-read
end-of-stream :
generic-function
Generic arguments
- (stream <stream>)
- A
stream.
This function is guaranteed to be called when a read operation encounters the
end of the stream and the eos-error-p argument to read has a
non-() value.
end-of-stream :
method
Specialized arguments
- (stream <buffered-stream>)
-
A stream.
Signals the end of stream condition.
end-of-stream :
method
Specialized arguments
- (stream <file-stream>)
- A
stream.
Disconnects stream and signals the end of stream condition.
Reading from streams
read :
function
Arguments
- [stream]
- A stream.
- [eos-error-p]
- A boolean.
- [eos-value]
- Value to be returned to indicate end of
stream.
The argument stream defaults to lispin,
eos-error-p defaults to ()and eos-value
defaults to eos-default-value. The result is that of calling
generic-read with the arguments supplied or defaulted as
described.
generic-read :
generic-function
Generic arguments
- (stream <stream>)
- A
stream.
- (eos-error-p <object>)
- A
boolean.
- (eos-value <object>)
- Value
to be returned to indicate end of stream.
The next transaction unit from stream is returned as the result. If
the end of stream is encountered and the value of eos-error-p
is (), the result is eos-value. If the end of stream
is encountered and the value of eos-error-p is
non-(), the function end-of-stream is called with
the argument stream.
generic-read :
method
Specialized arguments
- (stream <stream>)
- A
stream.
- (eos-error-p <object>)
- A
boolean.
- (eos-value <object>)
- Value
to be returned to indicate end of stream.
Implements the generic-read operation for objects of class
<stream>. The result is that of calling the
read-action of stream with the arguments
stream, eos-error-p and eos-value.
generic-read :
method
Specialized arguments
- (stream <buffered-stream>)
-
A buffered stream.
- (eos-error-p <object>)
- A
boolean.
- (eos-value <object>)
- Value
to be returned to indicate end of stream.
Implements the generic-read operation for objects of class
<buffered-stream>. The result is the next object stored in the
stream buffer. If the buffer is empty, the function fill-buffer
is called. If the refilling operation did not succeed, the end of stream action is
carried out as described under the generic-function
generic-read.
generic-read :
method
Specialized arguments
- (stream <file-stream>)
- A
file stream.
- (eos-error-p <object>)
- A
boolean.
- (eos-value <object>)
- Value
to be returned to indicate end of stream.
Implements the generic-read operation for objects of class
<file-stream>. The result is the next character stored in the
stream buffer. If the buffer is empty, the function fill-buffer
is called. If the refilling operation did not succeed, the end of stream action is
carried out as described under the generic-function
generic-read.
Writing to streams
write :
function
Arguments
- obj
- Object to be written.
- [stream]
- Stream for writing.
generic-write :
generic-function
generic Generic arguments
- (obj <object>)
- Object to
be written.
- (stream <stream>)
- Stream
for writing.
generic-write :
method
Specialized arguments
- (obj <object>)
- Object to
be written.
- (stream <stream>)
- Stream
for writing.
generic-write :
method
Specialized arguments
- (obj <object>)
- Object to
be written.
- (stream <buffered-stream>)
-
Stream for writing.
generic-write :
method
Specialized arguments
- (obj <object>)
- Object to
be written.
- (stream <file-stream>)
-
Stream for writing.
Additional functions
read-line :
function
Arguments
- stream
- A stream.
- [eos-error-p]
- A boolean.
- eos-value
- Value to be returned to indicate end of stream.
prin :
function
Arguments
- obj
- Object to be written.
- [stream]
- Stream for writing.
print :
function
Arguments
- obj
- Object to be written.
- [stream]
- Stream for writing.
flush :
function
Arguments
- [stream]
- Stream for writing.
newline :
function
Arguments
- [stream]
- Stream for writing.
prin-char :
function
Arguments
- char
- Character to be written.
- [stream]
- Stream for writing.
- [times]
- Integer count.
Outputs char on stream. The stream
defaults to stdout. The count times defaults to
1. If times is specified, then stream must also be
specified.
sread :
function
Arguments
- stream
- A stream.
- [eos-error-p]
- A boolean.
- eos-value
- Value to be returned to indicate end of stream.
sprin :
function
Arguments
- obj
- Object to be written.
- [stream]
- Stream for writing.
Convenience forms
open-input-file :
function
Arguments
- path
- A path identifying a file system object.
Allocates and returns a new <file-stream> object whose
source is connected to the file system object identified by path.
open-output-file
: function
Arguments
- path
- A path identifying a file system object.
Allocates and returns a new <file-stream> object whose sink
is connected to the file system object identified by path.
with-input-file :
macro
with-input-file =
'(', 'with-input-file', path, {form}, ')';
with-output-file
: macro
with-source :
macro
with-sink :
macro
Posix bindings
fopen :
function
Arguments
- stream
- A stream to connect to a file.
- path
- A path identifying a file system object.
- mode
- How the file is to be opened.
Connects stream to the file system object identified by
path according to the specified mode. The mode is
specified by one of the following symbols:
- r
- Opens file for reading.
- w
- Opens file for writing, creating the file if it does not
exist.
- a
- Opens file for append output, creating the file if it
does not exist. If the file exists, the stream position points to the end of
the file, so any output adds to the file.
- r+
- Opens the file for update. Both input and output
can be performed on the stream. Any existing data in the file is
preserved.
- w+
- Opens the file for update. Both input and output
can be performed on the stream. Any existing data in the file is
eliminated; the file is re-created if it exists.
- a+
- Opens the file for update. The file can be read at
any location, but any output to the file occurs starting from its current
end.
The result is stream.
fclose :
function
Arguments
- stream
- A stream.
Closes the file stream stream and returns (). The
stream is disconnected from the file system object with which it was associated
and may no longer be used for read or
write operations. The stream buffer is flushed to the file
system before the file is closed.
fcntl :
function
Arguments
- stream
- A stream.
- [cmds]
-
fcntl commands as defined
below.
This function returns or sets information about an open file stream. The
symbol command determines the action of fcntl
and in some cases, the third argument command-values must also
be supplied. The command can be any one of the following
symbols, which are a subset of those defined in 1990:??? (POSIX C API):
- F_GETFL
- This is the default value. In this case,
fcntl returns a list of symbols or integers, in no
particular order, describing the stream's attributes. These values can be
among the following:
- O_APPEND
- The file is open in append mode.
- O_NONBLOCK
- Waiting for data does not cause
blocking.
- O_RDONLY
- The file is open for read only.
- O_RDWR
- The file is open for read and write.
- O_WRONLY
- The file is open for write only.
-
- Other implementation-defined values specified as
integers.
- F_SETFL
- In this case the the third argument
command-values must be a list of attributes from the set
described above for
F_GETFL. However, according to
1990:???, only the values O_APPEND and
O_NONBLOCK can be modified.
Discussion
If you would like to read the discussion about this document and its
development please click
here. If you would like to add to the discussion please click
here.