+
+Manipulating the object tree
+----------------------------
+
+To change object relationships at run-time:
+
+ move object to parent_object ;
+ remove object ;
+
+To return the parent of an object (or nothing):
+
+ parent(object)
+
+To return the first child of an object (or nothing):
+
+ child(object)
+
+To return the adjacent child of an object's parent (or nothing):
+
+ sibling(object)
+
+To return the number of child objects directly below an object:
+
+ children(object)
+
+Message passing
+---------------
+
+To a class:
+
+ class.remaining()
+ class.create()
+ class.destroy(object)
+ class.recreate(object)
+ class.copy(to_object,from_object)
+
+To an object:
+
+ object.property(a1,a2, ... a7)
+
+To a routine:
+
+ routine.call(a1,a2, ... a7)
+
+To a string:
+
+ string.print()
+ string.print_to_array(array)
+
+Statements
+----------
+
+Each *statement* is terminated by a semi-colon ";".
+
+A *statement_block* is a single *statement* or a series of
+*statements* enclosed in braces {...}.
+
+An exclamation "!" starts a comment - rest of line ignored.
+
+A common statement is the assignment:
+
+ variable = expr ;
+
+There are two forms of multiple assignment:
+
+ variable = variable = ... = expr ;
+ variable = expr, variable = expr, ... ;
+
+Routines
+--------
+
+A routine can have up to 15 local variables: word values which are
+private to the routine and which by default are set to zero on each
+call. Recursion is permitted.
+
+A **standalone** routine:
+
+- has a name, by which it is called using `routine();` can also be
+ called indirectly using
+
+ indirect(routine,a1,a2, ... a7)
+
+- can take arguments, using `routine(a1,a2, ... a7)`, whose values
+ initialise the equivalent local variables
+
+- returns true at the final "]"
+
+ [ routine
+ local_var local_var ... local_var ;
+ statement;
+ statement;
+ ...
+ statement;
+ ]
+
+A routine **embedded** as the value of an object property:
+
+- has no name, and is called when the property is invoked; can also
+ be called explicitly using object.property()
+
+- accepts arguments only when called explicitly
+
+- returns false at the final "]"
+
+ property [
+ local_var local_var ... local_var;
+ statement;
+ statement;
+ ...
+ statement;
+ ]
+
+Routines return a single value, when execution reaches the final "\]"
+or an explicit return statement:
+
+ return expr;
+ return;
+ rtrue;
+ rfalse;
+
+To define a dummy standalone routine with N local variables (unless it
+already exists):
+
+ Stub routine N;
+
+Flow control
+------------
+
+To execute statements if *expr* is true; optionally, to execute other
+statements if *expr* is false:
+
+ if (expr)
+ statement_block
+ if (expr)
+ statement_block
+ else
+ statement_block
+
+To execute statements depending on the value of *expr*:
+
+ switch (expr) {
+ value: statement; ... statement;
+ value: statement; ... statement;
+ ...
+ default: statement; ... statement;
+ }
+
+where each *value* can be given as:
+
+ constant
+ lo_constant to hi_constant
+ constant,constant, ... constant
+
+Loop control
+------------
+
+To execute statements while *expr* is true:
+
+ while (expr)
+ statement_block
+
+To execute statements until *expr* is true:
+
+ do
+ statement_block
+ until (expr)
+
+To execute statements while a variable changes:
+
+ for (set_var : loop_while_expr : update_var )
+ statement_block
+
+To execute statements for all defined objects:
+
+ objectloop (variable)
+ statement_block
+
+To execute statements for all objects selected by *expr*:
+
+ objectloop (expr_starting_with_variable)
+ statement_block
+
+To jump out of the current innermost loop or switch:
+
+ break;
+
+To immediately start the next iteration of the current loop:
+
+ continue;
+
+Displaying information
+----------------------
+
+To output a list of values:
+
+ print value,value, ... value;
+
+To output a list of values followed by a newline, then return `true`
+from the current routine:
+
+ print_ret value,value, ... value;
+
+If the first (or only) *value* is a string, "`print_ret`" can be
+omitted:
+
+ "string",value, ... value ;
+
+Each *value* can be an expression, a string or a rule.
+
+An **expression** is output as a signed decimal value.
+
+A **string** in quotes "..." is output as text.
+
+A **rule** is one of:
+
+ -------------------- ------------------------------------------------
+ `(number)` *expr* the *expr* in words
+ `(char)` *expr* the *expr* as a single character
+ `(string)` *addr* the string at the *addr*
+ `(address)` *addr* the dictionary word at the *addr*
+ `(name)` *object* the external (short) name of the object
+ `(a)` *object* the short name preceded by "a/an"
+ `(the)` *object* the short name preceded by "the"
+ `(The)` *object* the short name preceded by "The"
+ `(routine)` value the output when calling `routine(value)`
+ -------------------- ------------------------------------------------
+
+To output a newline character:
+
+ new_line;
+
+To output multiple spaces:
+
+ spaces expr;
+
+To output text in a display box:
+
+ box "string " "string " ... "string ";
+
+To change from regular to fixed-pitch font:
+
+ font off;
+ ...
+ font on;
+
+To change the font attributes:
+
+ style bold; ! use one or more of these
+ style underline ; !
+ style reverse ; !
+ ...
+ style roman;
\ No newline at end of file