| 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
- 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$).
- Bytes 2–3 (Line Number): The BASIC line number as a 16-bit integer in Little Endian format (e.g.,
0A 00 $\rightarrow$ 10).
- Bytes 4–N (Tokens): The tokenized BASIC command. This sequence of bytes continues until a
$00 (null) terminator is encountered.
- 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:
- Use
r2000_set_data_type on Bytes 0–1 with "data_type": "address".
- Use
r2000_set_data_type on Bytes 2–3 with "data_type": "word".
- Use
r2000_set_data_type from Byte 4 to the $00 terminator (inclusive) with "data_type": "byte".
- Form a complete BASIC line string (e.g.,
10 REM LODE RUNNER).
- 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.
