diff --git a/commands.md b/commands.md new file mode 100644 index 0000000..b7e2dd9 --- /dev/null +++ b/commands.md @@ -0,0 +1,631 @@ +# Compiler Commands Reference + +## ADD + +Adds two values and stores result in destination. + +**Syntax:** +``` + = + +``` + +**Examples:** +``` +result = 10 + 5 +total = count + offset +sum = var1 + 100 +``` + +--- + +## AND + +Bitwise AND operation between two values. + +**Syntax:** +``` + = & +``` + +**Examples:** +``` +mask = value & $FF +result = byte1 & byte2 +flags = status & $80 +``` + +--- + +## BREAK + +Exits current loop immediately. + +**Syntax:** +``` +BREAK +``` + +**Examples:** +``` +FOR i = 0 TO 100 + IF i = 50 + BREAK + ENDIF +NEXT + +WHILE counter < 1000 + counter++ + IF error + BREAK + ENDIF +WEND +``` + +--- + +## BYTE + +Declares an 8-bit variable or constant. + +**Syntax:** +``` +BYTE +BYTE = +BYTE @
+BYTE CONST = +``` + +**Examples:** +``` +BYTE counter +BYTE speed = 5 +BYTE screen @ $D020 +BYTE CONST MAX_SPEED = 10 +``` + +--- + +## CALL + +Calls a function with optional arguments. + +**Syntax:** +``` +([,[,...]]) +``` + +**Examples:** +``` +initialize +setColor(1,14) +drawSprite(xpos,ypos,@spriteData) +process("hello",42,myvar) +``` + +--- + +## DEC + +Decrements a variable or memory location by 1. + +**Syntax:** +``` +-- +DEC +DECREMENT +``` + +**Examples:** +``` +counter-- +lives-- +index-- +DEC $D020 +DECREMENT screenColor +``` + +--- + +## ELSE + +Alternative branch in IF statement. + +**Syntax:** +``` +See IF +``` + +--- + +## ENDIF + +Terminates IF block. + +**Syntax:** +``` +See IF +``` + +--- + +## FEND + +Ends a function definition. + +**Syntax:** +``` +See FUNC +``` + +--- + +## FOR + +Loop with automatic counter increment. + +**Syntax:** +``` +FOR = TO [STEP ] +``` + +**Examples:** +``` +FOR i = 0 TO 10 + screen = i +NEXT + +FOR x = 0 TO 255 STEP 2 + result = result + x +NEXT + +FOR counter = start TO finish + process(counter) +NEXT +``` + +--- + +## FUNC + +Defines a function with optional parameters. + +Parameter passing modes: `in:` (default, read-only), `out:` (write-only), `io:` (read-write) + +**Syntax:** +``` +FUNC +FUNC ([,,...]) +``` + +**Examples:** +``` +FUNC initialize + BYTE temp = 0 + screen = temp +FEND + +FUNC add(in:a,in:b,out:result) + result = a + b +FEND + +FUNC process(value,{BYTE temp}) + temp = value + 1 +FEND + +FUNC swap(io:x,io:y) + BYTE temp = x + x = y + y = temp +FEND +``` + +--- + +## GOSUB + +Calls subroutine with optional register passing. + +**Syntax:** +``` +GOSUB +GOSUB PASSING AS ACC|XREG|YREG [ AS XREG|YREG [ AS YREG]] +``` + +**Examples:** +``` +GOSUB myRoutine +GOSUB clearScreen +GOSUB processData PASSING value AS ACC +GOSUB multiply PASSING a AS ACC b AS XREG result AS ACC +``` + +--- + +## GOTO + +Unconditional jump to label or address. + +**Syntax:** +``` +GOTO +``` + +**Examples:** +``` +GOTO mainLoop +GOTO error +GOTO endProgram +GOTO $9000 +GOTO (startAddress+$100) +``` + +--- + +## IF + +Conditional execution based on comparison. + +When single parameter: 0 = false, non-zero = true + +**Syntax:** +``` +IF [ ] +``` + +Operators: `=` `==` `<>` `!=` `>` `<` `>=` `<=` + +**Examples:** +``` +IF count = 10 + result = 1 +ENDIF + +IF value > threshold + process(value) +ELSE + skip(value) +ENDIF + +IF status & $80 + errorFlag = 1 +ENDIF + +IF x < 100 + x++ +ELSE + x = 0 +ENDIF +``` + +--- + +## INC + +Increments a variable or memory location by 1. + +**Syntax:** +``` +++ +INC +INCREMENT +``` + +**Examples:** +``` +counter++ +index++ +frameCount++ +INC $D020 +INCREMENT screenColor +``` + +--- + +## LABEL + +Creates a named assembly label. + +**Syntax:** +``` +LABEL +``` + +**Examples:** +``` +LABEL mainLoop +LABEL skipSection +LABEL errorHandler +``` + +--- + +## LET + +Assigns value to variable. + +Note: expressions not allowed (except constant expressions without spaces) + +**Syntax:** +``` + = +``` + +**Examples:** +``` +counter = 0 +speed = maxSpeed +result = temp +value = 100+50 +``` + +--- + +## NEXT + +Loop terminator for FOR. + +**Syntax:** +``` +See FOR +``` + +--- + +## OR + +Bitwise OR operation between two values. + +**Syntax:** +``` + = | +``` + +**Examples:** +``` +flags = flags | $01 +result = byte1 | byte2 +status = status | errorBit +``` + +--- + +## ORIGIN + +Sets assembly origin address. + +**Syntax:** +``` +ORIGIN
+``` + +**Examples:** +``` +ORIGIN $0801 +ORIGIN $C000 +ORIGIN startAddress +``` + +--- + +## PEEK + +Reads byte from memory location. + +**Syntax:** +``` + = PEEK
[] +``` + +**Examples:** +``` +value = PEEK $D020 +char = PEEK screenPtr[index] +data = PEEK buffer[5] +byte = PEEK pointer +``` + +--- + +## PEEKW + +Reads word (16-bit) from memory location. + +**Syntax:** +``` + = PEEKW
[] +``` + +**Examples:** +``` +addr = PEEKW $FFFE +value = PEEKW dataPtr[0] +word = PEEKW buffer[10] +address = PEEKW pointer +``` + +--- + +## POINT + +Sets pointer variable to address of target. + +**Syntax:** +``` +POINTER TO +``` + +**Examples:** +``` +POINTER screenPtr TO $0400 +POINTER dataPtr TO buffer +POINTER funcPtr TO myFunction +``` + +--- + +## POKE + +Writes byte to memory location. + +**Syntax:** +``` +POKE
[] WITH +``` + +**Examples:** +``` +POKE $D020 WITH 0 +POKE screenPtr[index] WITH char +POKE buffer[5] WITH data +POKE pointer WITH value +``` + +--- + +## POKEW + +Writes word (16-bit) to memory location. + +**Syntax:** +``` +POKEW
[] WITH +``` + +**Examples:** +``` +POKEW $0314 WITH handler +POKEW dataPtr[0] WITH value +POKEW buffer[10] WITH address +``` + +--- + +## SUBEND + +Returns from subroutine. + +**Syntax:** +``` +SUBEND +``` +or +``` +EXIT +``` + +**Examples:** +``` +LABEL subroutine + counter = counter + 1 + SUBEND + +LABEL checkValue + IF value = 0 + EXIT + ENDIF + process(value) + SUBEND +``` + +--- + +## SUBTR + +Subtracts second value from first. + +**Syntax:** +``` + = - +``` + +**Examples:** +``` +result = 100 - 5 +difference = end - start +remaining = total - used +``` + +--- + +## WEND + +Terminates WHILE loop. + +**Syntax:** +``` +See WHILE +``` + +--- + +## WHILE + +Loop that continues while condition is true. + +When single parameter: 0 = false, non-zero = true + +**Syntax:** +``` +WHILE [ ] +``` + +Operators: `=` `==` `<>` `!=` `>` `<` `>=` `<=` + +**Examples:** +``` +WHILE counter < 100 + counter++ + result = result + counter +WEND + +WHILE running + processFrame + checkInput +WEND + +WHILE x != y + x++ +WEND +``` + +--- + +## WORD + +Declares a 16-bit variable or constant. + +**Syntax:** +``` +WORD +WORD = +WORD = "" +WORD @
+WORD CONST = +``` + +**Examples:** +``` +WORD counter +WORD address = $C000 +WORD message = "Hello" +WORD irqVector @ $0314 +WORD CONST SCREEN = $0400 +``` + +--- + +## XOR + +Bitwise XOR operation between two values. + +**Syntax:** +``` + = ^ +``` + +**Examples:** +``` +result = value ^ $FF +output = byte1 ^ byte2 +toggleBits = flags ^ mask +``` \ No newline at end of file diff --git a/syntax.md b/syntax.md new file mode 100644 index 0000000..36127bb --- /dev/null +++ b/syntax.md @@ -0,0 +1,481 @@ +# Syntax Reference + +## Comments + +C65GM uses C-style line comments. + +**Syntax:** +``` +// +``` + +**Examples:** +``` +BYTE counter = 0 // Initialize counter +// This is a full line comment +FOR i = 0 TO 10 // Loop through values + counter++ // Increment +NEXT +``` + +**Notes:** +- Comments start with `//` and continue to end of line +- Comments in ASM blocks use assembly syntax: `;` +- Comments in SCRIPT blocks use Starlark syntax: `#` + +--- + +## Preprocessor Directives + +### #DEFINE + +Defines a text substitution macro. + +**Syntax:** +``` +#DEFINE [= ] +``` + +**Examples:** +``` +#DEFINE MAX_SPEED = 10 +#DEFINE SCREEN = $0400 +#DEFINE OFFSET = 255 +#DEFINE BASE+DELTA = $D000+32 +``` + +**Notes:** +- Optional `=` separator +- Value can contain previously defined macros +- Macros are expanded in source lines +- Case sensitive + +--- + +### #UNDEF + +Undefines a previously defined macro. + +**Syntax:** +``` +#UNDEF +``` + +**Examples:** +``` +#DEFINE DEBUG = 1 +#UNDEF DEBUG +``` + +--- + +### #IFDEF + +Conditional compilation if macro is defined. + +**Syntax:** +``` +#IFDEF +``` + +**Examples:** +``` +#IFDEF DEBUG + BYTE debugFlag = 1 +#IFEND + +#IFDEF PAL + BYTE scanlines = 312 +#IFEND +``` + +--- + +### #IFNDEF + +Conditional compilation if macro is not defined. + +**Syntax:** +``` +#IFNDEF +``` + +**Examples:** +``` +#IFNDEF __INCLUDED_SPRITE_LIB + #DEFINE __INCLUDED_SPRITE_LIB = 1 + FUNC drawSprite + ; sprite code + FEND +#IFEND +``` + +**Notes:** +- Common pattern for include guards +- Prevents multiple inclusion + +--- + +### #IFEND + +Ends conditional compilation block. + +**Syntax:** +``` +#IFEND +``` + +**Examples:** +``` +See #IFDEF and #IFNDEF +``` + +--- + +### #INCLUDE + +Includes another source file. + +**Syntax:** +``` +#INCLUDE +#INCLUDE +``` + +**Examples:** +``` +#INCLUDE sprites.c65 +#INCLUDE lib/math.c65 +#INCLUDE "constants.c65" +#INCLUDE +``` + +**Notes:** +- Relative path: resolves relative to current file +- Angle brackets ``: searches in library path defined by C65LIBPATH environment variable +- Supports nested includes +- Use with #IFNDEF for include guards + +--- + +### #PRINT + +Prints message during compilation. + +**Syntax:** +``` +#PRINT +``` + +**Examples:** +``` +#PRINT Compiling main module +#PRINT MAX_VALUE +#PRINT Debug build enabled +``` + +**Notes:** +- Useful for debugging preprocessor +- Macros expanded before printing + +--- + +### #HALT + +Stops compilation immediately. + +**Syntax:** +``` +#HALT +``` + +**Examples:** +``` +#IFDEF INCOMPLETE + #PRINT Feature not implemented + #HALT +#IFEND +``` + +**Notes:** +- Halts entire compilation process, not just preprocessing +- Returns exit code 2 + +--- + +### #PRAGMA + +Sets compiler pragmas (options). + +**Syntax:** +``` +#PRAGMA [] +``` + +**Available Pragmas:** + +**_P_USE_LONG_JUMP** +- Uses JMP instead of branch instructions for IF/WHILE/FOR +- Needed when branch targets exceed 127 byte range +- Value: any non-zero value enables + +**_P_USE_IMMUTABLE_CODE** +- Prevents self-modifying code generation +- Required for ROM-based code +- Errors on PEEK/POKE/GOSUB with variable addresses + +**_P_USE_CBM_STRINGS** +- Encodes strings in CBM PETSCII format +- Default: ASCII encoding +- Value: any non-empty value enables + +**Examples:** +``` +#PRAGMA _P_USE_LONG_JUMP 1 +#PRAGMA _P_USE_IMMUTABLE_CODE 1 +#PRAGMA _P_USE_CBM_STRINGS 1 +``` + +--- + +## Code Blocks + +### ASM...ENDASM + +Inline assembly code block. + +**Syntax:** +``` +ASM + +ENDASM +``` + +**Examples:** +``` +ASM + lda #$00 + sta $d020 + jsr $ffd2 +ENDASM + +BYTE temp = 5 +ASM + lda temp + clc + adc #10 + sta temp +ENDASM + +FUNC calculate(value) + BYTE local = 10 + ASM + lda |local| ; Reference local variable + clc + adc value + sta |local| + ENDASM +FEND +``` + +**Notes:** +- Assembly code passed through to ACME assembler unchanged +- Can reference global variables by name +- Local variables inside FUNC must use `|varname|` syntax +- Comments in ASM blocks use `;` (assembly syntax) +- No macro expansion inside ASM blocks + +--- + +### SCRIPT...ENDSCRIPT + +Starlark script code block for generating assembly code. + +Scripts are written in Starlark (Python-like language) and executed at compile time. Output from `print()` statements is fed directly into the assembler. + +**Syntax:** +``` +SCRIPT + +ENDSCRIPT +``` + +**Examples:** + +**Simple data generation:** +``` +SCRIPT + for i in range(256): + print(" !byte %d" % i) +ENDSCRIPT +``` + +**Sine table generation:** +``` +SCRIPT + import math + print("sintable:") + for i in range(256): + angle = (i * 2.0 * math.pi) / 256.0 + sine = math.sin(angle) + value = int((sine + 1.0) * 127.5) + print(" !byte %d" % value) +ENDSCRIPT +``` + +**Using compiler variables:** +``` +BYTE tableSize = 64 + +SCRIPT + # Reference variables in generated assembly + print("lookup:") + for i in range(64): + print(" !byte %d" % (i * 2)) + print(" ; Table size is stored in |tableSize|") +ENDSCRIPT +``` + +**Notes:** +- Scripts use Starlark language (Python-like subset) +- Comments in SCRIPT blocks use `#` (Python syntax) +- Output from `print()` goes directly to assembler +- Can reference compiler variables using `|varname|` syntax +- Math module available: `import math` +- Maximum 1 million execution steps (prevents infinite loops) +- Executed at compile time, not runtime + +--- + +## Expression Syntax + +Expressions evaluate left to right with no operator precedence. + +### Number Formats + +**Decimal:** +``` +123 +0 +255 +65535 +``` + +**Hexadecimal ($-prefix):** +``` +$FF +$D020 +$C000 +$00 +``` + +**Binary (%-prefix):** +``` +%11111111 +%10000000 +%00000001 +%11110000 +``` + +### Operators + +Evaluated strictly left to right: + +- `+` Addition +- `-` Subtraction +- `*` Multiplication +- `/` Division +- `|` Bitwise OR +- `&` Bitwise AND + +### Constants + +Named constants defined with BYTE CONST or WORD CONST: + +``` +BYTE CONST MAX_SPEED = 10 +WORD CONST SCREEN = $0400 + +speed = MAX_SPEED +pointer = SCREEN +``` + +### Expression Examples + +``` +value = 100+50 +result = $FF-10 +address = $D000+32 +mask = %11110000&$0F +combined = base|offset +calculated = start+length*2 +``` + +**Critical:** No operator precedence. Evaluation is strictly left to right: +``` +result = 2+3*4 ; evaluates as (2+3)*4 = 20, not 2+(3*4) = 14 +value = $10|$20&$0F ; evaluates as ($10|$20)&$0F, not $10|($20&$0F) +``` + +### Usage Contexts + +Expressions accepted anywhere a numeric literal is expected: + +**Variable initialization:** +``` +BYTE count = 10+5 +WORD addr = $C000+$100 +``` + +**Absolute addresses:** +``` +BYTE screen @ $0400+40*10 +INC $D000+20 +``` + +**Command parameters:** +``` +FOR i = 0 TO MAX_VALUE-1 +IF x > THRESHOLD+10 +POKE $D020+offset WITH value +result = PEEK $0400+index +``` + +**Arithmetic operations:** +``` +sum = value1+value2 +product = base*factor +adjusted = original+OFFSET +``` + +### Limitations + +**No parentheses for grouping:** +``` +; NOT SUPPORTED: +result = (a+b)*c +value = base+(offset*2) +``` + +**No nested expressions in assignments:** +``` +; NOT SUPPORTED: +x = y + z ; only single value or constant expression +x = a+b ; constant expression (no spaces) OK if a,b are constants +``` + +**Workaround for complex expressions:** +Use temporary variables: +``` +temp = a + b +result = temp * c +``` + +### Constant Expressions + +Expressions without spaces are treated as constant expressions: +``` +value = 100+50 ; OK - constant expression +value = 100 + 50 ; ERROR - not a simple assignment +value = MAX+10 ; OK if MAX is constant +``` \ No newline at end of file