prolog_stream.pl -- A stream with Prolog callbacks

This library defines a Prolog stream that realises its low-level I/O with callbacks to Prolog. The library was developed to bind normal Prolog I/O to Pengines I/O. This type of I/O redirection is probably the primary use case.

 open_prolog_stream(+Module, +Mode, -Stream, +Options)

Create a new stream that implements its I/O by calling predicates in Module. The called predicates are:

Module:stream_write(+Stream, +String)

Called for a Mode = write stream if data is available. String contains the (textual) data that is written to Stream. The callback is called if the buffer of Stream overflows, the user calls flush_output(Stream) or Stream is closed and there is buffered data.

Module:stream_read(+Stream, -Term)

Called for a Mode == read stream to get new data. On success the stream extracts text from the provided Term. Term is typically a string, atom, code or character list. If term is not one of the above, it is handed to writeq/1. To signal end-of-file, unify stream with an empty text, e.g., stream_read(Stream, "").

Module:stream_close(+Stream)

Called when the stream is closed. This predicate must succeed. The callback can be used to cleanup associated resources.

The current implementation only deals with text streams. The stream uses the wchar_t encoding. The buffer size must be a multiple of wchar_t, i.e., a multiple of four for portability. The newline mode of the stream is posix on all platforms, disabling the translation "\n" --> "\r\n".

Arguments:

Options

- is currently ignored.

bug

- Futher versions might require additional callbacks. As we demand all callbacks to be defined, existing code needs to implement the new callbacks.