asm.doc

=== Command-line switches ===

It requires two arguments, being the input file name and the output file
name; you can write - in place of the output file name for stdout, but
the input file is required to be seekable.

-d
  Emit debugging information.

-e
  Emit editor information in addition to the usual data.

-w
  Read the world file with the same name as the input file, but with the
  suffix changed from ".asm" to ".sz0" or ".ASM" to ".SZ0".

-v
  Verbose output (to stderr).


=== Syntax ===

Each line can be blank, or a comment, or it can be an optional label
followed by one or more spaces/tabs and then the instruction, which
can also optionally be followed by a comment.

A label may be a numbered label, which is a digit 0 to 9 followed by H
in which case it is possible to have more than one with the same number
and codes like 1F and 2B etc can reference them.

A label name consists only of letters, digits, underscore, and question
mark, and must start with a letter or underscore. It must contain more
than one character; single character names are reserved.

A normal instruction consists of the name, a space, the first operand,
a comma, and the second operand. The first operand must be A to H or S
to Z (although some only allow A to H). The second operand can be one
of the following:

* One of the registers A to H or W to Z.

* A numeric expression.

* A memory operand, consisting of * and a 8-bit number being the address
to read from.

* An extension operand; see below.

A pseudo instruction is the name, space, and then the arguments (which
depend on the specific pseudo).

Extension operands are written as three parts with commas in between; the
first is the kind which is % and zero to three more letters, and the
second is the source (see below), and the third is the value (normally
must be in range 0 to 255, but sometimes -256 to +255 is allowed).

The source of an extension operand can be one of the following:

* One of the registers A to H or W to Z.

* A numeric expression.

* A numeric expression with an asterisk in front, representing accessing
the unsigned 16-bit number at that address.

* Empty, which is the same as zero.

The kinds of extension operands are:

* % = Add together the source and value. The value can be -256 to +255.

* %B = Extract bits from the source. The value is a 8-bit number, where
the high nybble is the lowest bit to extract and the low nybble is the
number of bits to extract; the value is unsigned shifted right.

* %BRD = The current board ID. Source and value are not used.

* %E = The event, where the source is the element number (in the low
8-bits) and the value is the event number (in range 0 to 15).

* %H = Board height plus source plus value (in range -8 to +7).

* %I = Add together the source and value, and treat it as an address to
read a 16-bit number from. The value can be -256 to +255.

* %L = Left shift the source by the value (in range 0 to 31).

* %M = Subtract the source from the value. The value can be -256 to +255.

* %OF = Use the source if the condition flag is false or the value if the
condition flag is true. The value can be -3 to +4 or A to H.

* %OT = Use the source if the condition flag is true or the value if the
condition flag is false. The value can be -3 to +4 or A to H.

* %R = A random number from 0 up to source+value-1. The value can be in
range 0 to 255.

* %SM = A status variable indicated by the value (0 to 15), minus the
source value.

* %SP = A status variable indicated by the value (0 to 15), plus the
source value.

* %SR = Signed right shift the source by the value (in range 0 to 31).

* %SX = Scroll X position plus source plus value (in range -8 to +7).

* %SY = Scroll Y position plus source plus value (in range -8 to +7).

* %UR = Unsigned right shift the source by the value (in range 0 to 31).

* %W = Board width plus source plus value (in range -8 to +7).

* %X = The source is the packed coordinates (or zero to use the X register
instead). The value has a special format: It must be + or - and then a
register name (A to H or W to Z) and then a comma and then the shift
amount (from 0 to 7). The result is the new coordinate value, which will
ignore the limits of the board coordinates.

* %XP = Player X plus value (in range -8 to +7) minus source.

* %Y = Similar than %X but for Y coordinates instead of X coordinates.

* %YP = Player Y plus value (in range -8 to +7) minus source.

A comment starts by a semicolon, and ends at the end of the line. (A
semicolon inside of a string or character literal is not a comment.)


=== Numeric expressions ===

It can be one of:

* A decimal integer.

* A hexadecimal integer with $ at first.

* A quoted string; enters it into the global string table (merging
duplicates) and represents its index into the table.

* A character literal in the format like C programming language.

* A label name, for that label's address (or its value, if the IS or ISNT
pseudo is used).

* The sign @ to mean the current address of this instruction. (Do not
use this in the operands of editor-specific pseudos.)

* A digit 0 to 9 followed by B or F to find the closest numbered label
in the specified direction (B for backward, F for forward) with the
specified number.

* One of the above followed by + or - and another of the above. You can
optionally start the entire expression with - or + without preceding by
another of the above items, in which case zero is assumed.

In characters and strings, the valid escaping is:
  \xXX where XX are two hex digits, for that character code
  \\ or \" or \' to represent a literal \ or " or '
  \r for a carriage return
  \n for a line feed


=== Pseudos ===

In the below, [] denotes optional items and ... means you can have more
items if desired.

ASS number[,number...]
  If there is only one operand, it is an error if it is zero. If there is
  more than one operand, it is an error if any operand is less than the
  previous operand.

AT number
  Write further code at the specified address. (If not specified, then the
  default starting address is 256.)

COM string
  Make a user-defined script command. (It will override a built-in script
  command of the same name if there is one.)

DATA number[,number...]
  One or more numeric expressions, entered as data.

EV event,number[,number]
  Define an event. The first argument will be the letter or number of the
  event, and then the element number, and then optionally the value to
  use for the event (if not specified, use the current address).

FILL number[,number]
  The first number is how many memory cells to fill, and the second number
  is the value to fill it with. If the second number is a expression which
  contains @ then it will be recalculated for each cell, and if the second
  number is omitted then zero is used.

IS number
  Makes the label value the specified number, instead of the address.

ISNT number
  Same as IS but uses the bitwise complement.

PT string
  Null-terminated packed text; packs two characters in one byte.

STR string[,string...]
  This works like IS but only for strings, and it forces the string to be
  given a new number, even if there is already a duplicate string (which
  will keep its existing number). Multiple strings given on the same line
  or on consecutive STR lines will be given consecutive numbers. If the
  string defined by STR is mentioned by its text later in the program
  without using STR, then it will use the number defined by STR, but if
  the string text is mentioned before STR then that string has a separate
  (lesser) number than the one defined by STR.

TA addr[,value]
  Write the current address (or the specified value, if it is present) at
  the specified address.


=== Editor-specific pseudos ===

These pseudos are only meaningful if the -e switch is used. Any of these
pseudos that are preceded by a label will make a label which is only to be
used in the operands of other editor-specific pseudos.

ED number[,number...]
  Works like DATA but for the editor memory. See editops.doc for details
  of what format of operands is expected.

ED0 number[,number]
  The first number is a element number. The following editor-specific
  pseudos will control the parameter editing for that element. If a second
  operand is specified, then instead it will use that value as the default
  value of the parameter and no parameter editing will be needed; you can
  add $100 to the default value to ask the user for a character code.

ED1 number[,number]
  Used for board editor function keys and some other purposes. Usually the
  menu items (as ED commands) would follow, but a second number can be
  specified in some cases.

ED2 number,string[,number...]
  Defines a form field in a parameter editor. See editops.doc for details.

ED3 key,value[,key,value,...]
  A key/value list; see editops.doc for details.

ED4 register,number
  Sets the value of a A to H register in a parameter editor instruction
  list. See editops.doc for details.

ED5 register,number,number
  See editops.doc for details about this command.