OTHER INFORMATION

COMPLEMENTS

MULTIPLE INSTRUCTIONS ON A SINGLE LINE

ESA accepts several instructions and/or constructions on a single line:

         lea.l buffer,a0 § bool d1=d2,d0.b § add.b d7,d7 § ...

The instructions in the example are separated by § (the leading SPACE is compulsory, the following not), the default separator (which can be substituted with the SEPARATOR option).
Labels, of course, cannot be specified after a separator.

ERROR REPORTS

Error reports are shown in this form:

"ERROR" NUMBER ":" MESSAGE

or, when needed:

"ERROR" NUMBER ":" MESSAGE "at line" LINE "of" FILE ":"
">" CODE

where:

NUMBER is the number of the error found (the AmigaDOS return code will be this number +19).
MESSAGE is the concise explanation of what went wrong.
LINE is the number of the line which the error occurred at.
FILE is the file which contains the error (only the file part of the path is printed).
CODE is the source line which contains the error.

In some cases, the same report can be given for different errors.

MISCELLANEOUS NOTES

These notes reveal, in no particular order, some interesting aspects that are not so obvious.

Some constructions produce jumps to labels generated automatically: if they are local (i.e. start with '.') and if between these jumps global labels are defined, probably the assembler will fail with an "undefined symbol" error.
The default size is .l (except where differently specified).
SPACEs/TABs can be placed anywhere except between the arguments and their own sizes.
ESA makes mainly syntactical checks; semantics is left to the assembler.
ESA is case sensitive.
Comments start with '*' or ';' if they are at the beginning of a line or are not preceded by any instruction/directive; otherwise ';' is the only character which marks a comment (at least a SPACE/TAB must precede it).
Comments end at the end of the line.
All SPACEs and TABs in the arguments will be removed (except if enclosed between single/double quotes).
When ESA is halted by an error during pass 2, the output file holds all the code generated until that moment.
The generated labels have the format CXXXXXXX, where XXXXXXX is a number in hexadecimal notation and C is generally '.' (or the character chosen with the PREFIX option); otherwise, it can be either 'p' for global procedures or 'f' for global functions.
Admittedly, naming could have been better and more uniform, and the grammar more elegant.
For speed sake:
- at compile time, constructions nesting is permitted up to 64 levels, but without any check - instead of inserting checks, it would be preferable to enlarge the internal stack used for this purpose (even doubled it would be still very small);
- sometimes generated instructions are not aligned perfectly in their column;
- a negated exclusive or ("~ ... ^") generates capitalized letters ("EOR");
- in very rare cases, the printout of the string which generated an error could be somehow corrupted (truncated, partially modified in the middle, etc.): this is because during pass 1 some integer values are directly written in the copy of the source in memory;
- lines longer than 2048 characters could cause malfunctioning (even GURUs) when the work buffer is almost full;
- "-(ax)+" is recognized as a correct var.

NOTE ABOUT SPEED

Basic, speedy, flexible... but hard to work with due to the complexity of usage. Often, to make things easier for us humans, simplicity, speed and flexibility are sacrificed. This applies to almost everything in computing (and in the "real" world as well). And this is exactly what naturally happens with ESA.
ESA code is normally quite efficient - sometimes even perfectly efficient -, but obviously it cannot match the performance of hand-written assembly in all cases. So, WHEN WRITING TIME-CRITIC ROUTINES, DO NOT RELY ON ESA CODE SPEED!
That said, do not be afraid: not only generated code is normally good, but inefficiencies can be kept under control by understanding well the behaviour of the constructions.