

                                 ACME

         ...the ACME Crossassembler for Multiple Environments

                       --- Quick  reference ---


This file should give you a basic overview. More specialized stuff
like forcing a specific addressing mode is discussed in extra files
("AddrModes.txt" in this case).




***   Example of what an ACME source code file looks like:

;--- Example code fragment, start ---

		*= $c000;	The program counter definition
		!to "out.o";	The output file definition
		!cpu 65816;	The processor definition
; If you don't define the processor, ACME will default to a 6502.
; You can use "!cpu" to change the processor at any place.

basout = $ffd2;			A label definition
		ldx #0
		beq in

.loop		jsr basout;	a local label
in		lda string,x;	a global label
		bne .loop
		rts

string		!pet "Hi !", 0;	a global label and a PetSCII string

;--- Example code fragment, end ---


Save this to a file called "source.a" and start acme by typing

    acme source.a

ACME will parse the file and report any errors. An output file will
only be generated if there were no errors and if the source file
contains the relevant directive.


After assembly, the example program can be run on a C64 using

    LOAD "out.o",8,1
    SYS 49152

Note that ACME does not include any routines for transferring data to
a C64. Such tools exist on almost every platform, and I didn't want
ACME to become bloatware.


Back to the example program:

As you can see, local labels are prefixed with a dot (".") and Pseudo
Opcodes are prefixed with an exclamation mark ("!"). Okay, so it's
non-standard, but: Backwards compatibility is the root of all evil. :)




***   The Pseudo Opcodes

A list with information on how to use all the Pseudo Opcodes can be
found in the file "AllPOs.txt". Here's just a short overview:

!08 / !16 / !24 / !32 / !by / !byte / !fi / !fill / !wo / !word
...for directly placing values into the output file.

!subzone / !sz / !zn / !zone
...for defining the scope of local labels.

!cbm / !convtab / !ct / !pet / !raw / !scr / !scrxor / !text / !tx
...for converting and outputting strings.

!do / !endoffile / !eof / !for / !if / !ifdef / !set
...for flow control; looping assembly and conditional assembly.

!bin / !binary / !sl / !source / !src / !to
...for handling input and output files.

!pseudopc / !realpc
...for offset assembly.

!initmem *=
...for segment assembly.

!macro +
...for defining and calling macros.

!align !cpu
...for miscellaneous stuff.

!al !as !rl !rs
...for the 65816 processor.




***   The maths parser

ACME has a relatively powerful maths parser (...for a free 6502
assembler). This parser is used whenever ACME expects to read an
integer value. Supported operations include addition, subtraction,
multiplication, divisions, comparisons, shifts, negation, boolean
operations and some assembler-specific stuff like extracting the
"low byte", the "high byte" or the "bank byte" from a value.
All calculations are done using signed 32-bit integer arithmetic and
all label values are internally handled using 32 bits.


This is a list of the operators currently known by ACME:

Priority    Example     Meaning                 Alias
---------------------------------------------------------------------
      13        ! v     Complement of           NOT
      12     v  ^ w     To the power of
      11        - v     Negate
      10     v  * w     Multiply
      10     v  / w     Integer-Divide          DIV
      10     v  % w     Remainder of DIV        MOD
       9     v  + w     Add
       9     v  - w     Subtract
       8     v << w     Shift left              LSL, ASL
       8     v >> w     Logical shift right     LSR
       7        < v     Lowbyte of
       7        > v     Highbyte of
       7        ^ v     Bankbyte of
       6     v <= w     Lower or equal
       6     v <  w     Lower than
       6     v >= w     Higher or equal
       6     v >  w     Higher than
       5     v != w     Not equal               <>,  ><
       4     v  = w     Equal
       3     v  & w     Bit-wise AND            AND
       2                Bit-wise exclusive OR   EOR, XOR
       1     v  | w     Bit-wise OR             OR

Operations with higher priority are done first. Of course you can
change this using parentheses. If you prefer the aliases over the
shorthand characters, note that they must be written in capital
letters.
Note that though there are operators to extract the "low byte", the
"high byte" and the "bank byte", there is no operator to extract the
fourth byte. If you want to access that, shift it down using ">>" or
"LSR".


This is a list of the value formats currently known by ACME:

    Example     Meaning              Prefix
---------------------------------------------------------------------
    GetByte     Global label         None
    .Loop       Local label          "."
    9260        Decimal value        None
    $1a8e       Hexadecimal value    "$"
    0x8b4f      Hexadecimal value    "0x"
    &1054       Octal value          "&"
    %10010      Binary value         "%"
In binary values you can substitute the characters "0" and "1" by "."
and "#" respectively. This way the values are much more readable.
    "r"         Character value      Double quotes
    'r'         Character value      Single quotes
The value depends on the current conversion table, chosen using the
"!ct" pseudo opcode.
    *           The current PC       "*"
During offset assembly, "*" gives the value of the "Pseudo PC". Just
to make sure: The value of the program counter is always the value
that was valid at the start of the current statement, so

    !word *, *, *, *

will give the same value four times. I think most assemblers do it
this way.




***   Quite exact syntax

Every ACME source code file consists of a non-negative number of
"lines". The lines have to be separated from each other using CR, LF
or CRLF characters.

Every line consists of a non-negative number of "statements" and an
optional comment. Statements have to be separated from each other
using colon (":") characters, the comment has to be prefixed with a
semicolon (";") character.

Every statement consists of an optional "label" and an optional
"command". These are separated from each other using any number of
SPACE or TAB characters.

Every label consists of these characters: "a" to "z", "A" to "Z", "0"
to "9", the underscore character "_" and all characters with values
beyond 127. The first character must not be a digit though. But it can
be a dot ("."), making the label a local one.

Every command is one of the following:
    An assembler opcode
    A pseudo opcode, beginning with a "!" character
    A label definition
    A pc definition, beginning with a "*" character
    A macro call, beginning with a "+" character
...and the syntax of those things varies. :)

Assembler mnemonics and pseudo opcodes are case insensitive, so
whether you write "LDA" or "lda" or "LdA" does not make a difference.

Arithmetic operators like MOD, XOR, LSL must be written in UPPER CASE;
this rule simply serves to make them stand out.

Label names are case sensitive, so "label" and "Label" are two
different things.

