r2000-analyze-basic

name	r2000-analyze-basic
description	Analyzes a sequence of memory containing Commodore BASIC tokens, formats address/word data types, and constructs side comments representing the plain BASIC commands.

Analyze BASIC Tokens Workflow

Use this skill when the user asks to:

• "analyze this BASIC code"
• "decode basic commands from memory"
• "create side comments for BASIC lines"
• "parse basic pointer address and line number"

1. Determine Memory Range

Identify the starting and ending addresses of the Commodore BASIC sequence from the user's request or cross-references. If unspecified, prompt the user for clarification.

2. Read Memory Buffer

Invoke the r2000_read_region tool to read the requested sequence:

• start_address: The sequence start address (decimal).
• end_address: The sequence end address (decimal).
• view: "hexdump"

3. Process BASIC Lines

Commodore BASIC programs follow a strict structured sequence in memory. Iterate through the lines starting from the initial address, following the "Next Line Pointer" until you reach the end of the program.

Line Anatomy

1. Bytes 0–1 (Next Line Pointer): Pointer to the memory address where the next BASIC line begins, stored in Little Endian format (e.g., 24 04 $\rightarrow$ `$0424$).
2. Bytes 2–3 (Line Number): The BASIC line number as a 16-bit integer in Little Endian format (e.g., 0A 00 $\rightarrow$ 10).
3. Bytes 4–N (Tokens): The tokenized BASIC command. This sequence of bytes continues until a $00 (null) terminator is encountered.
4. Termination: The program ends when the "Next Line Pointer" (Bytes 0–1) of a line is $00 $00.

Keyword Token Table (V2)

Bytes in step 3 with the high-bit set ($80 to $CB) are keyword tokens. Decode them against this table:

Hex	Keyword	Hex	Keyword	Hex	Keyword	Hex	Keyword
$80	END	$93	LOAD	$A6	SPC(	$B9	POS
$81	FOR	$94	SAVE	$A7	THEN	$BA	SQR
$82	NEXT	$95	VERIFY	$A8	NOT	$BB	RND
$83	DATA	$96	DEF	$A9	STEP	$BC	LOG
$84	INPUT#	$97	POKE	$AA	+	$BD	EXP
$85	INPUT	$98	PRINT#	$AB	-	$BE	COS
$86	DIM	$99	PRINT

(Note: Bytes between $20 and $7F are literal PETSCII text characters like strings, variables, and numbers).

4. Apply Modifications

Formulate a sequence of commands for r2000_batch_execute to apply the modifications for all decoded BASIC lines at once.

For each decoded line:

1. Use r2000_set_data_type on Bytes 0–1 with "data_type": "address".
2. Use r2000_set_data_type on Bytes 2–3 with "data_type": "word".
3. Use r2000_set_data_type from Byte 4 to the $00 terminator (inclusive) with "data_type": "byte".
4. Form a complete BASIC line string (e.g., 10 REM LODE RUNNER).
5. Use r2000_set_comment to set this string as a "side" comment at the start of the line (Byte 0).

Continue this process by jumping to the address specified in the "Next Line Pointer" until the pointer is $00 $00. Finally, mark the $00 $00 terminator itself as "word".

5. Save Project

When completed, invoke r2000_save_project to persist the comments and types.