Acode minor directives supported by acdc 12.36

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

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.

Player command fiddling

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.

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.)

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

Save and restire directives

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, otherwise 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, otherwise 1, if the text is not a number.