(*
    Title: 	TextIO - Definitions
    LastEdit:	"Mon Sep 17 14:39:04 1984"
    Author: 	Mick Jordan
		Acorn Research Centre

    This module provides a minimal set of procedures
    for inputing and outputing basic language types,
    plus the SystemTypes.STRING type.
*)

DEFINITION MODULE TextIO;
IMPORT SystemTypes; FROM SystemTypes IMPORT String;
FROM Streams IMPORT Stream;

EXPORT QUALIFIED 
    NumberBase,
    ReadCHAR, ReadINTEGER, ReadCARDINAL, ReadBOOLEAN,
    ReadREAL, ReadChars, ReadString, WhiteSpace, EndOfLine, TermProc,
    ReadBasedCARDINAL, ReadBITSET,
    WriteCHAR, NewLine, WriteINTEGER, WriteCARDINAL, WriteBOOLEAN, 
    WriteREAL, WriteBasedCARDINAL, WriteChars, WriteString, WriteBITSET;

TYPE NumberBase = SystemTypes.NumberBase;
(*  re-exported for convenience
*)

(*    
    On output, the characters are placed on the stream
    given as first argument by Streams.Put.
    On input, characters are taken off the stream
    given as first argument, with Streams.Get.

    The procedures ReadINTEGER, ReadCARDINAL,
    ReadBOOLEAN, ReadREAL, ReadBasedCARDINAL and ReadBITSET
    skip all leading whitespace (spaces, tabs, newlines, form-feeds),
    and terminate reading when any character outside the range
    defined by the radix is encountered.  If no valid characters
    are found, the result is 0 for numbers, FALSE for booleans
    and {} for bitsets, and the last character is put back on the stream.  
    ReadChars and ReadString do not skip any characters.
    
    All input routines put any additional character read, but not part
    of the object, back on the stream with Streams.Backspace.

    Signed numbers are only accepted by ReadINTEGER and ReadREAL.
    
    The format of objects is as follows.
    [] signifies optional things and | alternatives.

    Type            Input               Output    
    ----            -----               ------

    INTEGER:        [+|-]n              [-]n
    CARDINAL:       n   base 10         as input
    BasedCARDINAL:  n   base specified  as input, leading zeros suppressed
    CHAR:           character           as input
    REAL:           [+|-]n[.fE[+|-]s]   [-]i.f
    BOOLEAN:        TRUE|FALSE          TRUE|FALSE
    BITSET:         {i,j,...}           {i,j,...}
                    where i,j are the bit number positions which are set,
                    and the size of the set is specified on output.
    String, Chars   abcdeT              abcde
                    where 'abcde' are the characters of the string
                    and T is specified terminating character.
*)     

PROCEDURE WriteCHAR(s: Stream; ch: CHAR);
PROCEDURE ReadCHAR(s: Stream): CHAR;
PROCEDURE NewLine(s: Stream);	
(*  WriteCHAR(s, CharCodes.NewLineCh)      
*)

PROCEDURE WriteINTEGER(s : Stream;  i : INTEGER);
PROCEDURE ReadINTEGER(s: Stream): INTEGER;

PROCEDURE WriteCARDINAL(s : Stream;  c : CARDINAL);
PROCEDURE ReadCARDINAL(s: Stream): CARDINAL;

PROCEDURE WriteBasedCARDINAL(s: Stream; n: CARDINAL; base: NumberBase);
PROCEDURE ReadBasedCARDINAL(s: Stream; base: NumberBase): CARDINAL;

PROCEDURE WriteBOOLEAN(s : Stream;  bool : BOOLEAN);
PROCEDURE ReadBOOLEAN(s: Stream): BOOLEAN;

PROCEDURE WriteREAL(s : Stream;  real : REAL;  decPlaces : CARDINAL);
PROCEDURE ReadREAL(s: Stream): REAL;

PROCEDURE WriteBITSET(s: Stream; b: BITSET; setSize: CARDINAL);
PROCEDURE ReadBITSET(s: Stream): BITSET; (* set size implicit *)

TYPE TermProc = PROCEDURE(CHAR): BOOLEAN;
(*  returns TRUE if the argument is in the set which should terminate
    a ReadChars or ReadString
*)
PROCEDURE WriteChars(s: Stream; chars: ARRAY OF CHAR);
(*  Writes the characters in 'chars', assumed to be a string in standard
    language form, i.e terminated by HIGH(chars) or chars[i] = 0C.
*)
PROCEDURE ReadChars(s: Stream; VAR chars: ARRAY OF CHAR; T: TermProc);
(*  Reads characters until 'T' returns TRUE or EndOfStream is reached,
    and places the characters in standard language form. 
    If 'chars' is not large enough, an array-bounds fault will occur.
*)

PROCEDURE WriteString(s: Stream; string: String);
PROCEDURE ReadString(s: Stream; T: TermProc): String;
(*  Similar to ReadChars, save that the characters are placed in
    a dynamically allocated String.  The caller is responsible for
    disposing of the resulting object.
    The maximum number of characters that can be read with this 
    routine is 256, else an array-bounds fault will occur.
*)
PROCEDURE WhiteSpace(ch: CHAR): BOOLEAN;
(*  a TermProc returning TRUE for the white-space characters,
    specifically SpaceCh, NewLineCh, CReturnCh, FormFeedCh and TabCh
    (from CharCodes), for common use with ReadChars, ReadString.
*)
PROCEDURE EndOfLine(ch: CHAR): BOOLEAN;
(*  a TermProc returning TRUE for the end-of-line characters,
    specifically NewLineCh, CReturnCh, FormFeedCh.
    (from CharCodes), for common use with ReadChars, ReadString.
*)

END TextIO.
