(*
    Title: 	general terminal handler for Unix
    LastEdit:	"Tue Feb 19 12:09:07 1985"
    Author: 	acm/jd/mjj
		Acorn Research Centre
*)

DEFINITION MODULE Terminal;

FROM Streams IMPORT Stream;

EXPORT QUALIFIED 
    ScBit, ScMode, NoBuff, NoTrans, HandsOff, Reflect, 
    CreateInOutput, CreateOutputForErrors, CreateStdInOutput, 
    StreamErrorCode, TranslateCR, DelProc, NullDelete;


(******* Unix data structure used for stty, gtty - see man 4 tty **********)

TYPE ScBit = (TANDEM, CBREAK, LCASE, ECHO, CRMOD, RAW);
    (* full definition of these bits in man 4 tty *)

TYPE ScMode = SET OF ScBit;

(* The following constants define what are probably the most useful settings
   of the terminal driver bits. You may of course create your own new and
   exciting combinations.
*)

CONST
    NoBuff      = ScMode {CBREAK, CRMOD};
                    (* like ordinary input except that no buffering is done.
                       CR is translated into LF, flow control is done, the
                       interrupt and kill characters work, but no reflection.
                    *)
    NoTrans     = ScMode {CBREAK};
                    (* as NoBuff, but no translation of CR into LF is done on
                       input, and no translation of CR or LF into CR-LF on
                       output, so watch it if you try to type one of these two
                       when a stream of this mode is selected for input!
                    *)
    HandsOff    = ScMode {RAW};
                    (* you are given all 8 bits with no interpretation at all.
                       This is the most useful mode, except that it has the
                       disadvantage that you can no longer kill a process from
                       the terminal. Terminal output is also 8-bits with no
                       translations whatsoever.
                    *)
    
    Reflect     = ScMode {ECHO};
                    (* a modifier which can be used with any mode to turn on
                       reflection: e.g. NoTrans + Reflect
                    *)

TYPE DelProc = PROCEDURE (Stream);

PROCEDURE NullDelete (s: Stream);
(* a null DelProc  *)

PROCEDURE StreamErrorCode(s: Stream): INTEGER;
(*  Returns OS error code in the event of an error.
*)

PROCEDURE CreateInOutput
    (mode: ScMode; translate: BOOLEAN; delete: DelProc): Stream;
(*  Returns a bi-directional stream to the terminal.
    Input is buffered at the level defined by the mode.
    Output is buffered until a NewLineCh, a call to Streams.FlushOut
    ,an input request on the stream, or a read or write to
    another stream handled by the module.
    IF translate is set to TRUE then carriage returns are translated
    on input & output. This may later be changed by calling
    TranslateCR. Normally want TRUE for SC stream, FALSE for
    buffered stream;
    The DelProc is a device so that whoever set up the stream
    can be told of its deletion if required. If this is not required
    then use NullDelete;
*)

PROCEDURE CreateStdInOutput (): Stream;
(*  as CreateInOutput, but sets standard terminal type with no translation
    and sets the delete proc to do nothing
*)

PROCEDURE CreateOutputForErrors(): Stream;
(*  Returns an unbuffered stream on which to output error messages.
    Whether this has the same destination as the output portion
    of the stream returned by CreateInOutput depends on the
    underlying operating system, which may also impose buffering.
    Only one instance of this stream is allowed; 
    repeated calls (without an intervening Delete)
    return the same stream handle.
*)

PROCEDURE TranslateCR (stream: Stream; yes: BOOLEAN);
(*  controls translation of carriage return into
    newline (line-feed).
    Translation occurs if 'yes= TRUE'.
    Normally want yes for a SC stream, 
    no for buffered stream.
*)

END Terminal .
