DEFINITION MODULE IOChan;
(* A channel abstraction over the runtime streams and files (an
   ISO-style ChanId).  ChanId is opaque: the standard channels wrap
   stdio streams, and OpenRead/OpenWrite wrap a file.  A failed open
   returns a closed channel (IsOpen = FALSE); operations on a closed
   channel are safe no-ops (ReadChar returns 0C). *)

FROM SYSTEM IMPORT ADDRESS;

TYPE ChanId;

(* --- standard channels --- *)
PROCEDURE StdInChan() : ChanId;
PROCEDURE StdOutChan() : ChanId;
PROCEDURE StdErrChan() : ChanId;

(* --- file channels --- *)
PROCEDURE OpenRead(VAR name : ARRAY OF CHAR) : ChanId;
PROCEDURE OpenWrite(VAR name : ARRAY OF CHAR) : ChanId;
PROCEDURE Close(VAR cid : ChanId);
PROCEDURE IsOpen(cid : ChanId) : BOOLEAN;

(* --- bridging (for libraries layered on channels, e.g. Files) --- *)
PROCEDURE Handle(cid : ChanId) : ADDRESS;
(* The underlying runtime handle of cid (NIL for a closed channel). *)
PROCEDURE MakeChan(h : ADDRESS) : ChanId;
(* Wraps a runtime handle as a ChanId (NIL yields a closed channel). *)

(* --- operations --- *)
PROCEDURE ReadChar(cid : ChanId) : CHAR;
PROCEDURE ReadString(cid : ChanId; VAR s : ARRAY OF CHAR);  (* one line *)
PROCEDURE ReadInt(cid : ChanId) : INTEGER;

PROCEDURE WriteChar(cid : ChanId; c : CHAR);
PROCEDURE WriteString(cid : ChanId; VAR s : ARRAY OF CHAR);
PROCEDURE WriteInt(cid : ChanId; n : INTEGER);
PROCEDURE WriteLn(cid : ChanId);

(* --- positioning (seekable channels) --- *)
PROCEDURE Position(cid : ChanId) : INTEGER;
(* Current byte offset (-1 when unknown/closed). *)
PROCEDURE Seek(cid : ChanId; pos : INTEGER) : BOOLEAN;
(* Absolute seek; FALSE on failure. *)
PROCEDURE Rewind(cid : ChanId) : BOOLEAN;
(* Seek to offset 0. *)

END IOChan.