informqr/informqr.md

   1 o% Inform in four minutes
   2 % Roger Firth <roger@firthworks.com>
   3
   4 A quick reference to the Inform programming language.
   5
   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
   9 are preserved.
  10
  11 <http://www.firthworks.com/roger/>
  12
  13 Version 1.3 (March 2002)
  14
  15 The road to brevity is via imprecision and through solecism.
  16
  17 Literals
  18 --------
  19
  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.
  22
  23 -   Decimal: `-32768` to `32767`\
  24     Hexadecimal: `$0` to `$FFFF`\
  25     Binary: `$$0` to `$$1111111111111111`
  26 -   Action: `##Look`
  27 -   Character: `'a'`
  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:
  34
  35   ------------- ------------------------------------
  36   ^             newline
  37   ~             quote (")
  38   @@64          at sign "@"
  39   @@92          backslash ""
  40   @@94          circumflex "^"
  41   @@126         tilde "~"
  42   @`a           a with a grave accent "`à`", et al
  43   @LL           pound sign "£", et al
  44   @00 ... @31   low string 0..31
  45   ------------- ------------------------------------
  46
  47 Names
  48 -----
  49
  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.
  54
  55 Expressions and Operators
  56 -------------------------
  57
  58 Use parentheses (...) to control the order of evaluation.
  59 Arithmetic/logical expressions support these operators:
  60
  61   ---------- ---------------------------------------------
  62   *p + q*    addition
  63   *p - q*    subtraction
  64   *p * q*    multiplication
  65   *p / q*    integer division
  66   *p % q*    remainder
  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
  71   *p & q*    bitwise AND
  72   *p | q*    bitwise OR
  73   *~p*       bitwise NOT (inversion)
  74   ---------- ---------------------------------------------
  75
  76 Conditional expressions return `true` (1) or `false` (0); *q* may be a
  77 list of alternatives *q1* `or` *q2* `or` ... *qN*:
  78
  79   ---------------- ----------------------------------------
  80   *p == q*         *p* is equal to *q*
  81   *p ~= q*         *p* isn't equal to *q*
  82   *p* &gt; *q*     *p* is greater than *q*
  83   *p &lt; q*       *p* is less than *q*
  84   *p &gt;= q*      *p* is greater than or equal to *q*
  85   *p &lt;= 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   ---------------- ----------------------------------------
  93
  94 Boolean expressions return `true` (1) or `false` (0):
  95
  96   -------- ----------------------------------
  97   p && q   both p and q are true (non-zero)
  98   p || q   either p or q is true (non-zero)
  99   ~~p      p is false (zero)
 100   -------- ----------------------------------
 101
 102 To return -1, 0 or 1 based on unsigned comparison:
 103
 104     UnsignedCompare(p,q)
 105
 106 To return `true` if object *q* is a child or grand-child or... of *p*:
 107
 108     IndirectlyContains(p,q)
 109
 110 To return a random number 1..*N*, or one from a list of constant
 111 values:
 112
 113     random(N )
 114     random(value,value, ... value )
 115
 116 Constants
 117 ---------
 118
 119 Named word values, unchanging at run-time, which are by default
 120 initialised to zero:
 121
 122     Constant constant;
 123     Constant constant = expr;
 124
 125 Standard constants are `true` (1), `false` (0) and `nothing` (0), also
 126 `NULL` (-1).
 127
 128 To define a constant (unless it already exists):
 129
 130     Default constant expr ;
 131
 132 Variables and Arrays
 133 --------------------
 134
 135 Named word/byte values which can change at run-time and are by default
 136 initialised to zero.
 137
 138 A **global** variable is a single word:
 139
 140     Global variable;
 141     Global variable = expr;
 142
 143 A **word array** is a set of global words accessed using `array-->0`,
 144 `array-->1`, ... `array-->(N-1)`:
 145
 146     Array array --> N;
 147     Array array --> expr1 expr2 ... exprN;
 148     Array array --> "string";
 149
 150 A **table array** is a set of global words accessed using
 151 *array--&gt;1*, *array--&gt;2*, ... *array--&gt;N*, with
 152 *array--&gt;0* initialized to *N*:
 153
 154     Array array table N ;
 155     Array array table expr1 expr2 ... exprN
 156     Array array table "string";
 157
 158 A **byte array** is a set of global bytes accessed using
 159 *array-&gt;0*, *array-&gt;1*, ... *array-&gt;(N-1)*:
 160
 161     Array array -> N;
 162     Array array -> expr1 expr2 ... exprN;
 163     Array array -> "string";
 164
 165 A **string array** is a set of global bytes accessed using
 166 *array-&gt;1*, *array-&gt;2*, ... *array-&gt;N*, with *array-&gt;0*
 167 initialized to *N*:
 168
 169     Array array string N;
 170     Array array string expr1 expr2 ... exprN;
 171     Array array string "string";
 172
 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**
 176 variables).
 177
 178 Classes and Objects
 179 -------------------
 180
 181 To declare a *class* - a template for a family of objects -
 182 where the optional (*N*) limits instances created at run-time:
 183
 184     Class       class(N)
 185       class     class class ... class
 186       has       attr_def attr_def ... attr_def
 187       with      prop_def,
 188                 ...
 189                 prop_def;
 190
 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:
 194
 195     Object      arrows object "ext_name " parent_object
 196       class     class class ... class
 197       has       attr_def attr_def ... attr_def
 198       with      prop_def,
 199                 ...
 200                 prop_def;
 201
 202 The `class`, `has` and `with` (and also the rarely-used `private`)
 203 segments are all optional, and can appear in any order.
 204
 205 To determine an object's class as one of `Class`, `Object`,
 206 `Routine`, `String` (or `nothing`):
 207
 208     metaclass(object)
 209
 210 **has segment**: Each *attr_def* is either of:
 211
 212     attribute
 213     ~attribute
 214
 215 To change attributes at run-time:
 216
 217     give object attr_def attr_def ... attr_def;
 218
 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):
 222
 223     property
 224     property value
 225     property value value ... value
 226
 227 A property variable is addressed by *object.property* (or
 228 within the object's declaration as *self.property*).
 229
 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.
 235
 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.
 239
 240 Manipulating the object tree
 241 ----------------------------
 242
 243 To change object relationships at run-time:
 244
 245     move object to parent_object ;
 246     remove object ;
 247
 248 To return the parent of an object (or nothing):
 249
 250     parent(object)
 251
 252 To return the first child of an object (or nothing):
 253
 254     child(object)
 255
 256 To return the adjacent child of an object's parent (or nothing):
 257
 258     sibling(object)
 259
 260 To return the number of child objects directly below an object:
 261
 262     children(object)
 263
 264 Message passing
 265 ---------------
 266
 267 To a class:
 268
 269     class.remaining()
 270     class.create()
 271     class.destroy(object)
 272     class.recreate(object)
 273     class.copy(to_object,from_object)
 274
 275 To an object:
 276
 277     object.property(a1,a2, ... a7)
 278
 279 To a routine:
 280
 281     routine.call(a1,a2, ... a7)
 282
 283 To a string:
 284
 285     string.print()
 286     string.print_to_array(array)