# The streams Module¶

This document describes the Streams module, which allows you to establish and control input to and output from aggregates of data, such as files on disk, or sequences. This module, together with the Standard-IO module, provides similar functionality to the java.io package in Java. See The standard-io Module, for details about the Standard-IO module in Dylan.

Concepts discusses the basic concepts involved in streaming over data. Stream classes describes the different classes of stream available, and how to create them, and Reading from and writing to streams describes how to read from and write to them.

More specialized subjects are covered next: Locking streams discusses locking streams while they are in use; Using buffered streams describes using buffered streams; Wrapper streams describes wrapper streams; Conditions the different stream-specific error conditions that can be raised.For the most part, you do not have to worry about the information in these later sections when using streams.

Finally, The streams Module Reference gives complete details on all interfaces in the Streams module. Each entry in this section is arranged in alphabetical order.

## Error conditions¶

This document uses two special terms in discussions of error conditions.

When it notes that something is an error, this means that the result is undefined. In particular, it does not*necessarily* mean that an error condition will be signalled. So, for instance, the following example text means only that the result of using pull-stream-element in the case described is undefined:

It is an error to apply pull-stream-element to an element that has already been read from the stream.

A given function is only guaranteed to raise an exception in response to an error if the documentation for that function specifically states that it will signal an error. Note that the specific error condition that is signaled may depend on the program state; in such situations, the specific error condition is not stated in the documentation. Consider the following hypothetical example, which states that an implementation must signal an error, but does not say what error must be signaled:

When index is a <stream-index>, if it is invalid for some reason, this function signals an error.

By contrast, the following example names the class of which the condition signaled is guaranteed to be a general instance:

If the end of the stream is encountered and no value was supplied for on-end-of-stream, read-last-element signals an <end-of-stream-error> condition.

If the name of the condition class is given, applications are permitted to specialize error handlers on that class.

## Goals of the module¶

The Streams module provides:

• A generic, easy-to-use interface for streaming over sequences and files. The same high-level interface for consuming or producing is available irrespective of the type of stream, or the types of the elements being streamed over.
• Efficiency, especially for the common case of file I/O.
• Access to an underlying buffer management protocol.

The Streams module does not address a number of related issues, including:

• A standard object-printing package such as Smalltalk’s printOn: or Lisp’s print-object, or a formatted printing facility such as Lisp’s format. These facilities are provided by the Print, Format, and Format-out libraries. For convenience, the Common Dylan library also provides simple formatting capabilities.
• A comprehensive range of I/O facilities for using memory-mapped files, network connections, and so on.
• An interface for naming files. The Locators module provides such an interface.
• An interface to operating system functionality, such as file renaming or deleting operations. The File-System module provides such an interface.

## Concepts¶

A stream provides sequential access to an aggregate of data, such as a Dylan sequence or a disk file. Streams grant this access according to a metaphor of reading and writing: elements can be read from streams or written to them.

Streams are represented as Dylan objects, and all are general instances of the class <stream>, which the Streams module defines.

It is usual to say that a stream is established over the data aggregate. Hence, a stream providing access to the string "hello world" is said to be a stream over the string "hello world".

Streams permitting reading operations are called input streams. Input streams allow elements from the underlying data aggregate to be consumed. Conversely, streams permitting writing operations are called output streams. Output streams allow elements to be written to the underlying data aggregate. Streams permitting both kinds of operations are called input-output streams.

The Streams module provides a set of functions for reading elements from an input stream. These functions hide the details of indexing, buffering, and so on. For instance, the function read-element reads a single data element from an input stream.

The following expression binds stream to an input stream over the string "hello world":

let stream = make(<string-stream>, contents: "hello world");


The first invocation of read-element on stream returns the character “h”, the next invocation “e”, and so on. Once a stream has been used to consume all the elements of the data, the stream is said to be at its end. This condition can be tested with the function stream-at-end?. The following code fragment applies my-function to all elements of the sequence:

let stream = make(<sequence-stream>, contents: seq);
while (~stream-at-end?(stream))
end;


When all elements of a stream have been read, further calls to read-element result in the <end-of-stream-error> condition being signaled. An alternative end-of-stream behavior is to have a distinguished end-of-stream value returned. You can supply such an end-of-stream value as a keyword argument to the various read functions; the value can be any object. Supplying an end-of-stream value to a read function is more concise than asking whether a stream is at its end on every iteration of a loop.

The Streams module also provides a set of functions for writing data elements to an output stream. Like the functions that operate upon input streams, these functions hide the details of indexing, growing an underlying sequence, buffering for a file, and so on. For instance, the function write-element writes a single data element to an output stream.

The following forms bind stream to an output stream over an empty string and create the string “I see!”, using the function stream-contents to access all of the stream’s elements.

let stream = make(<byte-string-stream>, direction: #"output");
write(stream, "I see!");
stream-contents(stream);


Calling write on a sequence has the same effect as calling write-element on all the elements of the sequence. For more information about writing to streams, see Writing to streams.

Some streams are positionable; that is, any element of the stream can be accessed at any time. Positionable streams allow you to set the position at which the stream is accessed by the next operation. The following example uses positioning to return the character “w” from a stream over the string "hello world":

let stream = make(<string-stream>, contents: "hello world");
stream-position(stream) := 6;


The following example returns a string. The first ten characters are the fill characters for the underlying sequence of the stream. The fill character for <string> is ” ” (the space character), so in the example below, the first ten characters are spaces.

let stream = make(<string-stream>, direction: #"output");
write(stream, "whoa!");
stream-contents(stream);


You can request a sequence containing all of the elements of a positionable stream by calling stream-contents on it. If the positionable stream is a <file-stream>, then it must be readable. Otherwise, it must be a sequence stream. The sequence returned never shares structure with any underlying sequence that might be used in the future by the stream. For instance, the string returned by calling stream-contents on an output <string-stream> will not be the same string as that being used to represent the string stream.

When making an input <string-stream>, you can cause the stream to produce elements from any subsequence of the supplied string. For example:

read-to-end(make(<string-stream>,
contents: "hello there, world",
start: 6,
end: 11));


This example evaluates to "there". The interval (start, end) includes the index start but excludes the index end. This is consistent with standard Dylan functions over sequences, such as copy-sequence. The read-to-end function is one of a number of convenient utility functions for operating on streams and returns all the elements up to the end of the stream from the stream’s current position.

### Streams, growing sequences, and object identity¶

When writing to output streams over sequences, Dylan may from time to time need to grow the underlying sequence that it is using to represent the stream data.

Consider the example of an output stream instantiated over an empty string. As soon as a write operation is performed on the stream, it is necessary to replace the string object used in the representation of the string stream. As well as incurring the cost of creating a new string, references to the string within the program after the replacement operation has occurred will still refer to the original string, and this may not be what the user intended.

To guarantee that other references to a sequence used in an output <sequence-stream> will have access to any elements written to the sequence via the stream, supply a stretchy collection (such as a <stretchy-vector>) to make. A stream over a stretchy vector will use the same stretchy vector throughout the stream’s existence.

For example:

let sv = make(<stretchy-vector>);
let stream = make(<sequence-stream>,
contents: sv,
direction: #"output");
write(stream, #(1, 2, 3, 4, 5, 6, 7, 8, 9));
write(stream, "ABCDEF");
values(sv, stream-contents(stream));


The example returns two values. Each value is the same (==) stretchy vector:

(1, 2, 3, 4, 5, 6, 7, 8, 9, 'A', 'B', 'C', 'D', 'E', 'F')


If a stretchy vector is not supplied, the result is different:

let v = make(<vector>, size: 5);
let stream = make(<sequence-stream>,
contents: v,
direction: #"output");
write(stream, #(1, 2, 3, 4, 5, 6, 7, 8, 9));
write(stream, "ABCDEF");
values(v, stream-contents(stream));


This example returns as its first value the original vector, whose contents are unchanged, but the second value is a new vector:

(1, 2, 3, 4, 5, 6, 7, 8, 9, 'A', 'B', 'C', 'D', 'E', 'F')


This difference arises because the output stream in the second example does not use a stretchy vector to hold the stream data. A vector of at least 15 elements is necessary to accommodate the elements written to the stream, but the vector supplied, v, can hold only 5. Since the stream cannot change v ‘s size, it must allocate a new vector each time it grows.

## Stream classes¶

The exported streams class heterarchy includes the classes shown in Streams module classes. Classes shown in bold are all instantiable.

• s - sealed | o - open
• p - primary | f - free
• c - concrete | a - abstract
• u - uninstantiable | i - instantiable

### Creating streams¶

This section describes how to create and manage different types of file stream and sequence stream.

### File streams¶

File streams are intended only for accessing the contents of files. More general file handling facilities, such as renaming, deleting, moving, and parsing directory names, are provided by the File-System module: see The file-system Module for details. The make method on <file-stream> does not create direct instances of <file-stream>, but instead an instance of a subclass determined by type-for-file-stream.

make file-stream-class

G.f method

make <file-stream> #key locator: direction: if-exists:
if-does-not-exist: buffer-size: element-type: asynchronous?: share-mode => file-stream-instance

Creates and opens a stream over a file, and returns a new instance of a concrete subclass of <file-stream> that streams over the contents of the file referenced by filename. To determine the concrete subclass to be instantiated, this method calls the generic function type-for-file-stream.

The locator: init-keyword should be a string naming a file. If the Locators library is in use, filename should be an instance of <locator> or a string that can be coerced to one.

The direction: init-keyword specifies the direction of the stream. This can be one of #"input", #"output", or #"input-output". The default is #"input".

The if-exists: and if-does-not-exist: init-keywords specify actions to take if the file named by filename does or does not already exist when the stream is created. These init-keywords are discussed in more detail in Options when creating file streams.

The buffer-size: init-keyword can be used to suggest the size of a stream’s buffer. See <buffered-stream>.

The element-type: init-keyword specifies the type of the elements in the file named by filename. See Options when creating file streams for more details.

### Options when creating file streams¶

When creating file streams, you can supply the following init-keywords to make in addition to those described in File streams:

• if-exists: An action to take if the file already exists.
• if-does-not-exist: An action to take if the file does not already exist.
• element-type: How the elements of the underlying file are accessed.
• asynchronous?: Allows asynchronous writing of stream data to disk.
• share-mode: How the file can be accessed while the stream is operating on it.

The if-exists: init-keyword allows you to specify an action to take if the file named by filename already exists. The options are:

• #f The file is opened with the stream position at the beginning. This is the default when the stream’s direction is #"input" or #"input-output".
• #"new-version" If the underlying file system supports file versioning, a new version of the file is created. This is the default when the stream’s direction is #"output". If the file system does not support file versioning, the default is #"replace" when the direction of the stream is #"output".
• #"overwrite" Set the stream’s position to the beginning of the file, but preserve the current contents of the file. This is useful when the direction is #"input-output" or #"output" and you want to overwrite an existing file.
• #"replace" Delete the existing file and create a new file.
• #"append" Set the stream’s initial position to the end of the existing file so that all new output occurs at the end of the file. This option is only useful if the file is writeable.
• #"truncate" If the file exists, it is truncated, setting the size of the file to 0. If the file does not exist, create a new file.
• #"signal" Signal a <file-exists-error> condition.

The if-does-not-exist: init-keyword allows you to specify an action to take if the file named by filename does not exist. The options are:

• #f No action.
• #"signal" Signal a <file-does-not-exist-error> condition. This is the default when the stream’s direction is #"input".
• #"create" Create a new zero-length file. This is the default when the stream’s direction is #"output" or #"input-output".

Because creating a file stream always involves an attempt to open the underlying file, the aforementioned error conditions will occur during file stream instance initialization.

File permissions are checked when creating and opening file streams, and if the user attempts to open a file for input, and has no read permission, or to open a file for output, and has no write permission, then an <invalid-file-permissions-error> condition is signalled at the time the file stream is created.

The element-type: init-keyword controls how the elements of the underlying file are accessed. The three possible element types are:

The asynchronous?: init-keyword allows asynchronous writing of stream data to disk. If #f, whenever the stream has to write a buffer to disk, the thread which triggered the write must wait for the write to complete. If asynchronous? is #t, the write proceeds in parallel with the subsequent actions of the thread.

Note that asynchronous writes complicate error handling a bit. Any write error which occurs most likely occurs after the call which triggered the write. If this happens, the error is stored in a queue, and the next operation on that stream signals the error. If you close the stream with the wait? flag #f, the close happens asynchronously (after all queued writes complete) and errors may occur after close has returned. A method wait-for-io-completion is provided to catch any errors that may occur after close is called.

The share-mode: keyword determines how a file can be accessed by other streams while the stream has it open. The possible values are:

• #"share-read" Allow other streams to be opened to the file for reading but not for writing.
• #"share-write" Allow other streams to be opened for writing but not for reading.
• #"share-read-write" Allow other streams to be opened for writing or reading.
• #"exclusive" Do not allow other streams to be opened to this file.

### Sequence streams¶

There are make methods on the following stream classes:

Rather than creating direct instances of <sequence-stream> or <string-stream>, the make methods for those classes might create an instance of a subclass determined by type-for-sequence-stream.

### Closing streams¶

It is important to call close on streams when you have finished with them. Typically, external streams such as <file-stream> and <console-stream> allocate underlying system resources when they are created, and these resources are not recovered until the stream is closed. The total number of such streams that can be open at one time may be system dependent. It may be possible to add reasonable finalization methods to close streams when they are no longer referenced but these are not added by default. See the The finalization Module for full details about finalization.

### Locking streams¶

In an application where more than one control thread may access a common stream, it is important to match the granularity of locking to the transaction model of the application. Ideally, an application should lock a stream which is potentially accessed by multiple threads, only once per transaction. Repeated and unnecessary locking and unlocking can seriously degrade the performance of the Streams module. Thus an application which wishes to write a complex message to a stream that needs to be thread safe should lock the stream, write the message and then unlock the stream after the entire message is written. Locking and unlocking the stream for each character in the message would be a poor match of locking to transaction model. The time required for the lock manipulation would dominate the time required for the stream transactions. Unfortunately this means that there is no way for the Streams module to choose a default locking scheme without the likelihood of seriously degrading streams performance for all applications whose transaction models are different from the model implied by the chosen default locking scheme. Instead, the Streams module provides the user with a single, per instance slot, stream-lock:, which is inherited by all subclasses of <stream>. You should use the generic functions lock-stream and unlock-stream or the macro with-stream-locked, together with other appropriate functions and macros from the Threads library, to implement a locking strategy appropriate to your application and its stream transaction model. The functions in the Streams module are not of themselves thread safe, and make no guarantees about the atomicity of read and write operations.

## Reading from and writing to streams¶

This section describes how you can read from or write to a stream. Note that it is an error to call any of these functions on a buffered stream while its buffer is held by another thread; see Using buffered streams for details about buffered streams.

### Reading from streams¶

The following are the basic functions for reading from streams.

A number of other functions are available for reading from streams. See peek, read-into!, discard-input, and stream-input-available?.

### Convenience functions for reading from streams¶

The following is a small set of reading functions that search for particular elements in a stream. These functions behave as though they were implemented in terms of the more primitive functions described in Reading from streams.

### Writing to streams¶

This section describes the basic functions for writing to streams.

### Reading and writing by lines¶

The following functions provide line-based input and output operations.

The newline sequence for string streams is a sequence comprising the single newline character \n. For character file streams, the newline sequence is whatever sequence of characters the underlying platform uses to represent a newline. For example, on MS-DOS platforms, the sequence comprises two characters: a carriage return followed by a linefeed.

Note

No other functions in the Streams module do anything to manage the encoding of newlines; calling write-element on the character \n does not cause the \n character to be written as the native newline sequence, unless \n happens to be the native newline sequence.

See also read-line-into!.

### Querying streams¶

The following functions can be used to determine various properties of a stream.

For output streams, note that you can determine if a stream is one place past the last written element by comparing stream-position to stream-size.

### Using file streams¶

The following operations can be performed on file streams.

## Using buffered streams¶

The Streams module provides efficient support for general use of buffered I/O. Most ordinary programmers using the module do not need to be concerned with buffering in most cases. When using buffered streams, the buffering is transparent, but programs requiring more control can access buffering functionality when appropriate. This section describes the available buffering functionality.

### Overview¶

A buffered stream maintains some sort of buffer. All buffered streams use the sealed class <buffer> for their buffers. You can suggest a buffer size when creating buffered streams, but normally you do not need to do so, because a buffer size that is appropriate for the stream’s source or destination is chosen for you.

Instances of the class <buffer> also contain some state information. This state information includes an index where reading or writing should begin, and an index that is the end of input to be read, or the end of space available for writing.

Buffered streams also maintain a held state, indicating whether the application has taken the buffer for a stream and has not released it yet. When a thread already holds the buffer for a stream, it is an error to get the buffer again (or any other buffer for the same stream).

### Useful types when using buffers¶

The following types are used in operations that involve buffers.

<byte>
A type representing limited integers in the range 0 to 255 inclusive.
<byte-character>
A type representing 8-bit characters that instances of <byte-string> can contain.
<unicode-character>
A type representing Unicode characters that instances of <unicode-string> can contain.
<byte-vector>
A subtype of <vector> whose element-type is <byte>.

## Wrapper streams¶

Sometimes stream data requires conversion before an application can use it: you might have a stream over a file of EBCDIC characters which you would prefer to handle as their ASCII equivalents, or you might need to encrypt or decrypt file data.

Wrapper streams provide a mechanism for working with streams which require such conversion. Wrapper streams hold on to an underlying stream, delegating to it most streams operations. The wrapper stream carries out appropriate processing in its own implementations of the streaming protocol.

The Streams module includes a base class called <wrapper-stream> upon which other wrapping streams can be implemented.

A subclass of <wrapper-stream> can “pass on” functions such as read-element and write-element by simply delegating these operations to the inner stream, as shown below:

define method read-element (ws :: <io-wrapper-stream>,
#key on-end-of-stream)
=> (element)
on-end-of-stream: on-end-of-stream)
end method;

define method write-element (ws :: <io-wrapper-stream>, element)
=> ()
write-element(ws.inner-stream, element)
end method;


Assuming that <io-wrapper-stream> delegates all other operations to its inner stream, the following would suffice to implement a 16-bit Unicode character stream wrapping an 8-bit character stream.

define class <unicode-stream> (<io-wrapper-stream>) end class;

define method read-element (s :: <unicode-stream>,
#key on-end-of-stream)
=> (ch :: <unicode-character>)
let first-char = read-element(s.inner-stream,
on-end-of-stream);
let second-char = read-element(s.inner-stream,
on-end-of-stream)
convert-byte-pair-to-unicode(first-char, second-char)
end method;

define method write-element (s :: <unicode-stream>,
c :: <character>)
=> ()
let (first-char, second-char) =
convert-unicode-to-byte-pair(c);
write-element(s.inner-stream, first-char);
write-element(s.inner-stream, second-char)
c
end method;

define method stream-position (s :: <unicode-stream>)
=> p :: <integer>;
truncate/(stream-position(s.inner-stream), 2)
end method;

define method stream-position-setter (p :: <integer>,
s :: <unicode-stream>);
stream-position(s.inner-stream) := p * 2
end method;


### Wrapper streams and delegation¶

One problem with wrapper streams is the need for a wrapper stream to intercept methods invoked by its inner stream. For example, consider two hypothetical streams, <interactive-stream> and <dialog-stream>, the latter a subclass of <wrapper-stream>. Both of these classes have a method called prompt. The <interactive-stream> class specializes read thus:

define method read (s :: <interactive-stream>,
n :: <integer>,
#key on-end-of-stream);
prompt(s);
next-method()
end method;


If a <dialog-stream> is used to wrap an <interactive-stream> then an invocation of read on the <dialog-stream> will call prompt on the inner <interactive-stream>, not on the <dialog-stream>, as desired. The problem is that the <dialog-stream> delegates some tasks to its inner stream, but handles some other tasks itself.

Delegation by inner-streams to outer-streams is implemented by the use of the outer-stream function. The outer-stream function is used instead of the stream itself whenever a stream invokes one of its other protocol methods.

A correct implementation of the read method in the example above would be as follows:

define method read (stream :: <interactive-stream>,
n :: <integer>,
#key on-end-of-stream)
prompt(s.outer-stream);
next-method()
end method;


The initialize method on <stream> is defined to set the outer-stream slot to be the stream itself. The initialize method on <wrapper-stream> is specialized to set the outer-stream slot to be the “parent” stream:

define method initialize (stream :: <wrapper-stream>,
#key on, #rest all-keys);
an-inner-stream.outer-stream := stream;
next-method()
end method;


## Conditions¶

The following classes are available for error conditions on streams.

There is no recovery protocol defined for any of these errors. Every condition that takes an init-keyword has a slot accessor for the value supplied. The name of this accessor function takes the form class - key, where class is the name of the condition class (without the angle brackets) and key is the name of the init-keyword. For example, the accessor function for the locator: init-keyword for <file-error> is file-error-locator.

For more information, please refer to the reference entry for the individual conditions.

## Indenting streams¶

The Streams module provides an <indenting-stream> which supports managing indentation when printing text to a stream. Indenting streams are implemented as wrapper streams, so the destination stream must be provided at instantiation.

let is = make(<indenting-stream>, inner-stream: *standard-output*);
with-indentation(is, 4)
// Write normally to the indenting stream.
format(is, "Hello %=!\n", name);
end with-indentation;


Indenting streams analyze everything written to them so that indentation can be maintained, without having to call new-line directly.

### Using indenting streams¶

All operations available to <wrapper-stream> are available, as well as:

## Streams protocols¶

This section describes the protocols for different classes of stream.

### Positionable stream protocol¶

This section describes the protocol for positionable streams.

A stream position can be thought of as a natural number that indicates how many elements into the stream the stream’s current location is. However, it is not always the case that a single integer contains enough information to reposition a stream. Consider the case of an “uncompressing” file stream that requires additional state beyond simply the file position to be able to get the next input character from the compressed file.

The Streams module addresses this problem by introducing the class <stream-position>, which is subclassed by various kinds of stream implementations that need to maintain additional state. A stream can be repositioned as efficiently as possible when stream-position-setter is given a value previously returned by stream-position on that stream.

It is also legal to set the position of a stream to an integer position. However, for some types of streams, to do so might be slow, perhaps requiring the entire contents of the stream up to that point to be read.

### Wrapper stream protocol¶

This section describes the protocol for implementing wrapper streams. For information on using wrapper streams, see Wrapper streams.

## The streams Module Reference¶

This section includes complete reference entries for all interfaces that are exported from the streams module.

adjust-stream-position Open Generic function

Moves the position of a positionable stream by a specified amount.

Signature: adjust-stream-position positionable-stream delta #key from => new-position positionable-stream – An instance of . delta – An instance of . from (#key) – One of #"current", #"start", or #"end". Default value: #"current". new-position – An instance of . Moves the position of positionable-stream to be offset delta elements from the position indicated by from. The new position is returned. When from is #"start", the stream is positioned relative to the beginning of the stream. When from is #"end", the stream is positioned relative to its end. When from is #"current", the current position is used. Using adjust-stream-position to set the position of a stream to be beyond its current last element causes the underlying aggregate to be grown to a new size. When extending the underlying aggregate for a stream, the contents of the unwritten elements are the fill character for the underlying sequence. The following example returns a string, the first ten characters of which are the space character, which is the fill character for the sequence . let stream = make(, direction: #"output"); adjust-stream-position(stream, 10); write(stream, "whoa!"); stream-contents(stream); 
as(<integer>, <stream-position>) Method

Coerces a <stream-position> to an integer.

Signature: as integer-class stream-position => integer integer-class – The class . stream-position – An instance of . integer – An instance of . Coerces a  to an integer. The integer-class argument is the class .
<buffer> Instantiable Sealed Class

A subclass of <vector> whose element-type is <byte>.

Superclasses:  size – An instance of  specifying the size of the buffer. Default value: 0. next – An instance of . For an input buffer, this is where the next input byte can be found. For an output buffer, this is where the next output byte should be written to. Default value: 0. end – An instance of . The value of this is one more than the last valid index in a buffer. For an input buffer, this represents the number of bytes read. A subclass of  whose element-type is . Instances of  contain a data vector and two indices: the inclusive start and the exclusive end of valid data in the buffer. The accessors for these indexes are called buffer-next and buffer-end. Note that size: is not taken as a suggestion of the size the user would like, as with the value passed with buffer-size: to make on ; if you supply a value with the size: init-keyword, that size is allocated, or, if that is not possible, an error is signalled, as with making any vector.
<buffered-stream> Open Abstract Class

A subclass of <stream> supporting the Stream Extension and Buffer Access protocols.

Superclasses:  buffer-size – An instance of . This is the size of the buffer in bytes. A subclass of  supporting the Stream Extension Protocol and the Buffer Access Protocol. It is not instantiable. Streams of this class support the buffer-size: init-keyword, which can be used to suggest the size of the stream’s buffer. However, the instantiated stream might not use this value: it is taken purely as a suggested value. For example, a stream that uses a specific device’s hardware buffer might use a fixed buffer size regardless of the value passed with the buffer-size: init-keyword. In general, it should not be necessary to supply a value for the buffer-size: init-keyword.
<byte> Type
Type: A type representing limited integers in the range 0 to 255 inclusive.  A type representing limited integers in the range 0 to 255 inclusive.
<byte-character> Type
Type: A type representing 8-bit characters that instances of  can contain.  A type representing 8-bit characters that instances of  can contain.
byte-storage-address(<buffer>) Sealed Method

Returns the address of the raw byte storage of a <buffer>.

byte-storage-offset-address(<buffer>) Sealed Method

Returns the address of the raw byte storage of a <buffer>, with an offset.

<byte-string-stream> Open Instantiable Class

The class of streams over byte strings.

Superclasses:  contents – A general instance of . direction – Specifies the direction of the stream. It must be one of #"input", #"output", or #"input-output". Default value: #"input". start – An instance of . This specifies the start position of the sequence to be streamed over. Only valid when direction: is #"input". Default value: 0. end – An instance of . This specifies the sequence position immediately after the portion of the sequence to stream over. Only valid when direction: is #"input". Default value: contents.size. The class of streams over byte strings. It is a subclass of . The class supports the same init-keywords as . The contents: init-keyword is used as the input for an input stream, and as the initial storage for an output stream. The start: and end: init-keywords specify the portion of the byte string to create the stream over: start: is inclusive and end: is exclusive. The default is to stream over the entire byte string.
<byte-vector> Sealed Class

A subtype of <vector> whose element-type is <byte>.

Superclasses:  See Superclasses. A subclass of  whose element-type is .
close Open Generic function

Closes a stream.

Signature: close stream #key #all-keys => () stream – An instance of . Closes stream, an instance of .
close(<file-stream>) Method

Closes a file stream.

Signature: close file-stream #key abort? wait? => () file-stream – An instance of . abort? (#key) – An instance of . Default value: #f. wait? (#key) – An instance of . Closes a file stream. This method frees whatever it can of any underlying system resources held on behalf of the stream. If abort is false, any pending data is forced out and synchronized with the file’s destination. If abort is true, then any errors caused by closing the file are ignored.
discard-input Open Generic function

Discards input from an input stream.

Signature: discard-input input-stream => () input-stream – An instance of . Discards any pending input from input-stream, both buffered input and, if possible, any input that might be at the stream’s source. This operation is principally useful for “interactive” streams, such as TTY streams, to discard unwanted input after an error condition arises. There is a default method on  so that applications can call this function on any kind of stream. The default method does nothing.
discard-output Open Generic function

Discards output to an output stream.

Signature: discard-output output-stream => () output-stream – An instance of . Attempts to abort any pending output for output-stream. A default method on  is defined, so that applications can call this function on any sort of stream. The default method does nothing.
<end-of-stream-error> Class

Error type signaled on reaching the end of an input stream.

Superclasses:  stream – An instance of . Signalled when one of the read functions reaches the end of an input stream. It is a subclass of . The stream: init-keyword has the value of the stream that caused the error to be signaled. Its accessor is end-of-stream-error-stream.
<file-does-not-exist-error> Class

Error type signaled when attempting to read a file that does not exist.

Superclasses:  See Superclasses. Signaled when an input file stream creation function tries to read a file that does not exist. It is a subclass of .
<file-error> Class

The base class for all errors related to file I/O.

Superclasses:  locator – An instance of . The base class for all errors related to file I/O. It is a subclass of . The locator: init-keyword indicates the locator of the file that caused the error to be signalled. Its accessor is file-error-locator.
<file-exists-error> Class

Error type signaled when trying to create a file that already exists.

Superclasses:  See Superclasses. Signalled when an output file stream creation function tries to create a file that already exists. It is a subclass of .
<file-stream> Open Abstract Instantiable Class

The class of single-buffered streams over disk files.

Superclasses: locator – An instance of  or . This specifies the file over which to stream. direction – Specifies the direction of the stream. It must be one of #"input", #"output", or #"input-output". Default value: #"input". if-exists – One of #f, #"new-version", #"overwrite", #"replace", #"append", #"truncate", #"signal". Default value: #f. if-does-not-exist – One of #f, #"signal", or #"create". Default value: depends on the value of direction:. asynchronous? – If #t, all writes on this stream are performed asynchronously. Default value:#f. The class of single-buffered streams over disk files. It is a subclass of  and . When you instantiate this class, an indirect instance of it is created. The file being streamed over is opened immediately upon creating the stream. The class supports several init-keywords: locator:, direction:, if-exists:, and if-does-not-exist:.
force-output Open Generic function

Forces pending output from an output stream buffer to its destination.

Signature: force-output output-stream #key synchronize? => () output-stream – An instance of . synchronize? (#key) – An instance of . Default value: #f. Forces any pending output from output-stream ‘s buffers to its destination. Even if the stream is asynchronous, this call waits for all writes to complete. If synchronize? is true, also flushes the operating system’s write cache for the file so that all data is physically written to disk. This should only be needed if you’re concerned about system failure causing loss of data.
<incomplete-read-error> Class

Error type signaled on encountering the end of a stream before reading the required number of elements.

Superclasses:  sequence – An instance of . count – An instance of . This error is signaled when input functions are reading a required number of elements, but the end of the stream is read before completing the required read. The sequence: init-keyword contains the input that was read before reaching the end of the stream. Its accessor is incomplete-read-error-sequence. The count: init-keyword contains the number of elements that were requested to be read. Its accessor is incomplete-read-error-count.
<indenting-stream> Instantiable Sealed Class

A wrapper stream which outputs indented text.

Superclasses:  inner-stream – An instance of . Inherited from . indentation – An instance of . Default value is 0. input-tab-width – An instance of . Default value is 8. output-tab-width – An instance of #f or . Default value is #f. A wrapper stream which outputs indented text. The initial indentation is controlled by indentation:. When output-tab-width: is not false, then the indenting stream converts sequences of spaces used for indentation to tabs.
indent Generic function

Alters the indentation level of an <indenting-stream>.

Signature: indent stream delta => () stream – An instance of . delta – An instance of . let is = make(, inner-stream: *standard-output*); indent(is, 4); format(is, "Hello, %=\n", name); indent(is, -4); 
inner-stream Open Generic function

Returns the stream being wrapped.

Signature: inner-stream wrapper-stream => wrapped-stream wrapper-stream – An instance of . wrapped-stream – An instance of . Returns the stream wrapped by wrapper-stream.
inner-stream-setter Open Generic function

Wraps a stream with a wrapper stream.

Signature: inner-stream-setter stream wrapper-stream => stream stream – An instance of . wrapper-stream – An instance of . stream – An instance of . Wraps stream with wrapper-stream. It does so by setting the inner-stream slot of wrapper-stream to stream, and the outer-stream slot of stream to wrapper-stream. Note Applications should not set inner-stream and outer-stream slots directly. The inner-stream-setter function is for use only when implementing stream classes.
<invalid-file-permissions-error> Class

Error type signalled when accessing a file in a way that conflicts with the permissions of the file.

Superclasses:  See Superclasses. Signalled when one of the file stream creation functions tries to access a file in a manner for which the user does not have permission. It is a subclass of .
lock-stream Open Generic function

Locks a stream.

Signature: lock-stream stream stream – An instance of . Locks a stream. It is suggested that with-stream-locked be used instead of direct usages of lock-stream and unlock-stream. See Locking streams for more detail and discussion on using streams from multiple threads.
make(<byte-string-stream>) Method

Creates and opens a stream over a byte string.

Signature: make byte-string-stream-class #key contents direction start end => byte-string-stream-instance byte-string-stream-class – The class . contents (#key) – An instance of . direction (#key) – One of #"input", #"output", or #"input-output". Default value: #"input". start (#key) – An instance of . Default value: 0. end (#key) – An instance of . Default value: contents.size. byte-string-stream-instance – An instance of . Creates and opens a stream over a byte string. This method returns an instance of . If supplied, contents describes the contents of the stream. The direction, start, and end init-keywords are as for make on . let stream = make(, direction: #"output"); 
make(<file-stream>) Method

Creates and opens a stream over a file.

Signature: make file-stream-class #key filename direction if-exists if-does-not-exist buffer-size element-type => file-stream-instance file-stream-class – The class . filename (#key) – An instance of 
make(<sequence-stream>) Method

Creates and opens a stream over a sequence.

Signature: make sequence-stream-class #key contents direction start end => sequence-stream-instance sequence-stream-class – The class . contents (#key) – An instance of . direction (#key) – One of #"input", #"output", or #"input-output". Default value: #"input". start (#key) – An instance of . Default value: 0. end (#key) – An instance of . Default value: contents.size. sequence-stream-instance – An instance of . Creates and opens a stream over a sequence. This method returns a general instance of . To determine the concrete subclass to be instantiated, this method calls the generic function type-for-sequence-stream. The contents init-keyword is a general instance of  which is used as the input for input streams, and as the initial storage for an output stream. If contents is a stretchy vector, then it is the only storage used by the stream. The direction init-keyword specifies the direction of the stream. The start and end init-keywords are only valid when direction is #"input". They specify the portion of the sequence to create the stream over: start is inclusive and end is exclusive. The default is to stream over the entire sequence. let sv = make(); let stream = make(, contents: sv, direction: #"output"); write(stream,#(1, 2, 3, 4, 5, 6, 7, 8, 9)); write(stream,"ABCDEF"); values(sv, stream-contents(stream)); 
make(<string-stream>) Method

Creates and opens a stream over a string.

Signature: make string-stream-class #key contents direction start end => string-stream-instance string-stream-class – The class . contents (#key) – An instance of . direction (#key) – One of #"input", #"output", or #"input-output". Default value: #"input". start (#key) – An instance of . Default value: 0. end (#key) – An instance of . Default value: contents.size. string-stream-instance – An instance of . Creates and opens a stream over a string. This method returns an instance of . If supplied, contents describes the contents of the stream. The direction, start, and end init-keywords are as for make on . let stream = make(, contents: "here is a sequence"); 
make(<unicode-string-stream>) Method

Creates and opens a stream over a Unicode string.

Signature: make unicode-string-stream-class #key contents direction start end => unicode-string-stream-instance unicode-string-stream-class – The class . contents (#key) – An instance of . direction (#key) – One of #"input", #"output", or #"input-output". Default value: #"input". start (#key) – An instance of . Default value: 0. end (#key) – An instance of . Default value: contents.size. unicode-string-stream-instance – An instance of . Creates and opens a stream over a Unicode string. This method returns a new instance of . If supplied, contents describes the contents of the stream, and must be an instance of . The direction, start, and end init-keywords are as for make on .
new-line Open Generic function

Writes a newline sequence to an output stream.

Signature: new-line output-stream => () output-stream – An instance of . Writes a newline sequence to output-stream. A method for new-line is defined on  that writes the character \n to the string stream.
outer-stream Open Generic function

Returns a stream’s wrapper stream.

Signature: outer-stream stream => wrapping-stream stream – An instance of . wrapping-stream – An instance of . Returns the stream that is wrapping stream.
outer-stream-setter Open Generic function

Sets a stream’s wrapper stream.

Signature: outer-stream-setter wrapper-stream stream => wrapper-stream wrapper-stream – An instance of . stream – An instance of . wrapper-stream – An instance of . Sets the outer-stream slot of stream to wrapper-stream. Note Applications should not set inner-stream and outer-stream slots directly. The outer-stream-setter function is for use only when implementing stream classes.
peek Open Generic function

Returns the next element of a stream without advancing the stream position.

Signature: peek input-stream #key on-end-of-stream => element-or-eof input-stream – An instance of . on-end-of-stream (#key) – An instance of 
<positionable-stream> Open Abstract Class

The class of positionable streams.

Superclasses:  See Superclasses. A subclass of  supporting the Positionable Stream Protocol. It is not instantiable.
<position-type> Type
Type: A type representing positions in a stream. type-union(, ) None. A type used to represent a position in a stream. In practice, positions within a stream are defined as instances of , but this type, together with the  class, allows for cases where this might not be possible.
read Open Generic function

Reads a number of elements from an input stream.

Signature: read input-stream n #key on-end-of-stream => sequence-or-eof input-stream – An instance of . n – An instance of . on-end-of-stream (#key) – An instance of 
read-element Open Generic function

Reads the next element in a stream.

Signature: read-element input-stream #key on-end-of-stream => element-or-eof input-stream – An instance of . on-end-of-stream (#key) – An instance of 
read-into! Open Generic function

Reads a number of elements from a stream into a sequence.

Signature: read-into! input-stream n sequence #key start on-end-of-stream => count-or-eof input-stream – An instance of . n – An instance of . sequence – An instance of . start (#key) – An instance of . on-end-of-stream (#key) – An instance of 
read-line Open Generic function

Reads a stream up to the next newline.

Signature: read-line input-stream #key on-end-of-stream => string-or-eof newline? input-stream – An instance of . on-end-of-stream (#key) – An instance of 
read-line-into! Open Generic function

Reads a stream up to the next newline into a string.

Signature: read-line-into! input-stream string #key start on-end-of-stream grow? => string-or-eof newline? input-stream – An instance of . string – An instance of . start (#key) – An instance of . Default value: 0. on-end-of-stream (#key) – An instance of 
read-through Generic function

Returns a sequence containing the elements of the stream up to, and including, the first occurrence of a given element.

Signature: read-through input-stream element #key on-end-of-stream test => sequence-or-eof found? input-stream – An instance of . element – An instance of 
read-to Generic function

Returns a sequence containing the elements of the stream up to, but not including, the first occurrence of a given element.

Signature: read-to input-stream element #key on-end-of-stream test => sequence-or-eof found? input-stream – An instance of . element – An instance of 
read-to-end Generic function

Returns a sequence containing all the elements up to, and including, the last element of the stream.

Signature: read-to-end input-stream => sequence input-stream – An instance of . sequence – An instance of . Returns a sequence of all the elements up to, and including, the last element of input-stream, starting from the stream’s current position. The type of the result sequence is as described for read. There is no special end-of-stream behavior; if the stream is already at its end, an empty collection is returned. read-to-end(make(, contents: "hello there, world", start: 6, end: 11)); 
<sequence-stream> Open Class

The class of streams over sequences.

Superclasses:  contents – A general instance of  which is used as the input for an input stream, and as the initial storage for an output stream. direction – Specifies the direction of the stream. It must be one of #"input", #"output", or #"input-output". Default value: #"input". start – An instance of . This specifies the start position of the sequence to be streamed over. Only valid when direction: is #"input". Default value: 0. end – An instance of . This specifies the sequence position immediately after the portion of the sequence to stream over. Only valid when direction: is #"input". Default value: contents.size. The class of streams over sequences. It is a subclass of . If contents: is a stretchy vector, then it is the only storage used by the stream. The  class can be used for streaming over all sequences, but there are also subclasses , , and , which are specialized for streaming over strings. The start: and end: init-keywords specify the portion of the sequence to create the stream over: start: is inclusive and end: is exclusive. The default is to stream over the entire sequence.
skip-through Generic function

Skips through an input stream past the first occurrence of a given element.

Signature: skip-through input-stream element #key test => found? input-stream – An instance of . element – An instance of 
<stream> Open Abstract Class

The superclass of all stream classes.

Superclasses: 
stream-at-end? Open Generic function

Tests whether a stream is at its end.

Signature: stream-at-end? stream => at-end? stream – An instance of . at-end? – An instance of . Returns #t if the stream is at its end and #f if it is not. For input streams, it returns #t if a call to read-element with no supplied keyword arguments would signal an . This function differs from stream-input-available?, which tests whether the stream can be read. For output-only streams, this function always returns #f. For output streams, note that you can determine if a stream is one place past the last written element by comparing stream-position to stream-size. The following piece of code applies function to all the elements of a sequence: let stream = make(, contents: seq); while (~stream-at-end?(stream)) function(read-element(stream)); end; 
stream-contents Open Generic function

Returns a sequence containing all the elements of a positionable stream.

Signature: stream-contents positionable-stream #key clear-contents? => sequence positionable-stream – An instance of . clear-contents? (#key) – An instance of . Default value: #t. sequence – An instance of . Returns a sequence that contains all of positionable-stream ‘s elements from its start to its end, regardless of its current position. The type of the returned sequence is as for read. The clear-contents? argument is only applicable to writeable sequence streams, and is not defined for file-streams or any other external stream. It returns an error if applied to an input only stream. If clear-contents? is #t (the default for cases where the argument is defined), this function sets the size of the stream to zero, and the position to the stream’s start. Thus the next call to stream-contents will return only the elements written after the previous call to stream-contents. Note that the sequence returned never shares structure with any underlying sequence that might be used in the future by the stream. For instance, the string returned by calling stream-contents on an output  will not be the same string as that being used to represent the string stream. The following forms bind stream to an output stream over an empty string and create the string “I see!”, using the function stream-contents to access all of the stream’s elements. let stream = make(, direction: #"output"); write-element(stream, 'I'); write-element(stream, ' '); write(stream, "see"); write-element(stream, '!'); stream-contents(stream); 
stream-element-type Open Generic function

Returns the element-type of a stream.

Signature: stream-element-type stream => element-type stream – An instance of . element-type – An instance of . Returns the element type of stream as a Dylan .
stream-input-available? Open Generic function

Tests if an input stream can be read.

Signature: stream-input-available? input-stream => available? input-stream – An instance of . available? – An instance of . Returns #t if input-stream would not block on read-element, otherwise it returns #f. This function differs from stream-at-end?. When stream-input-available? returns #t, read-element will not block, but it may detect that it is at the end of the stream’s source, and consequently inspect the on-end-of-stream argument to determine how to handle the end of stream.
stream-console? Open Generic function

Tests whether a stream is directed to the console.

Signature: stream-console? stream => console? stream – An instance of . console? – An instance of . Returns #t if the stream is directed to the console and #f if it is not. The following piece of code tests whether stdout has been directed to the console (./example), or to a file (./example > file): if (stream-console?(*standard-output*)) format-out("Output is directed to the console\n") else format-out("Output is not directed to the console\n") end if; 
stream-lock Open Generic function

Returns the lock for a stream.

Signature: stream-lock stream => lock stream – An instance of . lock – An instance of , or #f. Returns lock for the specified stream. You can use this function, in conjunction with stream-lock-setter to implement a basic stream locking facility.
stream-lock-setter Open Generic function

Sets a lock on a stream.

Signature: stream-lock-setter stream lock => lock stream – An instance of . lock – An instance of , or #f. lock – An instance of , or #f. Sets lock for the specified stream. If lock is #f, then the lock on stream is freed. You can use this function in conjunction with stream-lock to implement a basic stream locking facility.
stream-open? Open Generic function

Generic function for testing whether a stream is open.

Signature: stream-open? stream => open? stream – An instance of . open? – An instance of . Returns #t if stream is open and #f if it is not.
stream-position Open Generic function

Finds the current position of a positionable stream.

Signature: stream-position positionable-stream => position positionable-stream – An instance of . position – An instance of . Returns the current position of positionable-stream for reading or writing. The value returned can be either an instance of  or an integer. When the value is an integer, it is an offset from position zero, and is in terms of the stream’s element type. For instance, in a Unicode stream, a position of four means that four Unicode characters have been read. The following example uses positioning to return the character “w” from a stream over the string "hello world": let stream = make(, contents: "hello world"); stream-position(stream) := 6; read-element(stream); 

<position-type>

<stream-position> Abstract Class

The class representing non-integer stream positions.

Superclasses: 
stream-position-setter Open Generic function

Sets the position of a stream.

Signature: stream-position-setter position positionable-stream => new-position position – An instance of . positionable-stream – An instance of . new-position – An instance of , or an instance of . Changes the stream’s position for reading or writing to position. When it is an integer, if it is less than zero or greater than positionable-stream.stream-size this function signals an error. For file streams, a  is signalled. For other types of stream, the error signalled is . When position is a , if it is invalid for some reason, this function signals an error. Streams are permitted to restrict the position to being a member of the set of values previously returned by calls to stream-position on the same stream. The position may also be #"start", meaning that the stream should be positioned at its start, or #"end", meaning that the stream should be positioned at its end. Note You cannot use stream-position-setter to set the position past the current last element of the stream: use adjust-stream-position instead.
stream-size Open Generic function

Finds the number of elements in a stream.

Signature: stream-size positionable-stream => size positionable-stream – An instance of . size – An instance of , or #f. Returns the number of elements in positionable-stream. For input streams, this is the number of elements that were available when the stream was created. It is unaffected by any read operations that might have been performed on the stream. For output and input-output streams, this is the number of elements that were available when the stream was created (just as with input streams), added to the number of elements written past the end of the stream (regardless of any repositioning operations). It is assumed that: There is no more than one stream open on the same source or destination at a time. There are no shared references to files by other processes. There are no alias references to underlying sequences, or any other such situations. In such situations, the behavior of stream-size is undefined.
<string-stream> Open Instantiable Class

The class of streams over strings.

Superclasses:  contents – A general instance of . direction – Specifies the direction of the stream. It must be one of #"input", #"output", or #"input-output"; Default value: #"input". start – An instance of . Only valid when direction: is #"input". Default value: 0. end – An instance of . This specifies the string position immediately after the portion of the string to stream over. Only valid when direction: is #"input". Default value: contents.size. The class of streams over strings. The contents: init-keyword is used as the input for an input stream, and as the initial storage for an output stream. The start: init-keyword specifies the start position of the string to be streamed over. The class supports the same init-keywords as . The start: and end: init-keywords specify the portion of the string to create the stream over: start: is inclusive and end: is exclusive. The default is to stream over the entire string.
synchronize-output Open Generic function

Synchronizes an output stream with the application state.

Signature: synchronize-output output-stream => () output-stream – An instance of . Forces any pending output from output-stream’s buffers to its destination. Before returning to its caller, synchronize-output also attempts to ensure that the output reaches the stream’s destination before, thereby synchronizing the output destination with the application state. When creating new stream classes it may be necessary to add a method to the synchronize-output function, even though it is not part of the Stream Extension Protocol.
type-for-file-stream Open Generic function

Finds the type of file-stream class that needs to be instantiated for a given file.

Signature: type-for-file-stream filename element-type #rest #all-keys => file-stream-type filename – An instance of 
type-for-sequence-stream Open Generic function

Finds the type of sequence-stream class that needs to be instantiated for a given sequence.

Signature: type-for-sequence-stream sequence => sequence-stream-type sequence – An instance of . sequence-stream-type – An instance of . Returns the sequence-stream class to instantiate over a given sequence object. The method for make() calls this function to determine the concrete subclass of  that it should instantiate. There are type-for-sequence-stream methods for each of the string object classes. These methods return a stream class object that the Streams module considers appropriate.
<unicode-character> Type
Type: The type that represents Unicode characters.  A type representing Unicode characters that instances of  can contain.
<unicode-string-stream> Open Instantiable Class

The class of streams over Unicode strings.

Superclasses:  contents – A general instance of . direction – Specifies the direction of the stream. It must be one of #"input", #"output", or #"input-output". Default value: #"input". start – An instance of . This specifies the start position of the sequence to be streamed over. Only valid when direction: is #"input". Default value: 0. end – An instance of . This specifies the sequence position immediately after the portion of the sequence to stream over. Only valid when direction: is #"input". Default value: contents.size. The class of streams over Unicode strings. It is a subclass of . The contents: init-keyword is used as the input for an input stream, and as the initial storage for an output stream. If it is a stretchy vector, then it is the only storage used by the stream. The class supports the same init-keywords as . The start: and end: init-keywords specify the portion of the Unicode string to create the stream over: start: is inclusive and end: is exclusive. The default is to stream over the entire Unicode string.
unlock-stream Open Generic function

Unlocks a stream.

Signature: unlock-stream stream stream – An instance of . Unlocks a stream. It is suggested that with-stream-locked be used instead of direct usages of lock-stream and unlock-stream. See Locking streams for more detail and discussion on using streams from multiple threads.
unread-element Open Generic function

Returns an element that has been read back to a positionable stream.

Signature: unread-element positionable-stream element => element positionable-stream – An instance of . element – An instance of 
wait-for-io-completion Generic function

Waits for all pending operations on a stream to complete.

Signature: wait-for-io-completion file-stream => () file-stream – An instance of . If file-stream is asynchronous, waits for all pending write or close operations to complete and signals any queued errors. If file-stream is not asynchronous, returns immediately.
with-indentation Statement Macro
Macro Call: with-indentation (*stream*) *body* end;  with-indentation (*stream*, 4) *body* end;  stream – A Dylan expression bnf. An instance of . indentation – A Dylan expression bnf. An instance of . Optional. body – A Dylan body bnf. Runs a body of code with an indentation level managed automatically. This avoids the need to call indent to indent and then unindent around the body of code. with-indentation(is, 4) format(is, "Hello %=\n", name); end with-indentation; 
with-open-file Statement Macro

Runs a body of code within the context of a file stream.

Macro Call: with-open-file (*stream-var* = *filename*, #rest *keys*) *body* end => *values*  stream-var – An Dylan variable-name bnf. filename – An instance of . keys – Instances of 
with-stream-locked Statement Macro

Run a body of code while the stream is locked.

Macro Call: with-stream-locked (*stream-var*) *body* end => *values*  stream-var – An Dylan variable-name bnf. body – A Dylan body bnf. values – Instances of 
<wrapper-stream> Open Instantiable Class

The class of wrapper-streams.

Superclasses:  inner-stream – An instance of . The class that implements the basic wrapper-stream functionality. It takes a required init-keyword inner-stream:, which is used to specify the wrapped stream. The  class implements default methods for all of the stream protocol functions described in this document. Each default method on  simply “trampolines” to its inner stream. In the example below, , a subclass of , “passes on” functions such as read-element and write-element by simply delegating these operations to the inner stream: define method read-element (ws :: , #key on-end-of-stream) => (element) read-element(ws.inner-stream) end method; define method write-element (ws :: , element) => () write-element(ws.inner-stream, element) end method;  Assuming that  delegates all other operations to its inner stream, the following is sufficient to implement a 16-bit Unicode character stream wrapping an 8-bit character stream. define class () end class; define method read-element (s :: , #key on-end-of-stream) => (ch :: ) let first-char = read-element(s.inner-stream, on-end-of-stream); let second-char = read-element(s.inner-stream, on-end-of-stream); convert-byte-pair-to-unicode(first-char, second-char) end method; define method write-element (s :: , c :: ) => () let (first-char, second-char) = convert-unicode-to-byte-pair(c); write-element(s.inner-stream, first-char); write-element(s.inner-stream, second-char) c end method; define method stream-position (s :: ) => (p :: ) truncate/(stream-position(s.inner-stream), 2) end method; define method stream-position-setter (p :: , s :: ); stream-position(s.inner-stream) := p * 2 end method; 
write Open Generic function

Writes the elements of a sequence to an output stream.

Signature: write output-stream sequence #key start end => () output-stream – An instance of . sequence – An instance of . start (#key) – An instance of . Default value: 0. end (#key) – An instance of . Default value: sequence.size. Writes the elements of sequence to output-stream, starting at the stream’s current position. The elements in sequence are accessed in the order defined by the forward iteration protocol on . This is effectively the same as the following: do (method (elt) write-element(stream, elt) end, sequence); sequence;  If supplied, start and end delimit the portion of sequence to write to the stream. The value of start is inclusive and that of end is exclusive. If the stream is positionable, and it is not positioned at its end, write overwrites elements in the stream and then advances the stream’s position to be beyond the last element written. Implementation Note: Buffered streams are intended to provide a very efficient implementation of write, particularly when sequence is an instance of , , , or , and the stream’s element type is the same as the element type of sequence. The following forms bind stream to an output stream over an empty string and create the string “I see!”, using the function stream-contents to access all of the stream’s elements. let stream = make(, direction: #"output"); write-element(stream, 'I'); write-element(stream, ' '); write(stream, "see"); write-element(stream, '!'); stream-contents(stream); 
write-element Open Generic function

Writes an element to an output stream.

Signature: write-element output-stream element => () output-stream – An instance of . element – An instance of 
write-line Open Generic function

Writes a string followed by a newline to an output stream.

Signature: write-line output-stream string #key start end => () output-stream – An instance of . string – An instance of . start (#key) – An instance of . Default value: 0. end (#key) – An instance of . Default value: string.size. Writes string followed by a newline sequence to output-stream. The default method behaves as though it calls write on string and then calls new-line`. If supplied, start and end delimit the portion of string to write to the stream.