HELP STDIO R. J. Duncan, June 1989 Basic input/output in PML. CONTENTS - (Use g to access required sections) -- The StdIO Module -- I/O Stream Types -- I/O Exceptions -- Standard I/O Streams -- Functions on Input Streams -- Functions on Output Streams -- The StdIO Module --------------------------------------------------- signature StdIO structure StdIO : StdIO The structure -StdIO- defines the full set of I/O types, functions and exceptions required by the Standard ML language definition, Appendices C & D. This structure is open by default and the names it defines made "pervasive" so as to be visible everywhere. The -StdIO- module is described by the following signature: signature StdIO = sig (* I/O Stream Types *) type instream type outstream (* I/O Exception *) exception Io of string (* Standard I/O Streams *) val std_in : instream val std_out : outstream val std_err : outstream (* Functions on Input Streams *) val open_in : string -> instream val close_in : instream -> unit val input : instream * int -> string val input_line : instream -> string val lookahead : instream -> string val end_of_stream : instream -> bool val is_term_in : instream -> bool (* Functions on Output Streams *) val open_out : string -> outstream val open_append : string -> outstream val close_out : outstream -> unit val output : outstream * string -> unit val flush_out : outstream -> unit val is_term_out : outstream -> bool end; (* signature StdIO *) -- I/O Stream Types ---------------------------------------------------- type instream type outstream The central concept of I/O in ML is the stream: a sequence of characters which may or may not be finite, and if finite, which may or may not be terminated. Each input stream - or instream - has associated with it a character producer, usually a disk file or input device. Likewise, an output stream - outstream - has associated with it a character consumer. The stream transmits characters from the producer to a program, or from a program to the consumer; terminating the stream breaks the connection between the stream and its producer or consumer. -- I/O Exceptions ------------------------------------------------------ exception Io (s : string) Raised on any I/O failure: the string -s- describes the cause of the fault. Some particular cases are described below. -- Standard I/O Streams ------------------------------------------------ val std_in : instream An input stream whose producer is the input source of the PML process, typically the user's terminal. This stream may never be closed, although it may terminate if end-of-file is reached on the input. val std_out : outstream An output stream whose consumer is the output destination of the PML process, typically the user's terminal. This stream may never be closed. val std_err : outstream An output stream whose consumer is the error output destination of the PML process, typically the user's terminal. This stream may never be closed. -- Functions on Input Streams ----------------------------------------- val open_in (s : string) : instream Returns an instream whose producer is the file named -s-. The exception Io("Cannot open " ^ s) is raised if the file does not exist, or cannot be opened for reading. val close_in (is : instream) : unit Empties and terminates the instream -is-. Subsequent reads on the instream will return the empty string, "". val input (is : instream, n : int) : string Returns a string containing the next -n- characters from the instream -is-, removing them from the stream. If the stream is terminated with fewer than -n- characters remaining, then all the remaining characters are removed and returned. In particular, input on a terminated and empty stream returns the empty string, "". val input_line (is : instream) : string Returns a string containing characters from the instream -is- up to and including the next newline character, "\n". The characters returned are removed from the stream. If the stream is terminated with no newline character remaining, then all the remaining characters are removed and returned. In particular, input on a terminated and empty stream returns the empty string, "". val lookahead (is : instream) : string Returns a string containing the next character from the instream -is-. The character is not removed from the stream. If the stream is terminated and empty, -lookahead- returns the empty string, "". val end_of_stream (is : instream) : bool Returns -true- if the instream -is- is terminated and empty. Definition: fun end_of_stream is = lookahead is = "" val is_term_in (is : instream) : bool Returns -true- if the instream -is- is not terminated and its associated character producer is a terminal. -- Functions on Output Streams ---------------------------------------- val open_out (s : string) : outstream Returns an outstream whose consumer is the file named -s-. If the file -s- does not exist it is created, otherwise it is truncated to zero length. The exception Io("Cannot open " ^ s) is raised if the file cannot be opened for writing. val open_append (s : string) : outstream Returns an outstream whose consumer is the file named -s-. If the file -s- does not exist it is created, otherwise the existing contents of the file are preserved. The exception Io("Cannot open " ^ s) is raised if the file cannot be opened for writing. val close_out (os : outstream) : unit Terminates the outstream -os-. Any subsequent attempt to write on the outstream will raise an exception. val output (os : outstream, s : string) : unit Writes the characters in -s- to the outstream -os-. The exception Io("Output stream is closed") is raised if the stream is terminated. val flush_out (os : outstream) : unit Flushes any characters buffered by the consumer associated with the outstream -os-. val is_term_out (os : outstream) : bool Returns -true- if the outstream -os- is not terminated and its associated character consumer is a terminal. --- C.all/pml/help/stdio --- Copyright University of Sussex 1991. All rights reserved. ----------