1 % Inform in four minutes
2 % Roger Firth <roger@firthworks.com>
4 A quick reference to the Inform programming language.
6 Copyright © 2002 Roger Firth <roger@firthworks.com>. Copying and
7 distribution, with or without modification, are permitted in any
8 medium without royalty provided the copyright notice and this notice
11 <http://www.firthworks.com/roger/>
13 Version 1.3 (March 2002)
15 The road to brevity is via imprecision and through solecism.
20 A Z-code **word** literal uses sixteen bits (whereas a Glulx word has
21 thirty-two bits). A **byte** literal is always eight bits.
23 - Decimal: `-32768` to `32767`\
24 Hexadecimal: `$0` to `$FFFF`\
25 Binary: `$$0` to `$$1111111111111111`
28 - Dictionary word: `'aardvark'` (up to nine characters significant);
29 use circumflex "`^`" to denote apostrophe.\
30 Plural word: `'aardvarks//p'`\
31 Single-character word: `"a"` (`name` property only) or `'a//'`
32 - String: `"aardvark's adventure"` (maximum around 4000 characters);
33 can include special values including:
35 ------------- ------------------------------------
42 @`a a with a grave accent "`à`", et al
43 @LL pound sign "£", et al
44 @00 ... @31 low string 0..31
45 ------------- ------------------------------------
50 The identifier of an Inform *constant*, *variable*, *array*, *class*,
51 *object*, *property*, *attribute*, *routine* or *label*. Up to 32
52 characters: alphabetic (case not significant), numeric and underscore,
53 with the first character not a digit.
55 Expressions and Operators
56 -------------------------
58 Use parentheses (...) to control the order of evaluation.
59 Arithmetic/logical expressions support these operators:
61 ---------- ---------------------------------------------
64 *p * q* multiplication
65 *p / q* integer division
67 *p++* increments *p*, evaluates to original value
68 *++p* increments *p*, evaluates to new value
69 *p--* decrements *p*, evaluates to original value
70 *--p* decrements *p*, evaluates to new value
73 *~p* bitwise NOT (inversion)
74 ---------- ---------------------------------------------
76 Conditional expressions return `true` (1) or `false` (0); *q* may be a
77 list of alternatives *q1* `or` *q2* `or` ... *qN*:
79 ---------------- ----------------------------------------
80 *p == q* *p* is equal to *q*
81 *p ~= q* *p* isn't equal to *q*
82 *p* > *q* *p* is greater than *q*
83 *p < q* *p* is less than *q*
84 *p >= q* *p* is greater than or equal to *q*
85 *p <= q* *p* is less than or equal to *q*
86 *p ofclass q* object *p* is of class *q*
87 *p in q* object *p* is a child of object *q*
88 *p notin q* object *p* isn't a child of object *q*
89 *p provides q* object *p* provides property *q*
90 *p has q* object *p* has attribute *q*
91 *p hasnt q* object *p* hasn't attribute *q*
92 ---------------- ----------------------------------------
94 Boolean expressions return `true` (1) or `false` (0):
96 -------- ----------------------------------
97 p && q both p and q are true (non-zero)
98 p || q either p or q is true (non-zero)
100 -------- ----------------------------------
102 To return -1, 0 or 1 based on unsigned comparison:
106 To return `true` if object *q* is a child or grand-child or... of *p*:
108 IndirectlyContains(p,q)
110 To return a random number 1..*N*, or one from a list of constant
114 random(value,value, ... value )
119 Named word values, unchanging at run-time, which are by default
123 Constant constant = expr;
125 Standard constants are `true` (1), `false` (0) and `nothing` (0), also
128 To define a constant (unless it already exists):
130 Default constant expr ;
135 Named word/byte values which can change at run-time and are by default
138 A **global** variable is a single word:
141 Global variable = expr;
143 A **word array** is a set of global words accessed using `array-->0`,
144 `array-->1`, ... `array-->(N-1)`:
147 Array array --> expr1 expr2 ... exprN;
148 Array array --> "string";
150 A **table array** is a set of global words accessed using
151 *array-->1*, *array-->2*, ... *array-->N*, with
152 *array-->0* initialized to *N*:
154 Array array table N ;
155 Array array table expr1 expr2 ... exprN
156 Array array table "string";
158 A **byte array** is a set of global bytes accessed using
159 *array->0*, *array->1*, ... *array->(N-1)*:
162 Array array -> expr1 expr2 ... exprN;
163 Array array -> "string";
165 A **string array** is a set of global bytes accessed using
166 *array->1*, *array->2*, ... *array->N*, with *array->0*
169 Array array string N;
170 Array array string expr1 expr2 ... exprN;
171 Array array string "string";
173 In all these cases, the characters of the initializing *string* are
174 unpacked to the individual word/byte elements of the array. See also
175 Objects (for **property** variables) and Routines (for **local**
181 To declare a *class* - a template for a family of objects -
182 where the optional (*N*) limits instances created at run-time:
185 class class class ... class
186 has attr_def attr_def ... attr_def
191 To declare an *object*; "`Object`" can instead be a *class*, the
192 remaining four header items are all optional, and *arrows*
193 (`->`, `->` `->`, ...) and *parent_object* are incompatible:
195 Object arrows object "ext_name " parent_object
196 class class class ... class
197 has attr_def attr_def ... attr_def
202 The `class`, `has` and `with` (and also the rarely-used `private`)
203 segments are all optional, and can appear in any order.
205 To determine an object's class as one of `Class`, `Object`,
206 `Routine`, `String` (or `nothing`):
210 **has segment**: Each *attr_def* is either of:
215 To change attributes at run-time:
217 give object attr_def attr_def ... attr_def;
219 **with/private segments**: Each *prop_def* declares a variable
220 (or word array) and can take any of these forms (where a
221 *value* is an expression, a string or an embedded routine):
225 property value value ... value
227 A property variable is addressed by *object.property* (or
228 within the object's declaration as *self.property*).
230 Multiple values create a property array; in this case
231 *object.#property* is the number of **bytes** occupied by the
232 array, the entries can be accessed using
233 *object.&property-->0*, *object.&property-->1*, ... , and
234 *object.property* refers to the value of the first entry.
236 A property variable inherited from an object's class is
237 addressed by *object.class::property*; this gives the
238 original value prior to any changes within the object.
240 Manipulating the object tree
241 ----------------------------
243 To change object relationships at run-time:
245 move object to parent_object ;
248 To return the parent of an object (or nothing):
252 To return the first child of an object (or nothing):
256 To return the adjacent child of an object's parent (or nothing):
260 To return the number of child objects directly below an object:
271 class.destroy(object)
272 class.recreate(object)
273 class.copy(to_object,from_object)
277 object.property(a1,a2, ... a7)
281 routine.call(a1,a2, ... a7)
286 string.print_to_array(array)
291 Each *statement* is terminated by a semi-colon ";".
293 A *statement_block* is a single *statement* or a series of
294 *statements* enclosed in braces {...}.
296 An exclamation "!" starts a comment - rest of line ignored.
298 A common statement is the assignment:
302 There are two forms of multiple assignment:
304 variable = variable = ... = expr ;
305 variable = expr, variable = expr, ... ;
310 A routine can have up to 15 local variables: word values which are
311 private to the routine and which by default are set to zero on each
312 call. Recursion is permitted.
314 A **standalone** routine:
316 - has a name, by which it is called using `routine();` can also be
317 called indirectly using
319 indirect(routine,a1,a2, ... a7)
321 - can take arguments, using `routine(a1,a2, ... a7)`, whose values
322 initialise the equivalent local variables
324 - returns true at the final "]"
327 local_var local_var ... local_var ;
334 A routine **embedded** as the value of an object property:
336 - has no name, and is called when the property is invoked; can also
337 be called explicitly using object.property()
339 - accepts arguments only when called explicitly
341 - returns false at the final "]"
344 local_var local_var ... local_var;
351 Routines return a single value, when execution reaches the final "]"
352 or an explicit return statement:
359 To define a dummy standalone routine with N local variables (unless it
367 To execute statements if *expr* is true; optionally, to execute other
368 statements if *expr* is false:
377 To execute statements depending on the value of *expr*:
380 value: statement; ... statement;
381 value: statement; ... statement;
383 default: statement; ... statement;
386 where each *value* can be given as:
389 lo_constant to hi_constant
390 constant,constant, ... constant
395 To execute statements while *expr* is true:
400 To execute statements until *expr* is true:
406 To execute statements while a variable changes:
408 for (set_var : loop_while_expr : update_var )
411 To execute statements for all defined objects:
413 objectloop (variable)
416 To execute statements for all objects selected by *expr*:
418 objectloop (expr_starting_with_variable)
421 To jump out of the current innermost loop or switch:
425 To immediately start the next iteration of the current loop:
429 Displaying information
430 ----------------------
432 To output a list of values:
434 print value,value, ... value;
436 To output a list of values followed by a newline, then return `true`
437 from the current routine:
439 print_ret value,value, ... value;
441 If the first (or only) *value* is a string, "`print_ret`" can be
444 "string",value, ... value ;
446 Each *value* can be an expression, a string or a rule.
448 An **expression** is output as a signed decimal value.
450 A **string** in quotes "..." is output as text.
452 A **rule** is one of:
454 -------------------- ------------------------------------------------
455 `(number)` *expr* the *expr* in words
456 `(char)` *expr* the *expr* as a single character
457 `(string)` *addr* the string at the *addr*
458 `(address)` *addr* the dictionary word at the *addr*
459 `(name)` *object* the external (short) name of the object
460 `(a)` *object* the short name preceded by "a/an"
461 `(the)` *object* the short name preceded by "the"
462 `(The)` *object* the short name preceded by "The"
463 `(routine)` value the output when calling `routine(value)`
464 -------------------- ------------------------------------------------
466 To output a newline character:
470 To output multiple spaces:
474 To output text in a display box:
476 box "string " "string " ... "string ";
478 To change from regular to fixed-pitch font:
484 To change the font attributes:
486 style bold; ! use one or more of these
492 Uncommon and deprecated statements
493 ----------------------------------
495 To jump to a labelled statement:
501 To terminate the program:
505 To save and restore the program state:
511 To output the Inform compiler version number:
515 To accept data from the current input stream:
517 read text_array parse_array routine;
519 To assign to one of 32 'low string' variables:
522 Lowstring string_var "string";
528 To specify a new verb:
530 Verb 'verb ' 'verb ' ... 'verb '
531 * token token ... token -> action
532 * token token ... token -> action
534 * token token ... token -> action;
536 where instead "`Verb`" can be "`Verb meta`", "*action*" can be
537 "`action reverse`"; *tokens* are optional and each is one of:
539 ----------------- ----------------------------------------------
540 'word' that literal word
541 'w1'/'w2'/... any one of those literal words
542 attribute an object with that attribute
543 creature an object with `animate` attribute
544 held an object held by the player
545 noun an object in scope
546 noun=`routine` an object for which *routine* returns `true`
547 scope=`routine` an object in this re-definition of scope
548 multiheld one or more objects held by the player
549 multi one or more objects in scope
550 multiexcept as multi, omitting the specified object
551 multiinside as multi, omitting those in specified object
554 routine a general parsing routine
555 ----------------- ----------------------------------------------
557 To add synonyms to an existing verb:
559 Verb 'verb ' 'verb ' ... = 'existing_verb';
561 To modify an existing verb:
563 Extend 'existing_verb ' last
564 * token token ... token –> action
565 * token token ... token –> action
567 * token token ... token –> action ;
569 where instead "`Extend`" can be "`Extend only`" and "`last`" can be
570 omitted, or changed to "`first`" or "`replace`"
572 To explicitly trigger a defined action (both *noun* and *second* are
573 optional, depending on the action):
575 <action noun second>;
577 To explicitly trigger a defined action, then return `true` from the
580 <<action noun second >>;
582 Other useful directives
583 -----------------------
585 To include a directive within a routine definition [...], insert a
586 hash "#" as its first character.
588 To conditionally compile:
590 Ifdef name; ! use any one of these
599 To display a compile-time message:
603 To include the contents of a file, searching the Library path:
605 Include "source_file";
607 To include the contents of a file in the same location as the current
610 Include ">source_file";
612 To specify that a library routine is to be replaced:
616 To set the game's release number (default is 1), serial number
617 (default is today's *yymmdd*) and status line format (default is
625 To declare a new attribute common to all objects:
627 Attribute attribute ;
629 To declare a new property common to all objects:
632 Property property expr;
634 Uncommon and deprecated directives
635 ----------------------------------
637 You're unlikely to need these; look them up if necessary.
639 Abbreviate "string " "string " ... "string ";
641 Import variable variable ... variable;
642 Link "compiled_file";
643 Switches list_of_compiler_switches;
649 A minimal source file:
651 Constant Story "MYGAME";
652 Constant Headline "^My first Inform game.^";
653 Constant MANUAL_PRONOUNS;
658 [ Initialise; location = study; "^Hello!^"; ];
661 with description "A bare room."
665 with before [; Take,Pull,Push,Pushdir:
666 print_ret (The) self,
667 " is too heavy for that."; ]
668 has static supporter;
670 Room study "Your study';
672 Furniture "writing desk" study
673 with name 'writing' 'desk' 'table';
675 Object -> -> axe "rusty axe"
676 with name 'rusty' 'blunt' 'axe' 'hatchet'
677 description "It seems old and blunt.";
686 inform commands source_file
688 Useful *commands* include:
690 -------------- ------------------------------------------------
691 -~S disable both Strict checks and Debug tools
692 -~SD disable Strict checks, enable Debug tools
693 -X enable Infix debugger
694 -r output all game text to file (for spell-check)
695 -s display game's size and other statistics
696 -z display game's memory map
697 -v8 compile in Version 8 format (default is v5)
698 +dir,dir,... search for Included files in these directories
699 -------------- ------------------------------------------------
701 To display full compiler help, type: