1 ===============================
2 Appendix E -- Inform language
3 ===============================
9 .. image:: /images/picR.png
16 efer to this appendix for a succinct but essentially complete summary of
17 the Inform programming language; it covers everything that we've met in
18 this guide, plus various constructs which didn't occur naturally, and
19 others of an advanced or obscure nature.
24 In the specialised language of computing, the basic unit of data storage is
25 an eight-bit **byte**, able to store a value 0..255. That's too small to
26 be useful for holding anything other than a single character, so most
27 computers also work with a group of two, four or eight bytes known as a
28 **word** (not to be confused with Inform's dictionary word). In the
29 Z-machine a storage word comprises two bytes, and you can specify in
30 various ways the literal values to be stored.
32 :Decimal: `-32768` to `32767`
33 :Hexadecimal: `$0` to `$FFFF`
34 :Binary: `$$0` to `$$1111111111111111`
37 :Dictionary word: `'aardvark'` (up to nine characters significant); use
38 circumflex "^" to denote apostrophe.
40 :Plural word: `'aardvarks//p'`
42 :Single-character word: `"a"` (`name` property only) or `'a//'`
43 :String: `"aardvark's adventure"` (maximum around 4000 characters); can
44 include special values including:
46 ============= ====================================
48 `~` double quotes "`\"`"
50 `@@92` backslash "`\\`"
51 `@@94` circumflex "`^`"
53 `@\`a` a with a grave accent "`à`", et al
54 `@LL` pound sign "`£`", et al
55 `@00 ... @31` low string 0..31
56 ============= ====================================
61 The identifier of an Inform `{const_id}`, `{var_id}`, `{array}`,
62 `{class_id}`, `{obj_id}`, `{property}`, `{attribute}`, `{routine_id}` or
63 `{label}`. Up to 32 characters: alphabetic (case not significant), numeric
64 and underscore, with the first character not a digit.
69 Named word values, unchanging at run-time, which are by default initialised
72 | `Constant {const_id}`;
73 | `Constant {const_id} = {expr}`;
75 Standard constants are `true` (1), `false` (0) and `nothing` (0), also
76 `NULL` (-1). Additionally, `WORDSIZE` is the number of bytes in a storage
77 word: 2 for the Z-machine, 4 for Glulx.
79 To define a constant (unless it already exists):
81 | `Default {const_id expr}`;
86 Named word/byte values which can change at run-time and are by default
89 A **global** variable is a single word:
92 | `Global {var_id} = {expr}`;
94 A **word array** is a set of global words accessed using
95 `{array}->0,{array}->1,... {array}->({N}-1)`:
97 | `Array {array} --> {N};`
98 | `Array {array} --> {expr1 expr2... exprN};`
99 | `Array {array} --> "{string}";`
101 A **table array** is a set of global words accessed using `{array}->1,
102 {array}->2,... {array}->{N}`, with `{array}->0` initialised to `{N}`:
104 | `Array {array} table {N};`
105 | `Array {array} table {expr1... exprN};`
106 | `Array {array} table "{string}";`
108 A **byte array** is a set of global bytes accessed using `{array}->0,
109 {array}->1,... {array}->({N}-1)`:
111 | `Array {array} -> {N};`
112 | `Array {array} -> {expr1 expr2... exprN};`
113 | `Array {array} -> "{string}";`
115 A **string array** is a set of global bytes accessed using `array->1,
116 array->2,... array->{N}`, with `array->0` initialised to `{N}`:
118 | `Array {array} string {N};`
119 | `Array {array} string {expr1... exprN};`
120 | `Array {array} string "{string}";`
122 A **buffer array** is a set of global bytes accessed using
123 `{array}->(WORDSIZE), {array}->(WORDSIZE+1), ...
124 {array}->(WORDSIZE+{N}-1)`, with the first **word** `{array}->0`
125 initialised to `{N}`:
127 | `Array {array} buffer {N};`
128 | `Array {array} buffer {expr1... exprN};`
129 | `Array {array} buffer "{string}";`
131 In all these cases, the characters of the initialising `{string}` are
132 unpacked to the individual word/byte elements of the array.
134 See also Objects (for **property** variables) and Routines (for **local**
137 Expressions and operators
138 =========================
140 Use parentheses `(...)` to control the order of evaluation.
142 Arithmetic/logical expressions support these operators:
144 =========== ====================================
146 `{p} - {q}` subtraction
147 `{p} * {q}` multiplication
148 `{p} / {q}` integer division
149 `{p} % {q}` remainder
150 `{p}++` increments `{p}`, returns orig value
151 `++{p}` increments `{p}`, returns new value
152 `{p}--` decrements `{p}`, returns orig value
153 `--{p}` decrements `{p}`, returns new value
154 `{p} & {q}` bitwise AND
155 `{p} | {q}` bitwise OR
156 `~{p}` bitwise NOT (inversion)
157 =========== ====================================
159 Conditional expressions return `true` or `false`; `{q}` may be a list of
160 choices `{q1} or {q2} or ... {qN}`:
162 ================== ==========================================
163 `{p} == {q}` `{p}` is equal to `{q}`
164 `{p} ~= {q}` `{p}` isn't equal to `{q}`
165 `{p} > {q}` `{p}` is greater than `{q}`
166 `{p} < {q}` `{p}` is less than `{q}`
167 `{p} >= {q}` `{p}` is greater than or equal to `{q}`
168 `{p} <= {q}` `{p}` is less than or equal to `{q}`
169 `{p} ofclass {q}` object `{p}` is of class `{q}`
170 `{p} in {q}` object `{p}` is a child of object `{q}`
171 `{p} notin {q}` object `{p}` isn't a child of object `{q}`
172 `{p} provides {q}` object `{p}` provides property `{q}`
173 `{p} has {q}` object `{p}` has attribute `{q}`
174 `{p} hasnt {q}` object `{p}` hasn't attribute `{q}`
175 ================== ==========================================
177 Boolean expressions return `true` or `false`; if `{p}` has determined the
178 result, `{q}` is not evaluated:
180 ============ ========================================
181 `{p} && {q}` both `{p}` and `{q}` are true (non-zero)
182 `{p} || {q}` either `{p}` or `{q}` is true (non-zero)
183 `~~{p}` `{p}` is false (zero)
184 ============ ========================================
186 To return -1, 0 or 1 based on unsigned comparison:
188 | `UnsignedCompare({p},{q})`
190 To return `true` if object `{q}` is a child or grandchild or... of `{p}`:
192 | `IndirectlyContains({p},{q})`
194 To return the closest common parent of two objects (or nothing):
196 | `CommonAncestor({p},{q})`
198 To return a random number `1..{N}`, or one from a list of constant values:
201 | `random({value,value, ... value})`
206 To declare a `{class_id}` - a template for a family of objects - where the
207 optional (`{N}`) limits instances created at run-time:
209 | `Class {class_id}({N})`
210 | `class {class_id} {class_id}... {class_id}`
214 | `has {attr_def} {attr_def}... {attr_def};`
216 To declare an `{obj_id}`, "`Object`" can instead be a `{class_id}`, the
217 remaining four header items are all optional, and `{arrows}` (`->`, `->
218 ->`, ...) and `{parent_obj_id}` are incompatible:
220 | `Object {arrows obj_id} "{ext_name}" {parent_obj_id}`
221 | `class {class_id} {class_id}... {class_id}`
225 | `has {attr_def} {attr_def}... {attr_def};`
227 The `class`, `with` and `has` (and also the rarely-used `private`) segments
228 are all optional, and can appear in any order.
230 To determine an object's class as one of `Class`, `Object`, `Routine`,
231 `String` (or `nothing`):
233 | `metaclass({obj_id})`
235 **has segment**: Each `{attr_def}` is either of:
240 To change attributes at run-time:
242 | `give {obj_id attr_def... attr_def};`
244 **with/private segments**: Each `{prop_def}` declares a variable (or word
245 array) and can take any of these forms (where a `{value}` is an expression,
246 a string or an embedded routine):
250 | `{property value value... value}`
252 A property variable is addressed by `{obj_id.property}` (or within the
253 object's declaration as `{self.property}`).
255 Multiple `{values}` create a property array; in this case
256 `{obj_id.#property}` is the number of bytes occupied by the array, the
257 entries can be accessed using `{obj_id.&property}-->0`,
258 `{obj_id.&property}->1`, ..., and `{obj_id.property}` refers to the value
261 A property variable inherited from an object's class is addressed by
262 `{obj_id.class_id}::{property}`; this gives the original value prior to any
263 changes within the object.
265 Manipulating the object tree
266 ============================
268 To change object relationships at run-time:
270 | `move {obj_id} to {parent_obj_id};`
273 To return the parent of an object (or nothing):
277 To return the first child of an object (or nothing):
281 To return the adjacent child of an object's parent (or nothing):
283 | `sibling({obj_id})`
285 To return the number of child objects directly below an object:
287 | `children({obj_id})`
294 | `{class_id}.remaining()`
295 | `{class_id}.create()`
296 | `{class_id}.destroy({obj_id})`
297 | `{class_id}.recreate({obj_id})`
298 | `{class_id}.copy({to_obj_id},{from_obj_id})`
302 | `{obj_id.property(a1,a2, ... a7)}`
306 | `{routine_id}.call({a1,a2, ... a7})`
311 | `{string}.print_to_array({array})`
313 Uncommon and deprecated statements
314 ==================================
316 To jump to a labelled statement:
320 | `.{label}; {statement};`
322 To terminate the program:
326 To save and restore the program state:
332 To output the Inform compiler version number:
336 To accept data from the current input stream:
338 | `read {text_array parse_array routine_id};`
340 To assign to one of 32 'low string' variables:
342 | `string {N} "{string}";`
343 | `Lowstring {string_var} "{string}";`
344 | `string {N string_var};`
349 Each `{statement}` is terminated by a semicolon "`;`".
351 A `{statement_block}` is a single `{statement}` or a series of
352 `{statements}` enclosed in braces ``{...}``.
354 An exclamation "`!`" starts a comment - the rest of the line is ignored.
356 A common statement is the assignment:
358 | `{var_id} = {expr};`
360 There are two forms of multiple assignment:
362 | `{var_id} = {var_id} = ... = {expr};`
363 | `{var_id} = {expr}, {var_id} = {expr}, ... ;`
368 A routine can have up to 15 **local variables**: word values which are
369 private to the routine and which by default are set to zero on each call.
371 Recursion is permitted.
373 A **standalone** routine:
375 * has a name, by which it is called using `{routine_id}();` can also be
376 called indirectly using `indirect({routine_id,a1,a2, ... a7})`
378 * can take arguments, using `{routine_id}({a1,a2, ... a7})`, whose values
379 initialise the equivalent local variables
381 * returns `true` at the final "`]`"
384 | `{local_var} {local_var}... {local_var};`
391 A routine **embedded** as the value of an object property:
393 * has no name, and is called when the property is invoked; can also be
394 called explicitly using `{obj_id.property}()`
396 * accepts arguments only when called explicitly
398 * returns `false` at the final "`]`"
401 | `{local_var} {local_var}... {local_var};`
408 Routines return a single value, when execution reaches the final "`]`" or
409 an explicit `return` statement:
419 To execute statements if `{expr}` is `true`; optionally, to execute other
420 statements if `{expr}` is `false`:
423 | `{statement_block}`
426 | `{statement_block}`
428 | `{statement_block}`
430 To execute statements depending on the value of `{expr}`:
432 | `switch ({expr}) {`
433 | `{value}: {statement};... {statement};`
434 | `{value}: {statement};... {statement};`
436 | `default: {statement};... {statement};`
439 where each `{value}` can be given as:
442 | `{lo_constant} to {hi_constant}`
443 | `{constant,constant,... constant}`
445 And, if you really must:
449 | `.{label}; {statement};`
454 To execute statements while `{expr}` is true:
457 | `{statement_block}`
459 To execute statements until `{expr}` is true:
462 | `{statement_block}`
465 To execute statements while a variable changes:
467 | `for ({set_var} : {loop_while_expr} : {update_var})`
468 | `{statement_block}`
470 To execute statements for all defined objects:
472 | `objectloop ({var_id})`
473 | `{statement_block}`
475 To execute statements for all objects selected by `{expr}`:
477 | `objectloop ({expr_starting_with_var})`
478 | `{statement_block}`
480 To jump out of the current innermost loop or switch:
484 To immediately start the next iteration of the current loop:
488 Displaying information
489 ======================
491 To output a list of values:
493 | `print {value},{value},... {value};`
495 To output a list of values followed by a newline, then return `true` from
498 | `print_ret {value},{value},... {value};`
500 If the first (or only) `{value}` is a string, "`print_ret`" can be
503 | `"{string}",{value}, ... {value};`
505 Each `{value}` can be an expression, a string or a rule.
507 An **expression** is output as a signed decimal value.
509 A **string** in quotes "`...`" is output as text.
511 A **rule** is one of:
513 ======================== ===============================================
514 `(number) {expr}` the `{expr}` in words
515 `(char) {expr}` the `{expr}` as a single character
516 `(string) {addr}` the string at the `{addr}`
517 `(address) {addr}` the dictionary word at the `{addr}`
518 `(name) {obj_id}` the external (short) name of the `{obj_id}`
519 `(a) {obj_id}` the short name preceded by "`a/an`",
520 by "`some`", or by nothing for proper nouns
521 `(A) {obj_id}` the short name preceded by "`A/An`",
522 by "`Some`", or by nothing for proper nouns
523 `(the) {obj_id}` the short name preceded by "`the`"
524 `(The) {obj_id}` the short name preceded by "`The`"
525 `({routine_id}){value}` the output when calling `{routine_id}({value})`
526 ======================== ===============================================
528 To output a newline character:
532 To output multiple spaces:
536 To output text in a display box:
538 | `box "{string}" "{string}"... "{string}";`
540 To change from regular to fixed-pitch font:
546 To change the font attributes:
548 | `style bold; ! use any of these`
549 | `style underline; !`
557 To specify a new verb:
559 | `Verb '{verb}' '{verb}'... '{verb}'`
560 | `* {token} {token}... {token} -> {action}`
561 | `* {token} {token}... {token} -> {action}`
563 | `* {token} {token}... {token} -> {action}`
565 where instead "`Verb`" can be "`Verb meta`", "`{action}`" can be "`{action
566 reverse}`"; `{tokens}` are optional and each is one of:
568 ==================== ==================================================
569 `'{word}'` that literal word
570 `'{w1}'/'{w2}'/...` any one of those literal words
571 `{attribute}` an object with that attribute
572 `creature` an object with `animate` attribute
573 `held` an object held by the player
574 `noun` an object in scope
575 `noun={routine_id}` an object for which `{routine_id}` returns `true`
576 `scope={routine_id}` an object in this re-definition of scope
577 `multiheld` one or more objects held by the player
578 `multi` one or more objects in scope
579 `multiexcept` as `multi`, omitting the specified object
580 `multiinside` as `multi`, omitting those in specified object
583 `{routine_id}` a general parsing routine
584 ==================== ==================================================
586 To add synonyms to an existing verb:
588 | `Verb '{verb}' '{verb}'... =`
589 | `'{existing_verb}';`
591 To modify an existing verb:
593 | `Extend '{existing_verb}' last`
594 | `* {token} {token}... {token} -> {action}`
595 | `* {token} {token}... {token} -> {action}`
597 | `* {token} {token}... {token} -> {action}`
599 where instead "`Extend`" can be "`Extend only`" and "`last`" can be
600 omitted, or changed to "`first`" or "`replace`".
602 To explicitly trigger a defined action (both `{noun}` and `{second}` are
603 optional, depending on the `{action}`):
605 | `<{action noun second}>;`
607 To explicitly trigger a defined action, then return `true` from the current
610 | `<<{action noun second}>>;`
612 Other useful directives
613 =======================
615 To set compiler switches *at the very start* of the source file:
617 | `!% {list_of_compiler_switches};`
619 To include a directive within a routine definition `[...]`, insert a hash
620 "`#`" as its first character.
622 To conditionally compile:
624 | `Ifdef {name}; ! use any one of these`
627 | `Iffalse {expr}; !`
633 To display a compile-time message:
635 | `Message "{string}";`
637 To include the contents of a file, searching the Library path:
639 | `Include "{source_file}";`
641 To include the contents of a file in the same location as the current
644 | `Include ">{source_file}";`
646 To specify that a library routine is to be replaced:
648 | `Replace {routine_id};`
650 To set the game's release number (default is 1), serial number (default is
651 today's `{yymmdd}`) and status line format (default is `score`):
654 | `Serial "{yymmdd}";`
655 | `Statusline score;`
658 To declare a new attribute common to all objects:
660 | `Attribute {attribute};`
662 To declare a new property common to all objects:
664 | `Property {property};`
665 | `Property {property expr};`
667 Uncommon and deprecated directives
668 ==================================
670 You're unlikely to need these; look them up in the *Designer's Manual* if
673 | `Abbreviate "{string}"... "{string}";`
675 | `Import {var_id var_id} ... {var_id};`
676 | `Link "{compiled_file}";`
677 | `Stub {routine_id N};`
678 | `Switches {list_of_compiler_switches};`