Debian Codegraph @

gcc/m2/gm2-libs-iso/IOChan.def

raw
1 (* Library module defined by the International Standard
2 Information technology - programming languages
3 BS ISO/IEC 10514-1:1996E Part 1: Modula-2, Base Language.
4
5 Copyright ISO/IEC (International Organization for Standardization
6 and International Electrotechnical Commission) 1996-2021.
7
8 It may be freely copied for the purpose of implementation (see page
9 707 of the Information technology - Programming languages Part 1:
10 Modula-2, Base Language. BS ISO/IEC 10514-1:1996). *)
11
12 DEFINITION MODULE IOChan;
13
14 (* Types and procedures forming the interface to channels for
15 device-independent data transfer modules
16 *)
17
18 IMPORT IOConsts, ChanConsts, SYSTEM;
19
20 TYPE
21 ChanId; (* Values of this type are used to identify channels *)
22
23 (* There is one pre-defined value identifying an invalid channel
24 on which no data transfer operations are available. It may
25 be used to initialize variables of type ChanId.
26 *)
27
28 PROCEDURE InvalidChan (): ChanId;
29 (* Returns the value identifying the invalid channel. *)
30
31 (* For each of the following operations, if the device supports
32 the operation on the channel, the behaviour of the procedure
33 conforms with the description below. The full behaviour is
34 defined for each device module. If the device does not
35 support the operation on the channel, the behaviour of the
36 procedure is to raise the exception notAvailable.
37 *)
38
39 (* Text operations - these perform any required translation between the
40 internal and external representation of text.
41 *)
42
43 PROCEDURE Look (cid: ChanId; VAR ch: CHAR; VAR res: IOConsts.ReadResults);
44 (* If there is a character as the next item in the input stream
45 cid, assigns its value to ch without removing it from the stream;
46 otherwise the value of ch is not defined. res (and the stored
47 read result) are set to the value allRight, endOfLine, or endOfInput.
48 *)
49
50 PROCEDURE Skip (cid: ChanId);
51 (* If the input stream cid has ended, the exception skipAtEnd
52 is raised; otherwise the next character or line mark in cid is
53 removed, and the stored read result is set to the value
54 allRight.
55 *)
56
57 PROCEDURE SkipLook (cid: ChanId; VAR ch: CHAR; VAR res: IOConsts.ReadResults);
58 (* If the input stream cid has ended, the exception skipAtEnd is
59 raised; otherwise the next character or line mark in cid is
60 removed. If there is a character as the next item in cid
61 stream, assigns its value to ch without removing it from the
62 stream. Otherwise, the value of ch is not defined. res
63 (and the stored read result) are set to the value allRight,
64 endOfLine, or endOfInput.
65 *)
66
67 PROCEDURE WriteLn (cid: ChanId);
68 (* Writes a line mark over the channel cid. *)
69
70 PROCEDURE TextRead (cid: ChanId; to: SYSTEM.ADDRESS; maxChars: CARDINAL;
71 VAR charsRead: CARDINAL);
72 (* Reads at most maxChars characters from the current line in cid,
73 and assigns corresponding values to successive components of
74 an ARRAY OF CHAR variable for which the address of the first
75 component is to. The number of characters read is assigned to charsRead.
76 The stored read result is set to allRight, endOfLine, or endOfInput.
77 *)
78
79 PROCEDURE TextWrite (cid: ChanId; from: SYSTEM.ADDRESS;
80 charsToWrite: CARDINAL);
81 (* Writes a number of characters given by the value of charsToWrite,
82 from successive components of an ARRAY OF CHAR variable for which
83 the address of the first component is from, to the channel cid.
84 *)
85
86 (* Direct raw operations - these do not effect translation between
87 the internal and external representation of data
88 *)
89
90 PROCEDURE RawRead (cid: ChanId; to: SYSTEM.ADDRESS; maxLocs: CARDINAL;
91 VAR locsRead: CARDINAL);
92 (* Reads at most maxLocs items from cid, and assigns corresponding
93 values to successive components of an ARRAY OF LOC variable for
94 which the address of the first component is to. The number of
95 characters read is assigned to charsRead. The stored read result
96 is set to the value allRight, or endOfInput.
97 *)
98
99 PROCEDURE RawWrite (cid: ChanId; from: SYSTEM.ADDRESS; locsToWrite: CARDINAL);
100 (* Writes a number of items given by the value of charsToWrite,
101 from successive components of an ARRAY OF LOC variable for
102 which the address of the first component is from, to the channel cid.
103 *)
104
105 (* Common operations *)
106
107 PROCEDURE GetName (cid: ChanId; VAR s: ARRAY OF CHAR);
108 (* Copies to s a name associated with the channel cid, possibly truncated
109 (depending on the capacity of s).
110 *)
111
112 PROCEDURE Reset (cid: ChanId);
113 (* Resets the channel cid to a state defined by the device module. *)
114
115 PROCEDURE Flush (cid: ChanId);
116 (* Flushes any data buffered by the device module out to the channel cid. *)
117
118 (* Access to read results *)
119
120 PROCEDURE SetReadResult (cid: ChanId; res: IOConsts.ReadResults);
121 (* Sets the read result value for the channel cid to the value res. *)
122
123 PROCEDURE ReadResult (cid: ChanId): IOConsts.ReadResults;
124 (* Returns the stored read result value for the channel cid.
125 (This is initially the value notKnown).
126 *)
127
128 (* Users can discover which flags actually apply to a channel *)
129
130 PROCEDURE CurrentFlags (cid: ChanId): ChanConsts.FlagSet;
131 (* Returns the set of flags that currently apply to the channel cid. *)
132
133 (* The following exceptions are defined for this module and its clients *)
134
135 TYPE
136 ChanExceptions =
137 (wrongDevice, (* device specific operation on wrong device *)
138 notAvailable, (* operation attempted that is not available on that
139 channel *)
140 skipAtEnd, (* attempt to skip data from a stream that has ended *)
141 softDeviceError, (* device specific recoverable error *)
142 hardDeviceError, (* device specific non-recoverable error *)
143 textParseError, (* input data does not correspond to a character or
144 line mark - optional detection *)
145 notAChannel (* given value does not identify a channel -
146 optional detection *)
147 );
148
149 PROCEDURE IsChanException (): BOOLEAN;
150 (* Returns TRUE if the current coroutine is in the exceptional
151 execution state because of the raising of an exception from
152 ChanExceptions; otherwise returns FALSE.
153 *)
154
155 PROCEDURE ChanException (): ChanExceptions;
156 (* If the current coroutine is in the exceptional execution state
157 because of the raising of an exception from ChanExceptions,
158 returns the corresponding enumeration value, and otherwise
159 raises an exception.
160 *)
161
162 (* When a device procedure detects a device error, it raises the
163 exception softDeviceError or hardDeviceError. If these
164 exceptions are handled, the following facilities may be
165 used to discover an implementation-defined error number for
166 the channel.
167 *)
168
169 TYPE
170 DeviceErrNum = INTEGER;
171
172 PROCEDURE DeviceError (cid: ChanId): DeviceErrNum;
173 (* If a device error exception has been raised for the channel cid,
174 returns the error number stored by the device module.
175 *)
176
177 END IOChan.