Page Numbers: Yes First Page: 70 X: 527 Y: 10.5"
Margins: Binding: 13
Odd Heading: Not-on-first-page

Alto/Mesa StreamIO Package

Even Heading:

Alto/Mesa StreamIO Package

Alto/Mesa StreamIO Package
October 1980

StreamIO contains a set of procedures for convenient use of the character and string stream facilities in Mesa. The procedures of the StreamIO package are described below. The declarations necessary to use the procedures are in IODefs.

StreamIO uses two streams, one for input and one for output. These may be gotten by calling:

GetInputStream, GetOutputStream: PROCEDURE RETURNS [StreamHandle];

Returns the stream used for input or output, respectively.

The streams may be changed by calling:

SetInputStream, SetOutputStream: PROCEDURE [StreamHandle];

Replaces the input or output stream, respectively.

Character IO

ReadChar: PROCEDURE RETURNS [CHARACTER];

Returns the next character from the InputStream.

WriteChar: PROCEDURE [c: CHARACTER];

The character c is written on the OutputStream.

Definitions for control characters such as NUL, BS, TAB, LF, FF, CR, ESC, SP, DEL, and ControlA - ControlZ can be found in IODefs. These character definitions may also be found in the DEFINITIONS file Ascii.

String Input

The procedures below read input from the InputStream. The following exceptional conditions may occur.

LineOverflow: SIGNAL [s: STRING] RETURNS [ns: STRING];

The input has filled the string s; the current contents of the string is passed as a parameter to the SIGNAL. The catch phrase should return a string ns with more room.

Rubout: SIGNAL;

The DEL key was typed during ReadEditedString.

The SetEcho procedure controls the echoing of characters on input by ReadEdited String. It returns the previous state of the echoing mode which is defaulted to on.

SetEcho: PROCEDURE [new: BOOLEAN] RETURNS [old: BOOLEAN];

The input procedures are:

ReadEditedString: PROCEDURE [
s: STRING, t: PROCEDURE [CHARACTER] RETURNS [BOOLEAN], newstring: BOOLEAN]
RETURNS [CHARACTER];

s contains (on return) the string read from the InputStream. The procedure t should return TRUE if the CHARACTER passed to it should terminate the string. If (newstring is TRUE and the first input character is ESC) or (newstring is FALSE), then s is treated as if it had been read from InputStream (input characters are appended to it). Otherwise s is initialized to be empty before reading is begun.

A string is read from the InputStream with the following editing characters recognized:

↑A, ↑H (BS) delete the last character
↑W, ↑Q delete the last word
↑X delete the line and start over
↑R retype the line
↑V quote the next character

If echoing is on, all characters except the terminating character are echoed on the OutputStream. The user supplied procedure t determines which character(s) terminate the string. The editing characters above are not put into the string, but they are passed to the decision procedure t. The character returned is the character which terminated the string and is not echoed or included in the string.

The following procedures all call ReadEditedString passing TRUE for newstring.

ReadString: PROCEDURE [s: STRING, t: PROCEDURE [CHARACTER] RETURNS [BOOLEAN]];

Like ReadEditedString except that the terminating character is echoed (independent of the SetEcho state). No value is returned.

ReadLine: PROCEDURE [s: STRING];

Reads from the InputStream up to the next carriage return character using ReadEditedString. The terminating character is not part of s, but is echoed (independent of the SetEcho state).

ReadID: PROCEDURE [s: STRING];

Uses ReadEditedString to read a string terminated with a space or carriage return into s. The terminating character is not echoed.

String Output

WriteString: PROCEDURE [s: STRING];

The string s is written on the OutputStream.

WriteLine: PROCEDURE [s: STRING];

The string s is written on the OutputStream followed by a carriage return.

WriteSubString: PROCEDURE [ss: StringDefs.SubString];

The substring ss is written on the OutputStream.

Number Input

These procedures use the StringToNumber conversion procedures from the Strings package.

ReadNumber: PROCEDURE [default: UNSPECIFIED, radix: CARDINAL]
RETURNS [UNSPECIFIED];

ReadID followed by StringToNumber. The value default will be displayed if ESC is typed. radix is a default value, (use the "B" or "D" notation to force octal or decimal). radix values other than 8 or 10 cause unpredictable results.

ReadDecimal: PROCEDURE RETURNS [INTEGER];

ReadID followed by StringToDecimal.

ReadOctal: PROCEDURE RETURNS [UNSPECIFIED];

ReadID followed by StringToOctal.

Number Output

NumberFormat: TYPE = RECORD [
base: [2..36], zerofill, unsigned: BOOLEAN, columns: [0..255]];

A NumberFormat, say f, refers to a number whose base is f.base; the field is f.columns wide; if f.zerofill, the extra columns are filled with zeros, otherwise spaces are used; if f.unsigned, the number is treated as unsigned.

OutNumber: PROCEDURE [StreamHandle, UNSPECIFIED, NumberFormat];

Converts the value to a character string of digits as specified by the NumberFormat and outputs them to the StreamHandle.

WriteNumber: PROCEDURE [UNSPECIFIED, NumberFormat];

Equivalent to OutNumber with OutputStream as the StreamHandle.

WriteDecimal: PROCEDURE [n: INTEGER];

The value of n is converted to a character string of digits in base ten and output to the OutputStream. Negative numbers are written with a preceeding minus sign (’−).

WriteOctal: PROCEDURE [n: UNSPECIFIED];

The value of n is converted to a character string of digits in base eight and output to the OutputStream. The numbers are unsigned, i.e., −2 is written as 177776B. The "B" is appended to any number more than one digit long.

Initialization

The Mesa system provides an instance of StreamIO which will obtain input from the keyboard and write output to the display. Client programs may create new instances of StreamIO to deal with other streams by writing:

StreamIO: FROM "streamio";
. . .
IMPORTS . . . systemio: StreamIO . . . ;
. . .
f: POINTER TO FRAME [StreamIO];
. . .
f ← NEW systemio;
START f;

The streams used for input and output can then be set by calling SetInputStream or SetOutputStream. The desired stream procedures may be accessed by OPENing f or writing f.procedurename.

CharIO

The interface CharIO provides an alternative set of procedures for character and string facilities in Mesa. While not identical to the procedures in IODefs, there is a direct correspondence between the procedures in CharIO and those in IODefs. The primary difference is that the procedures in CharIO has an explicit stream parameter. The module CharIOPack implements the interface; it is not part of the standard configuration.