========================================================
(C)1993 Institute for New Generation Computer Technology
(Read COPYRIGHT for detailed information.)
========================================================

IO Module
=========
December 2, 1993
Takashi Chikayama (ICOT)

This document describes a temporary version of the module "io".

Note: The current version of the module "io" is a temporary solution
to the requirements on input/output functionalities for KLIC.  It is
only a temporary solution: many features that should be implemented
are lacking, implemented features sometimes do not behave as they
should, and implementation efficiency is far from ideal.  Especially,
the module will not work well with parallel implementations.

Nevertheless, the module might be useful for programs running on
sequential versions of KLIC.


1. Obtaining I/O Message Streams

The module "io" interfaces other programs through message streams.
There are basically two kinds of message streams, input and output.
The following predicates defined in the module "io" can be used to
obtain such message streams.

 io:instream(S)
	An input message stream corresponding to the standard input is
	returned to S.
 io:instream(PathName, S)
	The file specified by the PathName is opened in read mode and
	an input message stream corresponding to that file stream is
	returned to S.  If a file with that pathname does not exist,
	the program will simply fail.
 io:outstream(S)
	An output message stream corresponding to the standard output
	is returned to S.
 io:outstream(PathName, S)
	The file specified by the PathName is opened in write mode and
	an output message stream corresponding to that file stream is
	returned to S.  If a file with that pathname does not exist, a
	new file is created.  If the directory path leading to that
	file does not exist, the program will fail.

The PathName argument for the above predicates should be written (in
the current version) as: string#"PATHNAME".  For example, if you are
to read the contents of the file "/etc/passwd", an input stream to
that file should be obtained by the following.

	io:instream(string#"/etc/passwd", S)

Actual I/O operations can be effected by instantiating the message
stream "S" obtained through the above predicates with a list of
messages described below.  For example, writing out the name of an
atom "a" to a file named "abc.out" followed by a full stop and a new
line can be done by the following.

	io:outstream(string#"abc.out", S),
	S = [print(a), putc(0'.), nl].

Note: For each call of io:outstream/2 or io:outstream/2, the file is
opened anew.  Thus, for example, doing the above writing out of "a"
twice will not result in a file with two lines.  The file is first
made with a single line, which is then overwritten with the same
contents.  You can pass around the cdr of the streams for multiple
outputs to a single file.


2. Common Messages

 sync(X)
	X is unified with integer 0 after all the messages preceding
	this message has been processed.


3. Messages to Input Streams

 getc(X)
	The next character is read from the input stream and its
	character code is unified with X as an integer value.


4. Messages to Output Streams

 putc(X)
	Character whose code is X is written to the output stream.
	Processing of this message is suspended until X is
	instantiated.  Note that, output will be bufferred.  Use the
	flush message described below to flush out the buffer.
 nl
	A newline character is written to the output stream.
 flush
	Any bufferred output to the output stream will be actually
	written out.
 print(X)
	Any term X is written out to the output stream.  Processing of
	this message is suspended until X is completedly instantiated
	to a ground value.


5. When the Stream is Closed

When an input or an output stream is closed and the file stream
corresponding to that message stream is not standard input nor
standard output, the file is closed.


6. Bugs

- The whole KLIC process will suspend when input value is not
  available yet.

- More powerful term I/O is required.
