A stream defines a logical I/O channel which is used by built-in predicates to perform input and output on. A stream is identified by its name, which is an atom. Each logical stream is assigned to a physical stream. The physical streams, denoted by small integers, are directly connected to files, pipes etc. (the physical stream, however, has no relation to the UNIX file descriptor). Most of the built-in predicates that handle streams explicitly have the stream argument at the first position, e.g. write(Stream, Term).
NOTE: Although physical streams can be directly accessed and used, the ECLiPSe programs should not contain explicit references to physical streams, because the correspondence of logical and physical streams may not be maintained in various releases. In future ECLiPSe versions it might even not be possible to access physical streams directly.
It is possible to find the physical stream to which a logical stream is assigned. This is done by a call of the predicate get_stream/2:
get_stream(Logical_Stream, Stream)This call will return in Stream the physical stream to which the Logical_Stream is assigned, but it will also succeed if Stream is another logical stream associated to the same physical stream as Logical_Stream.
New physical streams are created by predicates open/3, pipe/2 (see also section 12.3). These predicates return the newly created stream(s) in their argument(s). If this argument is a free variable, the number of the new physical stream is returned, for instance
[eclipse 1]: open(new_file, write, Stream). Stream = 6 yes.If the stream argument is a stream name, new logical stream with that name is created if necessary, and the new physical stream is associated to it:
[eclipse 1]: open(new_file, write, new_stream). yes.It is also possible to assign a logical stream to an existing physical or logical stream using the predicate set_stream/2:
set_stream(New_Stream, Existing_Stream)Here the logical stream New_Stream has been assigned to the physical stream that is currently associated with Existing_Stream. A logical stream is always connected only to a physical stream, it is not possible to associate a logical stream to another logical stream so that changing one would change the other as well:
[eclipse 1]: set_stream(a, 0), set_stream(b, a), set_stream(a, 1). yes. [eclipse 2]: get_stream(a, A), get_stream(b, B). A = 1 B = 0 yes.The predicate
close(Stream)is used to close a stream. If the specified stream is a logical one, it is closed and if its associated physical stream is still open, it is closed as well. When a physical stream is closed and there are some logical streams associated to it, they are not closed, but they still refer to the closed physical stream and this physical stream cannot be used for another channel until all logical streams associated to it are redirected to other physical streams or closed.
The predicate
current_stream(?Stream)can be used to backtrack over all the currently opened streams. A stream's properties can be accessed using
get_stream_info(+Stream, +Property, -Value)e.g. its mode, line number, file name etc.