The main modules described by Niklaus Wirth and suggested for adoption in Modula-2 are described in this Appendix. Although the detailed semantics varies widely in some cases, they can be assumed to be a part of all older (pre-ISO) versions, and are included alongside the ISO modules by some vendors as well.
DEFINITION MODULE InOut; CONST EOL = 15C; (* hardware dependant--could also be 36C *) VAR Done: BOOLEAN; termCH: CHAR; PROCEDURE OpenInput (defext: ARRAY OF CHAR); PROCEDURE OpenOutput (defext: ARRAY OF CHAR); PROCEDURE CloseInput; PROCEDURE CloseOutput; PROCEDURE Read (VAR ch: CHAR); PROCEDURE ReadString (VAR s: ARRAY OF CHAR); PROCEDURE ReadInt (VAR x: INTEGER); PROCEDURE ReadCard (VAR x: CARDINAL); PROCEDURE Write (ch: CHAR); PROCEDURE WriteLn; PROCEDURE WriteString (s: ARRAY OF CHAR); PROCEDURE WriteInt (x: INTEGER; n: CARDINAL); PROCEDURE WriteCard (x, n: CARDINAL); PROCEDURE WriteOct (x, n: CARDINAL); PROCEDURE WriteHex (x, n: CARDINAL); END InOut.
NOTES: 1. In some cases InOut may incorporate RealInOut.
2. Many implementations place termCH in Terminal.
3. Some include the procedure ClearScreen.
4. The syntax and semantics of OpenInput and OpenOutput vary widely from one classical implementation to another.
DEFINITION MODULE RealInOut; VAR Done: BOOLEAN; PROCEDURE ReadReal (VAR x: REAL); PROCEDURE WriteReal (x: REAL; n: CARDINAL); PROCEDURE WriteRealOct (x: REAL); END RealInOut.
NOTE: The syntax and semantics of WriteReal widely from one classical implementation to another.
DEFINITION MODULE Terminal; PROCEDURE Read (VAR ch: CHAR); PROCEDURE ReadLn (VAR s: ARRAY OF CHAR); (* stops at end-of-line *) PROCEDURE BusyRead (VAR ch: CHAR); PROCEDURE ReadAgain; PROCEDURE Write (ch: CHAR); PROCEDURE WriteString (s: ARRAY OF CHAR); PROCEDURE WriteLn; END Terminal.
NOTE: Where supplied, the contents of this module vary. The following module may be included in Terminal or be separate.
DEFINITION MODULE Screen; PROCEDURE HomeCursor; PROCEDURE ClearScreen; PROCEDURE EraseLine; PROCEDURE GotoXY (x, y: CARDINAL); END Screen.
DEFINITION MODULE MathLib0; PROCEDURE sqrt (x: REAL): REAL; PROCEDURE exp (x: REAL): REAL; PROCEDURE ln (x: REAL): REAL; PROCEDURE sin (x: REAL): REAL; PROCEDURE cos (x: REAL): REAL; PROCEDURE arctan (x: REAL): REAL; PROCEDURE real (x: INTEGER): REAL; PROCEDURE entier (x: REAL): INTEGER; END MathLib0.
Several versions add:
DEFINITION MODULE MathLibLong; (* may be called "LongMath" *) PROCEDURE sqrt (x: LONGREAL): LONGREAL; PROCEDURE exp (x: LONGREAL): LONGREAL; PROCEDURE ln (x: LONGREAL): LONGREAL; PROCEDURE sin (x: LONGREAL): LONGREAL; PROCEDURE cos (x: LONGREAL): LONGREAL; PROCEDURE arctan (x: LONGREAL): LONGREAL; PROCEDURE real (x: LONGINTEGER): LONGREAL; PROCEDURE entier (x: LONGREAL): LONGINTEGER; END MathLibLong.
NOTE: The contents of mathematical libraries vary widely in classival versions. Some may include:
CONST pi = 3.1415926536; e = 2.7182818284;
The module SYSTEM is properly termed a psuedo-Module as it does not exist in the library, but is entirely contained inside the compiler. Nonetheless, it behaves in most classical versions as though it had the definition given.
DEFINITION pseudo-MODULE SYSTEM;
TYPE
ADDRESS; WORD;
PROCEDURE ADR (anyObject: ARRAY OF WORD): ADDRESS;
PROCEDURE SIZE (anyObject: ARRAY OF WORD): CARDINAL;
(* older versions--newer ones have it as a built-in *) PROCEDURE TSIZE (anyType [,optional variant list] ): CARDINAL;
PROCEDURE NEWPROCESS (nameOfProcess : PROC;
workspace : ADDRESS;
sizeOfSpace : CARDINAL;
VAR newProc : ADDRESS);
PROCEDURE TRANSFER (VAR oldProcess : ADDRESS; VAR newProcess : ADDRESS);
PROCEDURE IOTRANSFER (VAR oldProcess : ADDRESS; VAR newProcess : ADDRESS);
(* Not all implement the latter *)
END SYSTEM.
NOTE: The contents of this library vary widely in classical versions. Many other entities may be included, such as:
TYPE BYTE; SHORTWORD; LONGWORD; QUADWORD; OCTWORD; HEXWORD;
DEFINITION MODULE Storage; FROM SYSTEM IMPORT ADDRESS; PROCEDURE ALLOCATE (VAR p: ADDRESS; size: CARDINAL); PROCEDURE DEALLOCATE (VAR p: ADDRESS; size: CARDINAL); PROCEDURE Available (size: CARDINAL): BOOLEAN; END Storage.
DEFINITION MODULE Strings;
TYPE
STRING = ARRAY [0..80] OF CHAR;
PROCEDURE Assign (VAR source, dest: ARRAY OF CHAR);
PROCEDURE Insert (substr: ARRAY OF CHAR; VAR str: ARRAY OF CHAR; index: CARDINAL);
PROCEDURE Delete (VAR str: ARRAY OF CHAR; index: CARDINAL; len: CARDINAL);
PROCEDURE Pos (substr, str: ARRAY OF CHAR): CARDINAL;
PROCEDURE Copy (str: ARRAY OF CHAR; index: CARDINAL; len: CARDINAL;
VAR result: ARRAY OF CHAR);
PROCEDURE Concat (s1, s2: ARRAY OF CHAR; VAR result: ARRAY OF CHAR);
PROCEDURE Length (VAR str: ARRAY OF CHAR): CARDINAL;
PROCEDURE CompareStr (s1, s2: ARRAY OF CHAR): INTEGER;
(* returns -1 if s1 < s2 0 if s1 = s2 1 if s1 > s2 *)
END Strings.
This module (or some other) may also contain facilities for conversions to another type of string employed by the operating system, such as the Macintosh (Pascal) strings that are used to call the file manager. Some possible names and syntax are given below:
FROM MacSystemTypes IMPORT Str255; PROCEDURE StrModToPas (VAR dest: Str255; source: ARRAY OF CHAR); PROCEDURE StrPasToMod (VAR dest: ARRAY OF CHAR; source: Str255); PROCEDURE WritePasString (string: Str255); PROCEDURE StrPasCat (VAR source1AndResult: Str255; source2: Str255);
NOTE: Contents of string handling modules vary widely from one classical version to another. Even where two versions have similarly named modules, the syntax (order of parameters) may be different.
Some classical versions make available a variety of string/numeric conversion routines that are called by the high level I/O modules after they read a token (string) from the input stream. Examples include:
DEFINITION MODULE Conversions; FROM SYSTEM IMPORT WORD; PROCEDURE IntToStr (i: INTEGER; VAR s: ARRAY OF CHAR): BOOLEAN; PROCEDURE StrToInt (s: ARRAY OF CHAR; VAR i: INTEGER): BOOLEAN; PROCEDURE CardToStr (c: CARDINAL; VAR s: ARRAY OF CHAR): BOOLEAN; PROCEDURE StrToCard (s: ARRAY OF CHAR; VAR c: CARDINAL): BOOLEAN; PROCEDURE HexToStr (w: WORD; VAR s: ARRAY OF CHAR): BOOLEAN; PROCEDURE StrToHex (s: ARRAY OF CHAR; VAR w: WORD): BOOLEAN; PROCEDURE RealToStr (r: REAL; width: CARDINAL; decPlaces: INTEGER; VAR s: ARRAY OF CHAR): BOOLEAN); PROCEDURE StrToReal (s: ARRAY OF CHAR; VAR r: REAL;) : BOOLEAN; END Conversions.
In the early years of Modula-2, there were a very wide variety of file handling techniques, and earlier works by this author included pointers for writing a "standard" set of modules, so that readers could all use the same file interface. Those suggestions were taken to heart by many vendors, and gradually a model similar to the one in this section became common in the classical versions, though still with numerous variations in style, syntax, and semantics.
The general characteristics of this model are as follows:
1. File (or FILE) may be either a transparant or an opaque type. This is the type of the logical (program) variables which are associated with physical files through the procedure Open.
2. Only minimal text writing facilities are provided in the module Files(or FileSystem, or Filer) , as it is designed more for random access files.
3. Text I/O is generally handled by a separate module, but using the type File directly.
4. The type FilePos is usually not an opaque type.
5. Facilities are sometimes provided for looking up file names and for reading and parsing them from the terminal.
6. The main file handling module includes some or all of:
DEFINITION MODULE FileSystem;
FROM SYSTEM IMPORT
WORD, ADDRESS, BYTE;
TYPE
File;
Response = (done, notdone, notsupported, callerror, unknownmedium, unknownfile, paramerror, toomanyfiles, eom, deviceoff, softparityerror, softprotected, softerror, hardparityerror, hardprotected, timeout, harderror);
(* File Management *)
PROCEDURE FileState (f: File) : Response;
PROCEDURE Lookup (VAR f: File; name: ARRAY OF CHAR; new: BOOLEAN);
(* new = permission to create if not found *)
PROCEDURE Create (VAR f: File; mediumName: ARRAY OF CHAR);
(* file created is temporary and nameless*)
PROCEDURE Rename (VAR f: File; filename: ARRAY OF CHAR);
(* needed to make a temporary file permanent. The reverse happens if the name given is empty. *)
PROCEDURE Close (VAR f: File);
(* Only those with nonempty names will remain in the directory after being closed. *)
PROCEDURE Delete (filename: ARRAY OF CHAR);
PROCEDURE SetRead (VAR f: File);
PROCEDURE SetWrite (VAR f: File);
PROCEDURE SetModify (VAR f: File);
PROCEDURE SetOpen (VAR f: File); (* where present, cancels any of the last three *)
(* File Information *)
PROCEDURE Eof (f: File): BOOLEAN;
(* Sequential File Access -- Textual Material *)
PROCEDURE ReadChar (f: File; VAR ch: CHAR);
PROCEDURE WriteChar (f: File; ch: CHAR);
(* Binary File Access *)
PROCEDURE ReadWord (f: File; w: WORD);
PROCEDURE WriteWord (f: File; w: WORD);
PROCEDURE Again (VAR f: File);
(* sets position back to beginning or previously read WORD or CHAR *)
PROCEDURE ReadByte (f: File; w: BYTE);
PROCEDURE WriteByte (f: File; w: BYTE);
PROCEDURE ReadNBytes (VAR f: File; buf: ADDRESS; numBytesRequested: CARDINAL; VAR numRead: CARDINAL);
PROCEDURE WriteNBytes (VAR f: File; buf: ADDRESS; numBytesToWrite: CARDINAL; VAR numWritten: CARDINAL);
(* Random Access Files *)
PROCEDURE GetPos (f: File; VAR highpos, lowpos: CARDINAL);
PROCEDURE SetPos (f: File; highpos, lowpos: CARDINAL);
PROCEDURE Length (f: File; highpos, lowpos: CARDINAL);
(* last three use a single LONGCARD for position if this type is available *)
PROCEDURE Reset (VAR f: File);
(* sets state to open and position to beginning of file *)
END FileSystem.
An alternate is the module Filer. See A6.2.
In classical versions, the module in this section is commonly provided in conjunction with the above and used to provide all textual I/O using the type File
DEFINITION MODULE TextIO; FROM Files IMPORT File; CONST EOL = 15C; VAR Done : BOOLEAN; termCH : CHAR; PROCEDURE WriteString (f : File; s : ARRAY OF CHAR); PROCEDURE WriteLn (f : File); PROCEDURE WriteInt (f : File; i : INTEGER; flen : CARDINAL); PROCEDURE WriteCard (f : File; c : CARDINAL; flen : CARDINAL); PROCEDURE WriteReal (f : File; r : REAL; flen : CARDINAL; digits: INTEGER); PROCEDURE ReadString (f : File; VAR s : ARRAY OF CHAR); PROCEDURE ReadInt (f : File; VAR i : INTEGER); PROCEDURE ReadCard (f : File; VAR c : CARDINAL); PROCEDURE ReadReal (f : File; VAR r : REAL); END TextIO.
WARNING: The least reliance can be placed on comments made here about the contents of file handling modules. In classical versions, even the convergence on the common model found in this section never meant that there was much uniformity. This was one of the principal reasons for the ISO standards effort.
DEFINITION MODULE ASCII; CONST nul = 00C; soh = 01C; stx = 02C; etx = 03C; eot = 04C; enq = 05C; ack = 06C; bel = 07C; bs = 10C; ht = 11C; lf = 12C; vt = 13C; ff = 14C; cr = 15C; so = 16C; si = 17C; dle = 20C; dc1 = 21C; dc2 = 22C; dc3 = 23C; dc4 = 24C; nak = 25C; syn = 26C; etb = 27C; can = 30C; em = 31C; sub = 32C; esc = 33C; fs = 34C; gs = 35C; rs = 36C; us = 37C; del = 177C; END ASCII. Some versions add: CONST EOL = 36C; space = 40C;