informqr/informqr.md

   1 % 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)
 287
 288 Statements
 289 ----------
 290
 291 Each *statement* is terminated by a semi-colon ";".
 292
 293 A *statement_block* is a single *statement* or a series of
 294 *statements* enclosed in braces {...}.
 295
 296 An exclamation "!" starts a comment - rest of line ignored.
 297
 298 A common statement is the assignment:
 299
 300     variable = expr ;
 301
 302 There are two forms of multiple assignment:
 303
 304     variable = variable = ... = expr ;
 305     variable = expr, variable = expr, ... ;
 306
 307 Routines
 308 --------
 309
 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.
 313
 314 A **standalone** routine:
 315
 316 -   has a name, by which it is called using `routine();` can also be
 317     called indirectly using
 318
 319     indirect(routine,a1,a2, ... a7)
 320
 321 -   can take arguments, using `routine(a1,a2, ... a7)`, whose values
 322     initialise the equivalent local variables
 323
 324 -   returns true at the final "]"
 325
 326         [ routine
 327             local_var local_var ... local_var ;
 328             statement;
 329             statement;
 330             ...
 331             statement;
 332             ]
 333
 334 A routine **embedded** as the value of an object property:
 335
 336 -   has no name, and is called when the property is invoked; can also
 337     be called explicitly using object.property()
 338
 339 -   accepts arguments only when called explicitly
 340
 341 -   returns false at the final "]"
 342
 343         property [
 344             local_var local_var ... local_var;
 345             statement;
 346             statement;
 347             ...
 348             statement;
 349             ]
 350
 351 Routines return a single value, when execution reaches the final "\]"
 352 or an explicit return statement:
 353
 354     return expr;
 355     return;
 356     rtrue;
 357     rfalse;
 358
 359 To define a dummy standalone routine with N local variables (unless it
 360 already exists):
 361
 362     Stub routine N;
 363
 364 Flow control
 365 ------------
 366
 367 To execute statements if *expr* is true; optionally, to execute other
 368 statements if *expr* is false:
 369
 370     if (expr)
 371         statement_block
 372     if (expr)
 373         statement_block
 374     else
 375         statement_block
 376
 377 To execute statements depending on the value of *expr*:
 378
 379     switch (expr) {
 380         value: statement; ... statement;
 381         value: statement; ... statement;
 382         ...
 383         default: statement; ... statement;
 384         }
 385
 386 where each *value* can be given as:
 387
 388     constant
 389     lo_constant to hi_constant
 390     constant,constant, ... constant
 391
 392 Loop control
 393 ------------
 394
 395 To execute statements while *expr* is true:
 396
 397     while (expr)
 398         statement_block
 399
 400 To execute statements until *expr* is true:
 401
 402     do
 403         statement_block
 404         until (expr)
 405
 406 To execute statements while a variable changes:
 407
 408     for (set_var : loop_while_expr : update_var )
 409         statement_block
 410
 411 To execute statements for all defined objects:
 412
 413     objectloop (variable)
 414         statement_block
 415
 416 To execute statements for all objects selected by *expr*:
 417
 418     objectloop (expr_starting_with_variable)
 419         statement_block
 420
 421 To jump out of the current innermost loop or switch:
 422
 423     break;
 424
 425 To immediately start the next iteration of the current loop:
 426
 427     continue;
 428
 429 Displaying information
 430 ----------------------
 431
 432 To output a list of values:
 433
 434     print value,value, ... value;
 435
 436 To output a list of values followed by a newline, then return `true`
 437 from the current routine:
 438
 439     print_ret value,value, ... value;
 440
 441 If the first (or only) *value* is a string, "`print_ret`" can be
 442 omitted:
 443
 444     "string",value, ... value ;
 445
 446 Each *value* can be an expression, a string or a rule.
 447
 448 An **expression** is output as a signed decimal value.
 449
 450 A **string** in quotes "..." is output as text.
 451
 452 A **rule** is one of:
 453
 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   -------------------- ------------------------------------------------
 465
 466 To output a newline character:
 467
 468     new_line;
 469
 470 To output multiple spaces:
 471
 472     spaces expr;
 473
 474 To output text in a display box:
 475
 476     box "string " "string " ... "string ";
 477
 478 To change from regular to fixed-pitch font:
 479
 480     font off;
 481     ...
 482     font on;
 483
 484 To change the font attributes:
 485
 486     style bold;         ! use one or more of these
 487     style underline ;   !
 488     style reverse ;     !
 489     ...
 490     style roman;
 491
 492 Uncommon and deprecated statements
 493 ----------------------------------
 494
 495 To jump to a labelled statement:
 496
 497     jump label;
 498     ...
 499     .label; statement;
 500
 501 To terminate the program:
 502
 503     quit
 504
 505 To save and restore the program state:
 506
 507     save label;
 508     ...
 509     restore label;
 510
 511 To output the Inform compiler version number:
 512
 513 inversion;
 514
 515 To accept data from the current input stream:
 516
 517     read text_array parse_array routine;
 518
 519 To assign to one of 32 'low string' variables:
 520
 521     string N "string";
 522     Lowstring string_var "string";
 523     string N string_var;