3.7 Streams and External Iterators

Streams are objects that act as a sequential channel of elements from (or even to) some source.

3.7.1 Basic Protocol

Streams respond to a number of common messages. However, many of these only work on some of the stream types, usually according to good sense:

next

reads and returns the next element in the stream. This causes the stream reader to advance one element.

peek

reads and returns the next element in the stream. This does not advance the stream reader.

next:

draws the next n number of elements from the stream and returns them in a Sequence of the appropriate type.

next:putInto:

reads the next N bytes into the given Sequence starting from index 0.

next:putInto:startingAt:

reads the N elements into the given Sequence starting from the given index.

nextPutInto:

reads into the given Sequence the number of elements which will fit into it.

nextPut:

writes the object to the stream.

nextPutAll:

alias stream ; sequence writes all the objects in the Sequence to the stream. The ; selector allows the user to cascade several sequences into the stream as though they were concatenated.

do:

applies a Block to each element of the stream.

flush

synchronizes the total state of the stream with any pending requests made by the user.

atEnd

answers whether or not the stream has reached some limit.

upToEnd

collects all the elements of the stream up to its limit into an ExtensibleSequence.

3.7.2 Basic Stream Variants

Figure shows the major stream types and their relationships.

Figure: Stream Inheritance

Stream

provides the basic protocol for instantiating streams.

Stream

provides the basic protocol for instantiating streams.

PositionableStream

extends Stream to provide a basic protocol to iterate over a sequence of elements from a Sequence or a file or other source. These streams store their position in the sequence as they iterate, and are re-positionable. It also has its own variants, -Read-, -Write-, and -ReadWrite-.

ReadStream

provides the basic protocol for input access to a source.

WriteStream

provides the basic protocol for output access to a target.

ReadWriteStream

provides the basic protocol for both read and write access, and caches its input as necessary.

FileStream

targets a file, for reading or writing.

DummyStream

is a ReadStream that just returns Nil repeatedly.

EchoStream

is a wrapper for a Stream which copies all stream input/output interactions to another Stream for logging purposes.

BlockStream

is a ReadStream that targets a no-input block and returns its output each time.

BufferReadStream

wraps another stream with a special Buffer object for reading large chunks from the stream at a time while handing out the elements as requested. This also minimizes stress on the memory-allocator by avoiding unnecessary allocation of arrays.

BufferWriteStream

wraps another stream with a special Buffer object for writing large chunks to the stream at a time while accepting new elements as requested. This also minimizes stress on the memory-allocator by avoiding unnecessary allocation of arrays.

3.7.3 Basic Instantiation

There are a number of ways to create Streams, and a large number of implementations, so some methods exist to simplify the process of making a new one:

newOn:

creates a new Stream of the same type as the first argument, targetting it to the second as a source. This should not be overridden. Instead, the retargetting method on: is overridden.

newTo:

creates a new WriteStream of the appropriate type on the specified target. This should be overridden for derived types, and the first argument should apply to the generic Stream type to allow any instance to know this protocol.

newFrom:

creates a new ReadStream of the appropriate type on the specified target. This should be overridden for derived types, and the first argument should apply to the generic Stream type to allow any instance to know this protocol.

buffered

creates and returns a new BufferStream whose type corresponds to the argument and wraps the argument Stream.

readBuffered

creates and returns a new ReadBufferStream which wraps the argument Stream.

writeBuffered

creates and returns a new WriteBufferStream which wraps the argument Stream.

echoTo:

creates and returns a new EchoStream which wraps the first argument Stream and echoes to the second.

3.7.4 Standard Input/Output

The Slate interpreter provides two Streams primitively, ConsoleInput and ConsoleOutput, which are Read- and WriteStreams by default.

3.7.5 Collection Iterator Streams

Each collection type may define its own Stream type which goes over its elements in series, even if the collection is not ordered, and only visits each element once. This type's prototype is accessed via the slot ReadStream within each collection. So ``Set ReadStream'' refers to the prototype suitable for iterating over Sets.

In order to create a new iterator for a specific collection, the iterator message is provided, which clones the prototype for that collection's type and targets it to the receiver of the message. The protocol summary:

iterator

will return a ReadStream or preferrably a ReadWriteStream if one is available for the type.

reader

and writer get only ReadStream and WriteStream objects for the type, when available.