Acode minor directives supported by acdc 12.34

Terminology.

All declared entities may be referenced by any synonyms (vocabulary ones
or not) assigned to them.

Value bearing entities are global variables, local variables, objects, 
places, and texts.

A variable is either a global or a local variable.

A variable may hold either a value or a reference (pointer) to some
declared entity other than a local variable. The A-code kernel can tell
the difference between between values and references.

Automatic dereferencing of variables which point to some entity is 
signalled by suffixing directive arguments in the below list by *.
Only one level of dereferencing is automatic.

A value is a literal number, a symbolic constant, or the value of a
value-bearing entity. NB references are also values and may be
manipulated as such, unless automatic de-referencing is indicated.

A vocabulary word is a verb or a name of an object or a location, which
can be used by the player.

Conditionals.

Conditionals evaluate to true or false. If true, the immediately following
code block is executed. If false, execution skips the immediately
following code block.

IFEQ X Y
   Both X and Y are values. True iff X == Y
IFNE X Y
   Both X and Y are values. True iff X != Y
IFLT X Y
   Both X and Y are values. True iff X < Y
IFLE X Y
   Both X and Y are values. True iff X <= Y
IFGT X Y
   Both X and Y are values. True iff X > Y
IFGE X Y
   Both X and Y are values. True iff X >= Y
IFAT X* [Y* ...]
   X (and Y etc...) is a location.
   True iff the player is currently at any of the specified locations.
IFHAVE X* [Y]
   X is an object. Y is optional and can be either a value or an object
   flag. True iff the nominated object is carried by the player and (if
   Y is specified) in the state indicated by Y, or has the Y flag set.
IFHERE X* [Y]
   X is an object. Y is optional and can be either a value or an object
   flag. True iff the nominated object is in the same location as the
   player and (if Y is specified) in the state indicated by Y, or has
   the Y flag set.
IFNEAR X* [Y]
   X is an object. Y is optional and can be either a value or an object
   flag. True iff the nominated object is carried by the player or is in
   the same location as the player and (if Y is specified) in the state
   indicated by Y, or has the Y flag set.
IFLOC X* Y* [Z* ...]
   X is an object. Y (and Z etc...) is a place. True iff the nomonated
   object is at any of the listed locations.
IFIS X Y [Z ...]
   X is a local or global variable. Y, and any further optional arguments,
   is a referrable entity (object, place, text or variable). True iff X is
   a pointer to Y.
IFINRANGE X Y Z
   All three arguments are values. True iff Y <= X <= Z
IFKEY X* [Y* ...]
   X (and Y etc...) is a vocabulary word. True iff all of the specified
   arguments occur in the player's command.NB: Due to the current 
   limitations of the A-code parser, any IFKEY directive with more than
   two arguments will always return false.
IFANY X* [Y* ...]
   X (and Y etc...) is a vocabulary word. True iff any of the specified
   arguments occur in the player's command.
IFFLAG X* [Y*]
   X is a flag bearing entity. Y is a flag. True iff the entity X has
   the flag Y set. If the entity is of a kind without flags, the test
   returns FALSE.
IFHTML
   True iff the program is running in the HTTP server mode or the CGI mode.
IFCGI
   True iff the program is running in the CGI mode.
IFDOALL
   True iff the program is in the command loop processing the ALL psudo-
   object.
IFTYPED X
   X is a literal token. True iff the token matches a word actually 
   entered by the player in the command, with no abbreviation or typo
   processing.
CHANCE X*
   True with the probability of X%.
QUERY X*
   X is a text, which is displayed to the player. True iff the player replies
   with anything starting with y or Y. (NB: Cannot be used in the CGI mode!)
   
   
Conditional connectives. NB: tests which cannot affect the result, are
not evaluated.

NOT
   negates the immediately following test.
AND
   requires both the test so far and the subsequent tests to be true.
OR
   requires the test so far and/or the subsequent tests to be true.
XOR
   requires the test so far *or* the subsequent tests to be true (but
   not both!)

Conditional block delimiters.

ELSE
   Head of code block to be executed if a conditional evaluates to false.
FIN
   End of conditional (primary or alternative) or iterative code block. 
OTHERWISE
   End of an alternative code. Expects a conditional as the next statement.
EOT
   Deprecated sysnonym of FIN.

Deprecated conditionals. These are equivalent to the indicated
directives, except that they can only have the primary code block
associated with them, which must be terminated by a major directive
(rather than by ELSE, OTHERWISE or FIN).

KEYWORD use IFKEY instead
HAVE use IFHAVE instead
NEAR use IFNEAR instead
HERE use IFHERE instead
ATLOC use IFAT instead
ANYOF use ifany instead

Iterative directives.

ITOBJ X [Y* ...]
   X is a variable. Y (etc...) is either a place or a flag. Causes the
   immediately following code block (terminated by FIN) to be executed
   repeatedly, with the variable X iterating (as a pointer) through all 
   objects matchine the specified criteria (or just all objects if no
   criteria specified). If there are no matching objects, the code block
   is skipped. NB: As far as the kernel is concerned, an object has a 
   unique location, even if it is tagged as schizoid.
ITLOC (ITPLACE) X [Y* Z*]
   X is a variable. Y and Z are places. Causes the associated code block
   to be executed repeatedly, with the variable X iterating through
   all locations or (if Y and Z present) from location Y to location Z.
   In its three argument form this directive is completely equivalent 
   to ITERATE with those three arguments.
ITERATE X Y* Z*
   X is a variable. Y and Z are some entities or values. Causes the
   associated code block (terminated by FIN) to be executed repeatedly, 
   with the variable X iterating through the indicated range.
NEXT
   Skip the rest of the iteration black and proceed with the next iteration.
BREAK
   Break out of the iteration block.
EOI
   Deprecated end of iteration block. Use FIN instead.

Various fiddling.

EXEC X* Y
   X is a constant or a variable. Y is a variable. Execute a special action
   indicated by X, possibly returning some outcome value in the variable Y.
   (See the separate list of special actions for the meanings of values of 
   X.)
FAKEARG X* Y*
   X and Y are both vocabulary words (verb, place or object). If X is used 
   in the command being processed, pretend that the word Y was used
   instead, but without altering the command itself
FAKECOM X* Y*
   X and Y are both vocabulary words (verb, place or object). If X is used 
   in the command being processed, pretend that the word Y was used instead.
   Unlike FAKEARG this directive also fiddles the text string of the command
   to change it to the text string appropriate for Y.
VERBATIM {ARG1|ARG2}
   Set ARG1 or ARG2 text to whatever corresponding string player
   actually typed.

Program control.

LOCAL X
   Declares a local variable. All local declarations must come immediately
   after the PROCEDURE major directive, before any executable code.
CALL X* [Y ...]
   X is a verb a place (or place reference) or a procedure. Any optional 
   arguments (Y etc...) are passed by value as parameters of the called 
   -procedure.
PROCEED
   Return from the current procedure (or jump to the next INIT or REPEAT
   section if not in a procedure.)
QUIT
   Restart processing of REPEAT sections from the beginning.
STOP
   Exit the A-code program

Player movement.

GOTO X*
   X is a location or location reference. Relocates the player to
   the indicated location. (Strictly speaking, a synonym of MOVE)
MOVE [X ...] Y*
   X (etc...) is a vocabulary word.
   Y is a place or a place reference. If no optional argument are given,
   exactly equivalent to GOTO Y. If optional arguments given, player
   is moved to Y only if any the the indicated vocabulary words are
   present in the player's command.
SMOVE [X ...] Y* Z*
   X (etc...) is a vocabulary word.
   Y is a place or a place reference. Z is a text reference.
   If no optional arguments are given, or of one of the optional
   arguments is a vocabulaty word used in the player's command,
   the player's location is changed to Y and the text Z is output.
   NB: Could make Z* optional and fold all three of GOTO, MOVE and SMOVE into
   one directive (MOVE) with GOTO and smove as deprecated synonyms.
   
Text generation.

SAY X* [Y*]
   X is a text, an object or a place. Y is a value. Outputs text X,
   with the explicit qualifier Y.
RESAY X* [Y*]
   Like SAY, but first zaps all text accumulated so far.
QUIP X* [Y*]
   X is a text, an object or a place. Y is a value. Outputs text X,
   with the explicit qualifier Y and then "quits", i.e. restarts
   the REPEAT loop from the top.
RESPOND X* [...] Y* [Z*]
   X (etc...) is a vocabulary word 
   (verb, object or place). Y is a text, an object or a place. Z is
   a value. If any of the specified vocabulary words occur in the 
   player's command, outputs the text of Y, with the explicit qualifier Z 
   and then "quits", i.e. restarts the REPEAT loop from the top.
   NB: QUIP really ought to be a synonym, with X being optional too.
DESCRIBE X* [Y*]
   X is an object or a place. Y is a value. Outputs the most detailed
   description of X, explicitly qualified by Y.
VOCAB W X Y [Z]
   W is a verb a place or an object. X is a place, an object or zero.
   Y is a flag or zero. Optional argument Z is a text. Used to construct
   dynamic vocabulary listing. Outputs the main vocabulary word for W, or
   a replacement text Z of present, iff the conditions specified by X and Y
   are satisfied. If Y is zero, output is unconditional. Otherwise the flag
   Y is tested for entity X, or if that is specified as 0, on the entity W
   itself. NB Bad syntax. Maybe reimplement as W [Z] [X] [Y] ?
APPEND X* [Y*]
   X is a text, an object or a place. Y is a value. Removes any
   line feeds from the end of text generated so far, then outputs text X,
   with the explicit qualifier Y.
VALUE X* [Y*]
   Deprecated equivalent of SAY, which interpreted the placeholder # as
   meaning the value of an entity,rather than as its associated primary word.
   Use the $ placeholder and SAY instead.
   
Various stuff.

FLAG X Y
   X is a flaggable entity (a variable, a place or an object). Y is a flag.
   Sets flag Y for entity X.
UNFLAG
   X is a flaggabe entity. Y is a flag.
   Clears flag Y for entity X.
INPUT [X*]
   X is a text (optional replacement prompt). Outputs text X (if specified)
   and obtains player's input.
DEFAULT {X* [Y]|Y}
   X is a place. Y is an object flag. If player's command
   specified a verb but not an object, use -- if uniquely identified -- 
   the obejct specified by X and/or Y. If Y is present, the object must have 
   the the Y flag set. If X is present, the object must be at the location X.
   If both X and Y are present, both conditions must apply. If no object
   or multiple objects satisfy the criteria, do nothing. If a unique match
   found, fake the relevant pert of the command as if the player nominated
   that object. If no match is found, ARG2 is set to 0. If multiple
   matches fuond ARG2 is set to AMBIGWORD.
DOALL {X* [Y]|Y}
   X is a place, Y is an object flag.
   Apply the verb of the player's command in repeated execution of the
   whole REPEAT loop, iterating ARG2 (and faking the input word) through
   objects according to the specified criteria. If Y is specified, the object
   must have the flag Y set. If X is specified, the object must be in
   location X.
FLUSH
   Flush the remainder of the player command (in case it was a compound one)
   and abort the DOALL loop if one is in progress.
SVAR X Y
   X is a constant (4 or 5 for backward compatibility). Y is a variable.
   If X is 4, returns local time hour in Y. If X is 5, returns local
   time minute in Y. STYLE 1 legacy.

Arithmetic and pointers.

SET X Y
   X is a value bearing entity. Y is a value. Sets the value of X to Y.
ADD X Y
   X is a value bearing entity. Y is a value. Increase the value of
   X by Y.
SUBTRACT X Y
   X is a value bearing entity. Y is a value. Reduces the value of
   X by Y.
MULTIPLY X Y
   X is a value bearing entity. Y is a value. Sets the value of X
   to the product of the original value of X and Y.
DIVIDE X Y
   X is a value bearing entity. Y is a value. Sets the value of X
   to the result of integer division of X by Y.
NEGATE X
   X is a value bearing entity. Negates the value of X.
RANDOM X Y
   Sets the value of X to a random integer in the range 0 to Y-1.
INTERSECT X Y
   X is a value bearing entity. Y is a value. 
   Sets the value of X to be a bitwise and of X and Y.
CHOOSE X Y Z
   X is a value bearing entity. Y and Z are values.
   Sets the value of X to a random number in the range Y to Z-1 (or Z?)
RANDOMISE X Y
   X is a place, object or text. Y is a positive value. If N is the number of
   all possible switch configurations in the text associated with X,
   sets the value of X to a random number between Y and N-1. NB: Y must be 
   less than N. 
LDA X Y
   X is a variable. Y is a named entity. Sets X to be a pointer to Y.
EVAL X Y
   X is a variable. Y is a variable pointing to a value bearing entity. Sets
   X to the value of the entity pointed at by Y.
DEPOSIT X Y
   X is a variable pointing to a value bearing entity. Y is a value.
   Sets the value of the entity pointed at by X to Y.
TIE X Y [...]
   X is a value holder other than a local variable. Y (etc...) is a text.
   Makes the value of Y (etc...) to be a pointer to X.

Object location.

GET X*
   X is an object. Moves the object into player's
   inventory. Equivalent to APPORT X INHAND.
DROP X*
   X is an object. Moves the object from player's
   inventory to his current location. Equivalent to APPORT X HERE.
APPORT X* Y*
   X is an object. Y is a place or place reference.
   Moves object X to place Y.
LOCATE X, Y*
   X is a variable. Y is an object. Sets X to be a 
   pointer to the current location of Y.
   
Debugging.

CHECKPOINT
   Output text "Checkpoint: , line \n"
DUMP
   Dump the game state in a human readable format (requires the presence
   of xreference listings generated by acdc). Experimental.

Saved games.

SAVE FILE 
   Perform EXEC 1
SAVE MEMORY
   Perform memory save.
SAVE COMMAND
   Perform EXEC 23
SAVE VALUE, X
   X is a variable. Perform EXEC 6, X
RESTORE FILE
   Perform EXEC 2
RESTORE MEMORY
   Perform memory restore.
RESTORE COMMAND
   Perform EXEC 24
RESTORE VALUE, X
   X is a variable. Perform EXEC 7, X
DELETE 
   Perform EXEC 3. Not fully implemented yet
SAVEDLIST COUNT
   Not fully implemented yet
SAVEDLIST SHOW
   Not fully implemented yet

Undo stuff
Uses automatic variable UNDO.STATUS with automatic variable flags 
UNDO.NONE, UNDO.OFF, UNDO.INFO, UNDO.TRIM, UNDO.BAD, UNDO.INV

UNDO ARG2
   Undo the number of moves indicated by the text of ARG2. The number
   is deemed to be 32767 if the text is ALL, and 1 if the text is not a
   number.
REDO ARG2
   Undo the number of moves indicated by the text of ARG2. The number
   is deemed to be 32767 if the text is ALL, and 1 if the text is not a
   number.