feat: add user-defined functions (fn/endfn) (#115)

- Add single-line (`fn square(x) = x * x`) and multi-line (`fn`/`endfn`) user-defined functions
- `return` inside a function body evaluates and returns an expression
- Functions are called by name as expressions (e.g. `print square(5)`) — no `fn` keyword needed
- Supports nested function calls (e.g. `print add(square(2), square(3))`)
- Supports parameter localisation, control structures within function bodies, and up to 8 levels of nesting
- Eval stack is saved/restored on hardware stack for multi-line calls
- Nesting stacks protect against corruption from recursive calls
- `list` supports `fn` definitions (single-line and multi-line)
- String return values are copied to temp storage before local unwind
- Move error text strings to module page 1 to free ROM space for the new code

Author: mbrukner

modules/tokeniser/__kwdtext.asm

@@ -52,54 +52,56 @@ KeywordSet0:
 	.text	4,$40,"TRUE"           ; $ae TRUE
 	.text	4,$0b,"VAL("           ; $af VAL(
 	.text	4,$05,"FRE("           ; $b0 FRE(
-	.text	3,$e7,"FOR"            ; $b1 FOR
-	.text	2,$8f,"IF"             ; $b2 IF
-	.text	4,$34,"PROC"           ; $b3 PROC
-	.text	6,$c1,"REPEAT"         ; $b4 REPEAT
-	.text	5,$79,"WHILE"          ; $b5 WHILE
-	.text	5,$66,"ENDIF"          ; $b6 ENDIF
-	.text	7,$0b,"ENDPROC"        ; $b7 ENDPROC
-	.text	4,$3f,"NEXT"           ; $b8 NEXT
-	.text	4,$2f,"THEN"           ; $b9 THEN
-	.text	5,$8c,"UNTIL"          ; $ba UNTIL
-	.text	4,$2e,"WEND"           ; $bb WEND
-	.text	2,$95,"AT"             ; $bc AT
-	.text	2,$9b,"BY"             ; $bd BY
-	.text	4,$1c,"CALL"           ; $be CALL
-	.text	6,$b2,"CIRCLE"         ; $bf CIRCLE
-	.text	5,$67,"CLEAR"          ; $c0 CLEAR
-	.text	5,$7f,"COLOR"          ; $c1 COLOR
-	.text	6,$d4,"COLOUR"         ; $c2 COLOUR
-	.text	4,$1a,"DATA"           ; $c3 DATA
-	.text	3,$da,"DIM"            ; $c4 DIM
-	.text	6,$db,"DOWNTO"         ; $c5 DOWNTO
-	.text	4,$29,"ELSE"           ; $c6 ELSE
-	.text	4,$34,"FROM"           ; $c7 FROM
-	.text	3,$e5,"GFX"            ; $c8 GFX
-	.text	4,$24,"HERE"           ; $c9 HERE
-	.text	5,$63,"IMAGE"          ; $ca IMAGE
-	.text	3,$e5,"LET"            ; $cb LET
-	.text	4,$28,"LINE"           ; $cc LINE
-	.text	5,$6b,"LOCAL"          ; $cd LOCAL
-	.text	7,$1a,"MEMCOPY"        ; $ce MEMCOPY
-	.text	3,$db,"OFF"            ; $cf OFF
-	.text	2,$9d,"ON"             ; $d0 ON
-	.text	7,$20,"OUTLINE"        ; $d1 OUTLINE
-	.text	7,$0f,"PALETTE"        ; $d2 PALETTE
-	.text	4,$3f,"PLOT"           ; $d3 PLOT
-	.text	4,$2f,"POKE"           ; $d4 POKE
-	.text	5,$73,"POKED"          ; $d5 POKED
-	.text	5,$7b,"POKEL"          ; $d6 POKEL
-	.text	5,$86,"POKEW"          ; $d7 POKEW
-	.text	4,$1c,"READ"           ; $d8 READ
-	.text	4,$2e,"RECT"           ; $d9 RECT
-	.text	3,$e4,"REM"            ; $da REM
-	.text	5,$7b,"SOLID"          ; $db SOLID
-	.text	5,$89,"SOUND"          ; $dc SOUND
-	.text	6,$d7,"SPRITE"         ; $dd SPRITE
-	.text	4,$45,"TEXT"           ; $de TEXT
-	.text	2,$a3,"TO"             ; $df TO
-	.text	4,$3c,"STEP"           ; $e0 STEP
+	.text	2,$94,"FN"             ; $b1 FN
+	.text	3,$e7,"FOR"            ; $b2 FOR
+	.text	2,$8f,"IF"             ; $b3 IF
+	.text	4,$34,"PROC"           ; $b4 PROC
+	.text	6,$c1,"REPEAT"         ; $b5 REPEAT
+	.text	5,$79,"WHILE"          ; $b6 WHILE
+	.text	5,$6b,"ENDFN"          ; $b7 ENDFN
+	.text	5,$66,"ENDIF"          ; $b8 ENDIF
+	.text	7,$0b,"ENDPROC"        ; $b9 ENDPROC
+	.text	4,$3f,"NEXT"           ; $ba NEXT
+	.text	4,$2f,"THEN"           ; $bb THEN
+	.text	5,$8c,"UNTIL"          ; $bc UNTIL
+	.text	4,$2e,"WEND"           ; $bd WEND
+	.text	2,$95,"AT"             ; $be AT
+	.text	2,$9b,"BY"             ; $bf BY
+	.text	4,$1c,"CALL"           ; $c0 CALL
+	.text	6,$b2,"CIRCLE"         ; $c1 CIRCLE
+	.text	5,$67,"CLEAR"          ; $c2 CLEAR
+	.text	5,$7f,"COLOR"          ; $c3 COLOR
+	.text	6,$d4,"COLOUR"         ; $c4 COLOUR
+	.text	4,$1a,"DATA"           ; $c5 DATA
+	.text	3,$da,"DIM"            ; $c6 DIM
+	.text	6,$db,"DOWNTO"         ; $c7 DOWNTO
+	.text	4,$29,"ELSE"           ; $c8 ELSE
+	.text	4,$34,"FROM"           ; $c9 FROM
+	.text	3,$e5,"GFX"            ; $ca GFX
+	.text	4,$24,"HERE"           ; $cb HERE
+	.text	5,$63,"IMAGE"          ; $cc IMAGE
+	.text	3,$e5,"LET"            ; $cd LET
+	.text	4,$28,"LINE"           ; $ce LINE
+	.text	5,$6b,"LOCAL"          ; $cf LOCAL
+	.text	7,$1a,"MEMCOPY"        ; $d0 MEMCOPY
+	.text	3,$db,"OFF"            ; $d1 OFF
+	.text	2,$9d,"ON"             ; $d2 ON
+	.text	7,$20,"OUTLINE"        ; $d3 OUTLINE
+	.text	7,$0f,"PALETTE"        ; $d4 PALETTE
+	.text	4,$3f,"PLOT"           ; $d5 PLOT
+	.text	4,$2f,"POKE"           ; $d6 POKE
+	.text	5,$73,"POKED"          ; $d7 POKED
+	.text	5,$7b,"POKEL"          ; $d8 POKEL
+	.text	5,$86,"POKEW"          ; $d9 POKEW
+	.text	4,$1c,"READ"           ; $da READ
+	.text	4,$2e,"RECT"           ; $db RECT
+	.text	3,$e4,"REM"            ; $dc REM
+	.text	5,$7b,"SOLID"          ; $dd SOLID
+	.text	5,$89,"SOUND"          ; $de SOUND
+	.text	6,$d7,"SPRITE"         ; $df SPRITE
+	.text	4,$45,"TEXT"           ; $e0 TEXT
+	.text	2,$a3,"TO"             ; $e1 TO
+	.text	4,$3c,"STEP"           ; $e2 STEP
 	.text	$FF
 KeywordSet1:
 	.text	0,$65,""               ; $80 !0:EOF

source/Makefile

@@ -29,9 +29,8 @@ MODULES = +hardware +tokeniser +kernel +graphics:2 +sound:2
 BUILD_OUT = $(BUILDDIR)basic.rom
 SCRIPTDIR = scripts$(S)
 MAME_PATH=../../mame
-IMAGE_PATH := sd
-IMAGE := $(IMAGE_PATH).img
 BASIC_TESTS_PATH=$(PWD)/../test
+IMAGE := $(BASIC_TESTS_PATH)/.output/tests.img
 
 all:  build
 
@@ -95,9 +94,6 @@ build: prelim
 #		Scripts run in advance generating tables etc.
 #
 prelim:
-	@echo "Building submodules"
-	$(Q)$(MAKE) -B -C ..$(S)modules clean all
-
 	@echo "Generating assembly sources"
 	$(Q)$(PYTHON) $(SCRIPTDIR)errors.py $(LANGUAGE)
 	$(Q)$(PYTHON) $(SCRIPTDIR)opcodes.py >common$(S)generated$(S)asmcore.asm
@@ -106,6 +102,9 @@ prelim:
 	$(Q)$(PYTHON) $(SCRIPTDIR)constants.py
 	$(Q)$(PYTHON) $(SCRIPTDIR)version.py $(VERSION)
 
+	@echo "Building submodules"
+	$(Q)$(MAKE) -B -C ..$(S)modules clean all
+
 #
 #		Print base version to console
 #
@@ -192,9 +191,10 @@ flash: build
 #		Test in emulator
 #
 emu: build $(IMAGE)
-	cp $(BUILDDIR)/sb*.bin $(MAME_PATH)/roms/f256k
+	$(Q)$(CCOPY) $(BUILDDIR)/sb*.bin $(MAME_PATH)/roms/f256k
+	$(Q)$(CDEL) $(MAME_PATH)/nvram/f256k/flash
 	cd $(MAME_PATH) && ./f256k f256k -window -resolution 1280x720 -skip_gameinfo -harddisk $(BASIC_TESTS_PATH)/.output/tests.img -rompath roms
-	#cd $(MAME_PATH) && ./f256k f256k -window -resolution 1280x720 -skip_gameinfo -harddisk $(BASIC_TESTS_PATH)/.output/tests.img -rompath roms -script $(LAUNCH_SCRIPT) -log
 
-$(IMAGE): $(BASIC_TESTS_PATH)/ashanghai
-	$(BASIC_TESTS_PATH)/prepare-disk.py -t $<
+$(IMAGE): $(BASIC_TESTS_PATH)/fnproc
+	$(PYTHON) $(BASIC_TESTS_PATH)/prepare-disk.py -t $<
+

source/_basic.asm

@@ -35,6 +35,7 @@
 	.include	"./common/commands/assert.asm"
 	.include	"./common/commands/call.asm"
 	.include	"./common/commands/data.asm"
+	.include	"./common/commands/def.asm"
 	.include	"./common/commands/dim.asm"
 	.include	"./common/commands/end.asm"
 	.include	"./common/commands/for.asm"
@@ -150,6 +151,7 @@
 	.include	"./common/stack/setup.asm"
 	.include	"./common/strings/concrete.asm"
 	.include	"./common/strings/stringalloc.asm"
+	.include	"./common/expressions/unary/fn.asm"
 
 
 .section code
@@ -163,6 +165,9 @@ StartModuleCode:
 	.include	"../modules/.build/tokeniser.module.asm"
 	.include	"../modules/.build/kernel.module.asm"
 
+; --- Error text in module page 1 ---
+	.include	"./common/generated/_errortext.asm"
+
 ; --- Header data in boot section ($6000-$7FFF) ---
 	.include	"../modules/hardware/header/.build/headerdata.dat"
 

source/common/aa.system/04data.inc

@@ -76,6 +76,9 @@ NSMantissa3:
 NSExponent: 								; Exponent , 0 = Mantissa is integer
 		.fill 	MathStackSize
 
+fnStackLevel:								; saved stack level for function evaluation
+		.fill 	1
+
 		.send zeropref
 
 
@@ -151,6 +154,8 @@ listIndent:	 								; list indent level.
 		.fill 	1
 listElseFound:								; flag set when ELSE found on line (for indent fix)
 		.fill 	1
+listEndToken:								; closing token for LIST proc/fn
+		.fill 	1
 lcLastCharacter: 							; last character output.
 		.fill 	1	
 isPrintFlag:	 							; zero if input, non-zero if print, bit 6 zero = character print