The Standard ML Basis Library

The IMPERATIVE_IO signature

The IMPERATIVE_IO signature defines the interface of the Imperative IO layer in the IO stack. This layer provides buffered IO using mutable streams.

Synopsis

signature IMPERATIVE_IO


Interface

structure StreamIO : STREAM_IO
type vector = StreamIO.vector
type elem = StreamIO.elem
type instream
type outstream
val input : instream -> vector
val input1 : instream -> elem option
val inputN : (instream * int) -> vector
val inputAll : instream -> vector
val canInput : (instream * int) -> int option
val lookahead : instream -> elem option
val closeIn : instream -> unit
val endOfStream : instream -> bool
val output : (outstream * vector) -> unit
val output1 : (outstream * elem) -> unit
val flushOut : outstream -> unit
val closeOut : outstream -> unit
val getPosIn : instream -> StreamIO.in_pos
val setPosIn : (instream * StreamIO.in_pos) -> unit
val mkInstream : StreamIO.instream -> instream
val getInstream : instream -> StreamIO.instream
val setInstream : (instream * StreamIO.instream) -> unit
val getPosOut : outstream -> StreamIO.out_pos
val setPosOut : (outstream * StreamIO.out_pos) -> unit
val mkOutstream : StreamIO.outstream -> outstream
val getOutstream : outstream -> StreamIO.outstream
val setOutstream : (outstream * StreamIO.outstream) -> unit


Description

structure StreamIO

This substructure provides lower-level stream I/O, as defined by the STREAM_IO interface, that is compatible with the instream and outstream, in the sense that the conversion functions mkInstream, getInstream, mkOutstream and getOutstream allow the programmer to convert between low-level streams and redirectable streams. Typically, the redirectable streams are implemented in terms of low-level streams. Note that StreamIO.outstream is not a functional stream. The only difference between a StreamIO.outstream and an outstream is that the latter is redirectable.

type vector

type elem

These are the abstract types of stream elements and vectors of elements. For text streams, these are Char.char and String.string, while for binary streams, these are Word8.word and Word8Vector.vector.

type instream

The type of redirectable imperative input streams. Two imperative streams may share an underlying functional stream or reader. Closing one of them effectively closes the underlying functional stream, which will affect subsequent operations on the other.

type outstream

The type of redirectable output streams. Two redirectable streams may share an underlying stream or writer. If this is the case, writing or positioning the file pointer on one of them, or closing it, also affects the other.

input strm

attempts to read from strm, starting from the current input file position. When elements are available, returns a vector of at least one element. When strm is at end-of-stream or is closed, returns an empty vector. Otherwise, input blocks until one of these conditions is met, and returns accordingly. May raise the exception Io.

input1 strm

reads one element from strm. Returns SOME e if one element was available; returns NONE if at end-of-stream. May block, and may raise the exception Io.

inputN (strm, n)

reads at most n elements from strm. Returns a vector containing n elements if at least n elements are available before end-of-stream; returns a shorter (and possibly empty) vector of all elements remaining before end-of-stream otherwise. May block, and may raise the exception Io. Raises Size if n < 0 or n > maxLen.

inputAll strm

returns all elements of strm up to end-of-stream. May block, and may raise the exception Io. Raises Size if the amount of data exceeds the maxLen of the vector type.

canInput (strm, n)

returns NONE if any attempt at input would block. Returns SOME k, where 0 <= k <= n, if a call to input would return immediately with k characters. Note that k = 0 corresponds to the stream being at end-of-stream.

Some streams may not support this operation, in which case the Io exception will be raised. This function also raises the Io exception if there is an error in the underlying system calls. It raises the Size exception if n < 0.

Implementation note:

Implementations of canInput should attempt to return as large a k as possible. For example, if the buffer contains 10 characters and the user calls canInput (f, 15), canInput should call readVecNB 5 to see if an additional 5 characters are available.

lookahead strm

determines whether one element is available on strm before end-of-stream and returns SOME e in this case; returns NONE if at end-of-stream. In the former case, e is not removed from strm but stays available for further input operations. May block, and may raise the exception Io.

Note that arbitrary lookahead can be easily implemented using the underlying stream.

closeIn strm

closes the instream strm, freeing resources of the underlying I/O layers associated with it. A closeIn applied to an already closed stream will be ignored. Other operations on a closed stream will behave as if the stream is at end-of-stream. The function is implemented in terms of S.closeIn. It may also raise Io when another error occurs.

endOfStream strm

returns true if strm is at end-of-stream, and false if elements are still available. May block until one of these conditions is determined, and may raise the exception Io. Note: When endOfStream returns true on an unterminated stream, this denotes the current situation. When further data are appended to the underlying file or stream, the next call to endOfStream will return false, and input operations will deliver new elements.

output (strm, vec)

attempts to write the contents of vec to strm, starting from the current output file position. May block until the underlying stream layers (and eventually the operating system) can accept all of vec. May raise the exception Io. In that case, it is unspecified how much of vec was actually written.

output1 (strm, el)

outputs exactly one element el to strm. May block, and may raise the exception Io when an error occurred. In that case it is unspecified how much of el (if its physical representation is larger than just one byte) was actually written. At this level, more than this can not be guaranteed. Programs that need more control over this possibility need to make use of more primitive or OS-specific I/O routines.

flushOut strm

causes any stream buffers to be written out. Corresponds to S.flushOut. May block, and may raise the exception Io when an error occurs.

closeOut strm

closes the outstream strm, freeing resources of the underlying I/O layers associated with it. Implemented in terms of S.closeOut. A write attempt on a closed outstream will cause the exception Io{cause=ClosedStream,...} to be raised. May also raise Io when another error occurs (e.g., buffers can't be flushed out).

getPosIn strm

returns the current position in the stream strm.

setPosIn (strm, pos)

sets the current position of the stream strm to be pos.

mkInstream strm

constructs a redirectable instream from a functional one. The current version of strm returned by input operations will be kept internally and used for the next input. They can be obtained by getInstream.

getInstream strm

returns the current version of the underlying functional instream of strm. Using getInstream, it is possible to get input directly from the underlying functional stream. After having done so, it may be necessary to reassign the newly obtained functional stream to strm; otherwise that input will be read again when reading from strm the next time.

setInstream (strm, strm')

assigns a new functional stream strm' to strm. Future inputs on strm will be redirected to strm'. Useful for redirecting input or interleaving input from different streams, e.g., when handling nested include files in a lexer.

getPosOut strm

returns the current position in the stream strm.

setPosOut (strm, pos)

sets the current position of the stream strm to be pos.

mkOutstream strm

constructs a redirectable outstream from a low-level imperative one. Output to the imperative stream will be redirected to strm.

getOutstream strm

flushes strm and returns the underlying StreamIO.outstream. Using getOutstream, it is possible to write output directly to the underlying stream, or to save it and restore it after strm has been redirected.

setOutstream (strm, strm')

flushes the stream underlying strm, and then assigns a new low-level stream strm' to it. Future outputs on strm will be redirected to strm'.

See Also

TextIO, BinIO, STREAM_IO, ImperativeIO

Last Modified January 29, 1997
Comments to John Reppy.
Copyright © 1997 Bell Labs, Lucent Technologies