The Standard ML Basis Library

The `TextIO` structure

TextIO provides input/output of characters and strings. The stream operations themselves are all defined in the IMPERATIVE_IO signature.

The openIn and openOut functions allow creation of text streams. Certain operating systems may provide other ways to open files in operating-system-specific structures.

The signature given below for TEXT_IO is not valid SML, in that the substructure StreamIO is respecified. (It is initially specified as a substructure having signature STREAM_IO in the included signature IMPERATIVE_IO having signature.) This abuse of notation seems acceptable in that the intended meaning is clear (a structure matching TEXT_IO also matches IMPERATIVE_IO and has a substructure StreamIO that matches TEXT_STREAM_IO) while avoiding a textual inclusion of the whole IMPERATIVE_IO signature except its StreamIO substructure.

Question:

Need note describing newline translation.

Synopsis

signature TEXT_IO structure TextIO : TEXT_IO

Interface

include IMPERATIVE_IO structure StreamIO : TEXT_STREAM_IO val inputLine : instream -> string val outputSubstr : (outstream * substring) -> unit val openIn : string -> instream val openOut : string -> outstream val openAppend : string -> outstream val openString : string -> instream val stdIn : instream val stdOut : outstream val stdErr : outstream val print : string -> unit

Description

include IMPERATIVE_IO

structure StreamIO

inputLine strm

Read one line from strm and return it. If strm is not at end of file, the result ends with a newline character. If it is the last line of the file and the file ends without a trailing newline, stick the newline on anyway. If at end of file, return the empty string. Raises Size if the length of the line exceeds the length of the longest string.

outputSubstr (strm, ss)

outputs the substring ss to the text stream strm. This is equivalent to:

          output (strm, Substring.string ss)

openIn name

openOut name

Open the file named name for input and output, respectively. If name is a relative pathname, the file opened depends on the current working directory. On openOut, the file is created if it does not already exist and truncated to length zero otherwise. Raises Io if a stream cannot be opened on the given file, or in the case of openIn, the file name does not exist.

openAppend name

opens the file named name for output in append mode, creating it if it does not already exist. If the file already exists, set position at end of file. Raises Io if a stream cannot be opened on the given file.

Beyond having the initial file position be at the end of the file, any additional properities are system and implementation dependent. On operating systems (e.g., Unix) that support ``atomic append mode,'' each (flushed) output operation to the file will be appended to the end, even if there are other processes writing to the file simultaneously. However, due to buffering, these writes need not be atomic, i.e., output from a different process may interleave the output of a single write using the stream library.

openString s

creates an input stream whose content is s.

val stdIn

val stdOut

val stdErr

These correspond to the standard input, output and error streams, respectively.

Question:

Should these also be defined at the TEXT_STREAM_IO level?

print s

prints the string s to the standard output stream and flushes the stream. This is equivalent to:

          (output (stdOut, s); flushOut stdOut)

Discussion

When opening a stream for writing, the stream will be block buffered by default, unless the underlying file is associated with an interactive or terminal device (i.e., the kind of the underlying iodesc is OS.IO.Kind.tty), in which case the stream will be line buffered. Similarly, stdOut will be line buffered in the interactive case, but may be block buffered otherwise. stdErr is initially unbuffered.