-
Notifications
You must be signed in to change notification settings - Fork 4
/
sect07.html
315 lines (263 loc) · 12.2 KB
/
sect07.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
<!DOCTYPE html>
<html>
<head>
<title>The Z-Machine Standards Document</title>
<link rel="stylesheet" type="text/css" href="zspec.css">
<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
</head>
<body>
<img class="icon" src="images/icon07.gif" alt="">
<h1>7. Output streams and file handling</h1>
<hr>
<p>7.1 <a href="#7.1">Output streams</a> /
7.2 <a href="#7.2">Buffering</a> /
7.3 <a href="#7.3">Selection (V1 and V2)</a> /
7.4 <a href="#7.4">Selection (later versions)</a> /
7.5 <a href="#7.5">Dealing with Unicode or invalid characters</a> /
7.6 <a href="#7.6">File handling</a>
</p>
<hr>
<h2 id="7.1">7.1</h2>
<p>At any given time text is being output through a selection of
"output streams" (possibly none, possibly several at once).
</p>
<h2 id="7.1.1">7.1.1</h2>
<p>Two output streams are common to all Versions:
number 1 (the screen) and 2 (the game transcript, usually printed
to a printer or a file).
</p>
<h2 id="7.1.1.1">7.1.1.1</h2>
<p>In Versions 1 to 5, the player's input to the
<a href="sect15.html#read"><strong>read</strong></a>
opcode should be echoed to output streams 1 and 2 (if stream 2
is active), so that text typed in appears in any transcript.
In Version 6 input should be sent only to stream 1 and it is
the game's responsibility to write to the transcript.
</p>
<h2 id="7.1.1.2">7.1.1.2</h2>
<p>In Infocom's Version 4 game 'A Mind Forever Voyaging',
which anticipated a printer rather than a file to receive the
transcript, stream 2 is turned off and on again several times in
quick succession. Thus if an interpreter decides where to send
the transcript by asking the player for a filename, this question
should only be asked once per game session, not every time stream
2 is selected.
</p>
<h2 id="7.1.2">7.1.2</h2>
<p>Versions 3 and later supply these and two other output streams,
numbered 3 (Z-machine memory) and 4 (a script file of the player's whole
commands and of individual keypresses as read by
<a href="sect15.html#read_char"><strong>read_char</strong></a>).
</p>
<h2 id="7.1.2.1">7.1.2.1</h2>
<p>Output stream 3 writes to a table in dynamic memory. When the
stream is selected, the table may have any contents (even the initial 'size'
word will be ignored by the interpreter). While the stream is selected, the
table's contents are unspecified (and a game cannot safely read or write
to it). When the stream is deselected, the initial word of the table holds
the number of characters printed and subsequent bytes hold those characters.
(It is the programmer's responsibility to make the table large enough: the
interpreter performs no overflow checking.)
</p>
<p>In Version 6, the total width of printing (in units) will then be stored in
the word at <strong>$30</strong> in the header. The game should not attempt any
operation that will change the width of the font (such as changing from a
proportional to a fixed width font) while output stream 3 is active, and the
interpreter need not store an accurate width of the resulting string if a game does
do this.
</p>
<h2 id="7.1.2.1.1">7.1.2.1.1</h2>
<p><strong>***</strong> It is possible for stream 3 to be selected while
it is already on. If this happens, the previous table address is
remembered and the previous table is resumed when the new one is
finished. This nesting can reach a depth of up to 16: if stream 3
is opened for a seventeenth time, the interpreter should halt with
an error message.
</p>
<h2 id="7.1.2.2">7.1.2.2</h2>
<p>Output stream 3 is unusual in that, while it is selected, no
text is sent to any other output streams which are selected. (However,
they remain selected.)
</p>
<h2 id="7.1.2.2.1">7.1.2.2.1</h2>
<p>Newlines are written to output stream 3 as ZSCII 13. (A game
should never <a href="sect15.html#print_char"><strong>print_char</strong></a>
the value 10, or any other value which is undefined as a ZSCII output code.)
</p>
<h2 id="7.1.1.2.3">7.1.2.3</h2>
<p>Output stream 4 is unusual in that, when it is selected,
the only text printed to it is that of the player's commands and
keypresses (as read by <a href="sect15.html#read_char"><strong>read_char</strong></a>).
(Each command is written, in one go, when it has been finished. Time delays and mouse-clicks
should ideally be recorded. For suggestions on how this might be achieved, see the
<a href="sect07.html#remarks">remarks</a> section below. Mistypes and uses of 'delete' are
not written.)
</p>
<h2 id="7.2">7.2</h2>
<p>On output streams 1 and 2 (only), text printing may be "buffered"
in that new-lines are automatically printed to ensure that no word
(of length less than the width of the screen) spreads across two lines
(if the interpreter is able to control this).
(This process is sometimes called "word-wrapping".)
</p>
<h2 id="7.2.1">7.2.1</h2>
<p>In Versions 1 to 3, buffering is always on. In Versions 4
and later it is on by default (at the start of a game) and a game can
switch it on or off using the <a href="sect15.html#buffer_mode"><strong>buffer_mode</strong></a>
opcode.
</p>
<h2 id="7.2.2">7.2.2</h2>
<p>In Version 6, each of the eight windows has its own "buffering
flag". In Versions 3 to 5, the <a href="sect15.html#buffer_mode"><strong>buffer_mode</strong></a>
applies only to the lower window, and buffering never happens in the upper window.
</p>
<h2 id="7.3">7.3</h2>
<p>In Versions 1 and 2, output stream 1 is always selected and
stream 2 can be selected or deselected by the game, by setting or clearing
bit 0 of 'Flags 2'.
</p>
<h2 id="7.4">7.4</h2>
<p>In Versions 3 and later, all four output streams can be selected
or deselected using the <a href="sect15.html#output_stream">
<strong>output_stream</strong></a> opcode. In addition, stream 2
can be selected or deselected by setting or clearing bit 0 of 'Flags 2'.
Whichever method is used, the interpreter must ensure that this flag
holds the current status of stream 2. ('A Mind Forever Voyaging'
requires this.)
</p>
<h2 id="7.5">7.5</h2>
<p><strong>***</strong>
Because of the <strong>print_unicode</strong> opcode, it is possible for
arbitrary Unicode characters to be sent to the output streams: that is,
for characters which are not in the ZSCII set at all, even in the
"extra characters" range.
</p>
<h2 id="7.5.1">7.5.1</h2>
<p>See <strong>§</strong> 3.8.5.4 for rules on printing Unicode to stream 1.</p>
<h2 id="7.5.2">7.5.2</h2>
<p>Interpreters are free to use any representation of non-ASCII
Unicode characters in stream 2. For example, they might print
"[1a05]" to signify Unicode character <strong>$1a05</strong>; or they might be
configurable to write transcript files which conform to any chosen
ISO 8859 set.
</p>
<h2 id="7.5.3">7.5.3</h2>
<p>When printed to stream 3, Unicode characters should be
converted to ZSCII if possible. If this is not possible, a question
mark should be printed to stream 3.
</p>
<h2 id="7.5.4">7.5.4</h2>
<p>Non-ZSCII characters never need to be printed to stream 4.</p>
<h2 id="7.6">7.6</h2>
<p><strong>***</strong> In Versions 5 and later, the Z-machine has the ability to load
and save files (using optional operands with the
<a href="sect15.html#save"><strong>save</strong></a> and
<a href="sect15.html#restore"><strong>restore</strong></a>
opcodes: these operands were not used in Infocom's Version 5 games,
but I wish to specify them as in Version 5 anyway).
</p>
<h2 id="7.6.1">7.6.1</h2>
<p><strong>***</strong> Filenames have the following format (approximately the MS-DOS
8.3 rule): one to eight alphanumeric characters, a full stop and zero to
three alphanumeric characters (the "file extension").
</p>
<h2 id="7.6.1.1">7.6.1.1</h2>
<p>The interpreter must convert all filenames to upper case before
use. If no full stop is given, ".AUX" should be appended.
</p>
<h2 id="7.6.1.2">7.6.1.2</h2>
<p>Games should avoid the extensions ".INF", ".H", ".Z"
followed by a number or ".SAV": otherwise they may be in danger of erasing
their own object code, source code or saved game files.
</p>
<h2 id="7.6.2">7.6.2</h2>
<p><strong>***</strong> Saved files are not associated with any particular session
of a game. They are not part of the "state of play".
</p>
<h2 id="7.6.3">7.6.3</h2>
<p><strong>***</strong> A game may depend on having up to 32 auxiliary files (with
different names).
</p>
<h2 id="7.6.4">7.6.4</h2>
<p>File-handling errors such as "disc corrupt" and "disc full"
should be reported directly to the player by the interpreter. The error
"file not found" should only cause a failure return code from
<a href="sect15.html#restore"><strong>restore</strong></a>.
</p>
<h2 id="7.6.5">7.6.5</h2>
<p>Interpreters are allowed to not support access to external files (such as with
output_stream 2, or the extra features of save and restore), or to only support
some methods of access. Interpreters should support these features if possible,
as some games may rely on external files, and in any case transcripts are very
useful for testing, but in some environments such access is not feasible.
</p>
<h2 id="7.6.5.1">7.6.5.1</h2>
<p>An attempt by the game to use save or restore in a manner not supported by the
interpreter should simply return 0 as with any failure, and the game should
notice and take appropriate actions.
</p>
<h2 id="7.6.5.2">7.6.5.2</h2>
<p>An attempt by the game to use streams to access external files which is not
supported by the interpreter should ideally print a warning to the user that
the functionality is not available, and otherwise do nothing.
</p>
<hr>
<h2 id="remarks">Remarks</h2>
<p>The <strong>ITF</strong> interpreter incorrectly applies buffering when printing to
the upper window.
</p>
<p>Note that the requirement in <a href="sect07.html#7.1.2.1.1"><strong>§</strong>
7.1.2.1.1</a>, that usages of stream 3 can be
'nested', is new in Standard 1.0. This is potentially important for
Inform games, as stream 3 is often used to examine text before printing,
for instance to choose between the articles "a" and "an" in front
of an object name. But the process of printing an object name may
itself require a usage of stream 3, and so on.
</p>
<p>An ambiguous point about output stream 4 is whether it should contain
the answers to interpreter questions like "what file name should your
saved game have?": it can actually be quite useful to be able to include
such answers in test script files. (When running a long script, I often
save the game at several places during it, in order to save time in
re-running passages.)
</p>
<p>An interpreter should be able to write time delays (for timed input),
accented characters or mouse clicks into stream 4 (i.e., to a script file).
One possible style to record this information might be:
</p>
<pre>
take lamp an ordinary command
turn it on.[154] command, full stop, then keypad 9
(which might abbreviate for NE)
look unde[0] timed out input
look under the rock the same input continuing
[254][10][6] mouse-click at (10,6)
</pre>
<p>A typical auxiliary file might be one containing the player's preferred
choices. This would be created when he first changed any of the default
settings, and loaded (if present) whenever the game started up.
</p>
<hr>
<p>
<a href="index.html">Contents</a> /
<a href="preface.html">Preface</a> /
<a href="overview.html">Overview</a>
</p>
<p>Section
<a href="sect01.html">1</a> / <a href="sect02.html">2</a> /
<a href="sect03.html">3</a> / <a href="sect04.html">4</a> /
<a href="sect05.html">5</a> / <a href="sect06.html">6</a> /
<a href="sect07.html">7</a> / <a href="sect08.html">8</a> /
<a href="sect09.html">9</a> / <a href="sect10.html">10</a> /
<a href="sect11.html">11</a> / <a href="sect12.html">12</a> /
<a href="sect13.html">13</a> / <a href="sect14.html">14</a> /
<a href="sect15.html">15</a> / <a href="sect16.html">16</a>
</p>
<p>Appendix
<a href="appa.html">A</a> / <a href="appb.html">B</a> /
<a href="appc.html">C</a> / <a href="appd.html">D</a> /
<a href="appe.html">E</a> / <a href="appf.html">F</a>
</p>
<hr>
</body>
</html>