This chapter has been superseded by the standard basis library. The functions in the BasicIO structure are still available in the SML90 structure but where possible the TextIO structure should be used instead.
The structure BasicIO provides basic I/O facilities as prescribed by the ML Standard. These are:
type instream
type outstream
val std_in: instream
val std_out: outstream
val input: instream * int -> string
val output: outstream * string -> unit
val open_in: string -> instream
val open_out: string -> outstream
val close_in: instream -> unit
val close_out: outstream -> unit
val lookahead: instream -> string
val end_of_stream: instream -> bool
exception Io of string
All of the above functions are also available directly at the top-level as they form part of the Initial Basis; it is not necessary to open the structure BasicIO in order to use them.
The type instream is the type of input streams; outstream corresponds to output streams. Essentially, anything belonging to either of these types is a file descriptor.
The two values std_in and std_out are predefined streams, corresponding to the keyboard and terminal respectively (unless redirected by Unix).
output(std_out,"hello world\n");
will write the string 'hello world' on the terminal.
input(std_in,n);
will read n characters from the terminal, returning them as a string. If fewer than n characters are available, the function will wait for more input, unless <control-D> (or whatever is the local end-of-file indicator) is typed, in which case the function will return however many characters are available.
Calling open_in "myfile" will open the Unix file myfile for input, returning the file-descriptor. The function open_out is used to create new output streams; again the string is a Unix file name. close_in and close_out are the corresponding 'close' functions.
The function end_of_stream is used to detect the end of an input stream; end_of_stream is returns true when no further input is possible on the input stream is.
If the stream is has terminated, then lookahead is returns the empty string. Otherwise it returns a one-character string, containing the next character to be read from the stream without removing the character from the stream.
The exception Io is raised when an impossible I/O operation is attempted; for example, trying open_in "bad" if no file bad exists.
The structure ExtendedIO provides some non-standard (but very useful) I/O facilities. These are:
val is_term_in : instream -> bool
val is_term_out : outstream -> bool
val open_append : string -> outstream
val can_input : instream * int -> bool
val input_line : instream -> string
val flush_out : outstream -> unit
val execute : string -> instream * outstream
The functions ExtendedIO.is_term_in and ExtendedIO.is_term_out test whether the supplied input or output streams are currently connected to a terminal.
The function ExtendedIO.open_append is similar to BasicIO.open_out except that the stream is opened in 'append' mode; if the named file already exists then subsequent output is appended to it, instead of replacing it.
ExtendedIO.can_input(is,n);
returns true if n characters are immediately available to be read from the input stream is.
The function ExtendedIO.input_line reads characters from an input stream until a newline or the end of file is reached. In the first case the returned string will end with a newline.
ExtendedIO.flush_out os writes out any buffered data for the output stream os. BasicIO.close_out performs an ExtendedIO.flush_out before closing an outstream. By default, an outstream connected to a terminal will be line-buffered, whilst an outstream connected to a file or pipe is block-buffered.
ExtendedIO.execute creates a child Unix process with the stdin of the child connected to the outstream, and the stdout of the child connected to the instream via pipes. The string is the name of the command to execute. For example:
> val (is,os) = ExtendedIO.execute
"date";
val is = ? : instream val os = ? : outstream
> ExtendedIO.input-line is;
> val it = "Thu Jun 4 09:33:37 BST 1999\n" : string
Copyright (c) 2000 CUTS and contributers. Last updated: 15 January 2002 by David Matthews.