c65gm/syntax.md

Syntax Reference

Comments

C65GM uses C-style line comments.

Syntax:

// <comment text>

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 <n> [= <value>]

Examples:

#DEFINE MAX_SPEED = 10
#DEFINE HELLO = GOODBYE // Will replace the text HELLO in all source with GOODBYE (except ASM and SCRIPT blocks)
#DEFINE HELLO2 = GOOOOOODBYE // Longest match wins. If HELLO2 is encountered this will be the match not the HELLO define above 
#DEFINE SCREEN = $$0400 // Notice $$, see below.
#DEFINE OFFSET = 255

Note: Replacements are not recursive. Once a match is found, it's replaced, and processing starts after the replacement.

Special Characters in Values:

Define values support $ escape sequences for special characters:

• $XX (two hex digits) = character with code XX
• $$ = literal $ character

#DEFINE SPACE = $20          // space character
#DEFINE NEWLINE = $0D        // carriage return
#DEFINE TAB = $09            // tab character
#DEFINE HEXADDR = $$D020     // stores "$D020" as text

Notes:

• Optional = separator
• Value can contain previously defined macros
• Macros are expanded in source lines
• Case sensitive
• $ escapes are processed when the define is created, not when used
• For most purposes, use WORD CONST or BYTE CONST instead of preprocessor defines to define constant named values

---

#UNDEF

Undefines a previously defined macro.

Syntax:

#UNDEF <n>

Examples:

#DEFINE DEBUG = 1
#UNDEF DEBUG

---

#IFDEF

Conditional compilation if macro is defined.

Syntax:

#IFDEF <n>

Examples:

#IFDEF DEBUG
    BYTE debugFlag = 1
#IFEND

#IFDEF PAL
    BYTE scanlines = 312
#IFEND

---

#IFNDEF

Conditional compilation if macro is not defined.

Syntax:

#IFNDEF <n>

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 <filename>
#INCLUDE <libfile>

Examples:

#INCLUDE sprites.c65
#INCLUDE lib/math.c65
#INCLUDE "constants.c65"
#INCLUDE <stdlib.c65>

Notes:

• Relative path: resolves relative to current file
• Angle brackets <file>: 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 <message>

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 <n> [<value>]

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_IMMUTABLE_CODE 0 //turn off pragma
#PRAGMA _P_USE_CBM_STRINGS 1

---

Code Blocks

ASM...ENDASM

Inline assembly code block.

Syntax:

ASM
    <assembly code>
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
    <starlark code>
ENDSCRIPT

Examples:

Simple data generation:

SCRIPT
    for i in range(256):
        print("    !8 %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("    !8 %d" % value)
ENDSCRIPT

Using compiler variables:

BYTE tableSize = 64

SCRIPT
    # Reference variables in generated assembly
    print("lookup:")
    for i in range(64):
        print("    !8 %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
• ^ Bitwise XOR

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