qasm/doc/DIALECT.md

Merlin 16+ dialect (with 8/16 compatibility)

Primary spec: Merlin 16+ (Glen Bredon, Roger Wagner Publishing, 1988–89). Merlin 8/16 is the subset we remain compatible with. This file is the working language contract for this assembler, distilled from:

• doc/manuals/Merlin_816_Macro_Assembler_Manual.pdf
• doc/manuals/Merlin_16_Supplementary_Manual.pdf

Host-only extensions, if any, will be called out. None yet.

Line format

LABEL    OPCODE    OPERAND    ; comment

• A label, if present, starts in column 0 (no leading whitespace).
• Fields are separated by spaces or tabs.
• * or ; as the first non-blank character makes a comment line.
• Opcode mnemonics are case-insensitive. Labels, macros, and equates follow CAS SE / CAS IN (default: insensitive, matching typical 16+ FARMS).

Native Merlin source files (disk / IIgs editor)

The on-disk format from Merlin 8/16/16+ is not plain ASCII:

• Letters, digits, and punctuation normally have bit 7 set.
• Column tabs (label / opcode / operand / comment) are a single $A0 (space with the high bit set). $09 and $89 (TAB) are accepted too.
• Literal spaces in quoted operands and comments are $20 (high bit clear). That is why $A0 is a tab and $20 is not: the assembler can split columns without tracking quotes.
• Lines end with $8D (high-bit CR), sometimes $0D / $0A.
• Extra $A0 after the third separator is treated as an ordinary space (David Empson / CiderPress notes).

Host-side .s files (spaces, TABs, LF/CRLF, high bit clear) are also accepted. High-bit letters with $20 separators (partially converted files) still assemble: bit 7 is stripped on each field.

Processors

XC	CPU
off	6502 only
once	65C02
twice, or 16/16+ default	65802 / 65816

16+: XC OFF restores 6502-only. Startup:

• --dialect 16+ / 16: XC on (65816), MX %11 (emulation, 8-bit A/XY)
• --dialect 8: XC off, MX %11

Sources should still begin with explicit MX / XC so they assemble the same way regardless of FARMS / CLI defaults.

SEP / REP update assembler MX from the immediate operand when it is constant. MX %00–%11 (or 0–3) sets it without emitting code.

M=0 / X=0 means 16-bit; 1 means 8-bit.

Addressing

Merlin does not write ASL A. Accumulator/implied is a bare mnemonic.

Immediate data starts with #. Addresses do not.

Syntax	Mode
LDA #$00	immediate (8 or 16 from M)
LDA $10	direct page if value < $100 and not forced
LDA $C000	absolute
LDAL $E12000 / LDA >$E12000	long
LDA: $10 / LDA\ $10	force absolute
LDA <$1234	force direct page (low byte)
LDA ($10),Y	DP indirect indexed
LDA [$10],Y	DP indirect long indexed
LDA $10,S	stack relative
LDA ($10,S),Y	stack relative indirect indexed
BEQ LABEL	relative
MVN src,dst	block move (object: dest bank, src bank)

Byte selectors after #: < low, > high, ^ (or #A) bank.

Alternate mnemonics: BLT=BCC, BGE=BCS, TAS=TCS, TSA=TSC, TAD=TCD, TDA=TDC, SWA=XBA. Long ALU forms LDAL, STAL, …

Undefined labels are 16-bit (absolute) until equated. Zero-page labels must be defined before use (Merlin rule; otherwise DP/abs size would be unstable).

Expressions

Numbers: decimal, $hex, %binary (_ allowed in binary). ASCII 'A' / "A". * is the program counter at term position, multiply at operator position.

Default evaluation is left-to-right, no precedence (1+2*3 = 9). Enclose in { } for algebraic precedence (16+). --algebraic does that for all expressions (FARMS bit; can break old LAB1-LAB2/2 sources).

Operators, lowest to highest inside braces:

<  =  >  #          comparison (true=1, false=0); # is not-equal
+  -
*  /
&  .  !             AND, OR, XOR
-                   unary minus

( ) are addressing, not grouping. Use { }.

Labels

• Global: start with a letter or extra-alphabetic (_, @, … not a digit).
• ]NAME as a label is a backward-only local (nearest previous).
• :NAME is a local whose scope is the enclosing global labels.
• ]NAME = expr is a variable (redefinable). Forward refs to variables are illegal.
• Locals cannot be ENT/EXT and cannot be the first label in a file.

Compatibility: keep names ≤ 26 characters for real Merlin 16+.

Data / directives (16+ set, 8/16 subset)

Assembler: ORG, OBJ, EQU/=, PUT, USE, VAR, SAV, DSK, END, DUM, DEND, TYP, REL, LNK, ENT, EXT, MX, XC, CAS, ERR, CHK, DATE, STRL (16+), LST, EXP, TR, PAU, PAG, AST, SKP.

Data: HEX, DFB/DB, DA/DW, DDB, ADR, ADRL, DS, ASC, DCI, INV, FLS, REV, STR, STRL.

16+ ASC accepts hex bytes mixed into the string, empty strings, and ASC #expr / #' / #" / #>.

Conditionals: DO / ELSE / FIN, IF / ELSE / FIN. IF MX/2 tests M; IF "=]1" / IF #,]1 tests the first character of a variable (macros). Nest ≤ 8 on real 16+.

Macros: MAC … EOM / <<<. Call by name, or PMC / >>>. Parameters ]1–]9 separated by ;. Nest ≤ 15 on real 16+.

Loops: LUP n … --^. @ in a label becomes Z,Y,X,… per iteration (max 26).

Output

Absolute object (BIN) is produced from ORG + DSK/SAV/-o. REL / Linker.GS / OMF v2.1 is planned; not in the MVP.

TYP accepts hex ($B3) or ASCII names (SYS, S16, CDA, EXE, BIN).

What 16+ added (vs 8/16) that we treat as first-class

• XC OFF
• CAS SE / CAS IN
• {algebraic} expressions and < = > # comparisons
• STRL
• mixed hex in ASC/STR/… and ASC #
• TYP ASCII filetypes; TYP in REL files
• SAV compatible with REL
• LST FILE,name
• pathname ../ (. + / backup) in assembler/linker files
• DATE operands 1–8
• FLO (SANE extended) — not yet implemented
• DUP equate-same-value option — not yet a CLI flag