diff --git a/commands.md b/commands.md index e1c2abf..9d61c26 100644 --- a/commands.md +++ b/commands.md @@ -1,5 +1,47 @@ # Compiler Commands Reference +## Index + +- [ADD](#add) - Adds two values +- [AND](#and) - Bitwise AND operation +- [BREAK](#break) - Exits current loop +- [BYTE](#byte) - Declares 8-bit variable or constant +- [CALL](#call) - Calls function with parameters +- [CASE](#case) - Case branch in SWITCH statement +- [DEC](#dec) - Decrements variable or memory location +- [DEFAULT](#default) - Default branch in SWITCH statement +- [ELSE](#else) - Alternative branch in IF statement +- [ENDIF](#endif) - Terminates IF block +- [ENDSWITCH](#endswitch) - Terminates SWITCH block +- [FEND](#fend) - Ends function definition +- [FOR](#for) - Loop with automatic counter increment +- [FUNC](#func) - Defines function with parameters +- [GOSUB](#gosub) - Calls subroutine with register passing +- [GOTO](#goto) - Unconditional jump to label +- [IF](#if) - Conditional execution +- [INC](#inc) - Increments variable or memory location +- [LABEL](#label) - Creates named assembly label +- [LET](#let) - Assigns value to variable +- [NEXT](#next) - Terminates FOR loop +- [OR](#or) - Bitwise OR operation +- [ORIGIN](#origin) - Sets assembly origin address +- [PEEK](#peek) - Reads byte from memory +- [PEEKW](#peekw) - Reads word from memory +- [POINTER](#pointer) - Sets pointer to address +- [POKE](#poke) - Writes byte to memory +- [POKEW](#pokew) - Writes word to memory +- [SUBEND](#subend) - Returns from subroutine +- [SHIFTL](#shiftl) - Logical shift left +- [SHIFTR](#shiftr) - Logical shift right +- [SUBTR](#subtr) - Subtracts values +- [SWITCH](#switch) - Multi-way branching +- [WEND](#wend) - Terminates WHILE loop +- [WHILE](#while) - Loop while condition true +- [WORD](#word) - Declares 16-bit variable or constant +- [XOR](#xor) - Bitwise XOR operation + +--- + ## ADD Adds two values and stores result in destination. @@ -46,13 +88,18 @@ BREAK ``` **Examples:** + ``` +// BREAK in FOR loop FOR i = 0 TO 100 IF i = 50 BREAK ENDIF NEXT +``` +``` +// BREAK in WHILE loop WHILE counter < 1000 counter++ IF error @@ -117,10 +164,7 @@ process("hello",42,myvar) Defines a case branch within SWITCH statement. -**Syntax:** -``` -See SWITCH -``` +See [SWITCH](#switch) for syntax and examples. --- @@ -136,11 +180,21 @@ DECREMENT ``` **Examples:** + ``` +// Modern: decrement variables counter-- lives-- index-- +``` + +``` +// Alternative: decrement memory location DEC $D020 +``` + +``` +// Legacy: DECREMENT form DECREMENT screenColor ``` @@ -150,10 +204,7 @@ DECREMENT screenColor Defines the default branch in SWITCH statement. -**Syntax:** -``` -See SWITCH -``` +See [SWITCH](#switch) for syntax and examples. --- @@ -161,10 +212,7 @@ See SWITCH Alternative branch in IF statement. -**Syntax:** -``` -See IF -``` +See [IF](#if) for syntax and examples. --- @@ -172,10 +220,7 @@ See IF Terminates IF block. -**Syntax:** -``` -See IF -``` +See [IF](#if) for syntax and examples. --- @@ -183,10 +228,7 @@ See IF Terminates SWITCH block. -**Syntax:** -``` -See SWITCH -``` +See [SWITCH](#switch) for syntax and examples. --- @@ -194,10 +236,7 @@ See SWITCH Ends a function definition. -**Syntax:** -``` -See FUNC -``` +See [FUNC](#func) for syntax and examples. --- @@ -211,11 +250,16 @@ FOR = TO ``` **Examples:** + ``` +// FOR loop with literal values FOR i = 0 TO 10 screen = i NEXT +``` +``` +// FOR loop with variables FOR counter = start TO finish process(counter) NEXT @@ -247,28 +291,37 @@ FUNC name ( in:x out:y io:z ) # direction with pre-declared (legacy) ``` **Examples:** + ``` // Modern: self-contained function with local parameters FUNC add({BYTE a} {BYTE b} out:{BYTE result}) result = a + b FEND +``` +``` // Modern: with direction modifiers FUNC process(in:{BYTE input} out:{BYTE output}) output = input + 1 FEND +``` +``` // Modern: io parameter (read-write) FUNC increment(io:{BYTE counter}) counter = counter + 1 FEND +``` +``` // Modern: absolute address parameter FUNC read_byte({BYTE data @ $fa}) BYTE temp temp = data // Reads from $fa FEND +``` +``` // Legacy: uses global variables directly BYTE x BYTE y @@ -336,17 +389,25 @@ IF [ ] Operators: `=` `==` `<>` `!=` `>` `<` `>=` `<=` **Examples:** + ``` +// Simple IF statement IF count == 10 result = 1 ENDIF +``` +``` +// IF with ELSE branch IF value > threshold process(value) ELSE skip(value) ENDIF +``` +``` +// IF-ELSE with actions IF x < 100 x++ ELSE @@ -368,11 +429,21 @@ INCREMENT ``` **Examples:** + ``` +// Modern: increment variables counter++ index++ frameCount++ +``` + +``` +// Alternative: increment memory location INC $D020 +``` + +``` +// Legacy: INCREMENT form INCREMENT screenColor ``` @@ -421,10 +492,7 @@ value = 100+50 Loop terminator for FOR. -**Syntax:** -``` -See FOR -``` +See [FOR](#for) for syntax and examples. --- @@ -499,19 +567,27 @@ For operating with offsets the address parameter must be an absolute WORD variab ``` **Examples:** + ``` +// Read from absolute address reset_addr = PEEKW $FFFE +``` +``` +// Read with offset (requires WORD variable in zero page) WORD buffer @ $fd -offset_val = PEEKW buff_ptr[10] +offset_val = PEEKW buffer[10] +``` +``` +// Read through pointer WORD pointer val = PEEKW pointer ``` --- -## POINT +## POINTER Sets pointer variable to address of target. @@ -586,11 +662,16 @@ EXIT ``` **Examples:** + ``` +// Simple subroutine with SUBEND LABEL subroutine counter = counter + 1 SUBEND +``` +``` +// Subroutine with early EXIT LABEL checkValue IF value = 0 EXIT @@ -625,10 +706,20 @@ SHIFTL << -> - WORD→BYTE conversion truncates low byte only **Examples:** + ``` +// Modern: assignment form result = value << 3 +``` + +``` +// Alternative: arrow form +SHIFTL flags << 2 -> masked +``` + +``` +// Legacy: verbose form SHIFTL mask BY bits GIVING shifted -SHIFTR flags >> 2 -> masked ``` --- @@ -657,12 +748,22 @@ SHIFTR >> -> - WORD→BYTE conversion truncates low byte only **Examples:** + ``` +// Modern: assignment form mask = flags >> 2 -SHIFTR value BY shift GIVING result +``` + +``` +// Alternative: arrow form SHIFTR data >> 4 -> nibble ``` +``` +// Legacy: verbose form +SHIFTR value BY shift GIVING result +``` + --- ## SUBTR @@ -712,6 +813,7 @@ ENDSWITCH - Nested SWITCH statements are supported **Examples:** + ``` // Basic switch with default SWITCH status @@ -722,7 +824,9 @@ SWITCH status DEFAULT result = 0 ENDSWITCH +``` +``` // Switch with constants BYTE CONST MAX = 100 SWITCH value @@ -731,7 +835,9 @@ SWITCH value CASE 50 halfway = 1 ENDSWITCH +``` +``` // WORD switch WORD big_val SWITCH big_val @@ -742,7 +848,9 @@ SWITCH big_val DEFAULT mode = 0 ENDSWITCH +``` +``` // Nested switch SWITCH outer CASE 1 @@ -757,7 +865,9 @@ SWITCH outer DEFAULT result = 0 ENDSWITCH +``` +``` // Using variables in CASE BYTE threshold1 BYTE threshold2 @@ -779,10 +889,7 @@ ENDSWITCH Terminates WHILE loop. -**Syntax:** -``` -See WHILE -``` +See [WHILE](#while) for syntax and examples. --- @@ -800,17 +907,25 @@ WHILE [ ] Operators: `=` `==` `<>` `!=` `>` `<` `>=` `<=` **Examples:** + ``` +// WHILE with numeric comparison WHILE counter < 100 counter++ result = result + counter WEND +``` +``` +// WHILE with boolean condition WHILE running processFrame checkInput WEND +``` +``` +// WHILE with inequality WHILE x != y x++ WEND