Classic BASIC Interpreter

A line-by-line interpreter for a classic BASIC dialect, implemented in C.

Features

• Line-Oriented Programming: Traditional BASIC style with line numbers
• Variable Types: Numbers and strings
• Control Structures: GOTO, GOSUB/RETURN, IF/THEN, FOR/NEXT
• Expressions: Arithmetic and string operations with operator precedence
• Built-in Functions: RND, LEN, LEFT$, RIGHT$, MID$
• File I/O: OPEN, CLOSE, INPUT#, PRINT#
• Sound & Graphics: Basic placeholder implementations
• Garbage Collection: Integrated mark-and-sweep memory management
• Debugger: BREAK, STEP, WATCH, LIST commands
• REPL Environment: Interactive command-line interface
• State Serialization: Save/load program state to resume later

Building

make

Usage

Interactive Mode

./basic

Run a Program File

./basic my_program.bas

Testing Modules

./basic --test-tokenizer      # Test the tokenizer
./basic --test-line-manager   # Test the line manager
./basic --test-symbol-table   # Test variable management
./basic --test-execution      # Test execution loop
./basic --test-control        # Test control structures
./basic --test-expressions    # Test expressions and functions
./basic --test-file-io        # Test file I/O
./basic --test-sound-graphics # Test sound and graphics
./basic --test-gc             # Test garbage collection
./basic --test-debugger       # Test debugger commands
./basic --test-debug-integration # Test debugger integration
./basic --test-repl           # Test REPL functionality
./basic --test-state          # Test state save/load
./basic --test-comprehensive  # Run comprehensive test suite
./basic --test-final          # Run final integration test suite
./basic --help                # Show usage information

BASIC Commands

The interpreter supports classic BASIC commands:

Program Control

• RUN - Run the program
• LIST - List the program
• NEW - Clear program from memory
• CLEAR - Clear variables

Program Flow

• GOTO <line> - Jump to line
• GOSUB <line> - Call subroutine
• RETURN - Return from subroutine
• FOR <var>=<start> TO <end> [STEP <step>] - Begin loop
• NEXT <var> - End loop
• IF <expr> THEN <line> - Conditional branch
• END - End program

Input/Output

• PRINT <expr>[;<expr>...] - Print to screen
• INPUT <var> - Get input from user
• OPEN "<filename>" FOR <mode> AS #<n> - Open file
• CLOSE #<n> - Close file
• PRINT #<n>, <expr> - Print to file
• INPUT #<n>, <var> - Input from file

Sound & Graphics

• BEEP - Make a beep sound
• SOUND <freq>, <duration> - Play a tone
• LINE (<x1>,<y1>)-(<x2>,<y2>) - Draw a line
• CIRCLE (<x>,<y>), <radius> - Draw a circle
• PLOT <x>, <y> - Draw a point

State Management

• SAVE <filename> - Save program
• LOAD <filename> - Load program
• SAVESTATE <filename> - Save program state
• LOADSTATE <filename> - Load program state

Debug Commands

• DEBUG - Toggle debug mode
• BREAK <line> - Set breakpoint
• STEP - Execute one line
• WATCH <var> - Watch variable
• CONTINUE - Resume execution

Example Program

10 REM Simple BASIC program
20 PRINT "Hello, BASIC!"
30 INPUT "What is your name? ", name$
40 PRINT "Nice to meet you, "; name$
50 FOR i = 1 TO 5
60   PRINT "Counting: "; i
70 NEXT i
80 END

Project Structure

• main.c: Entry point and test functions
• basic.h: Core data structures
• token.h/tokenizer.c: Lexical analysis
• line_manager.h/c: Line storage and management
• execution.h/c: Execution loop and command handlers
• expression.h/c: Expression parsing and evaluation
• symboltable.c: Variable storage and retrieval
• memory_manager.h/c: Garbage collection
• debugger.h/c: Debugging functionality
• repl.h/c: Read-Eval-Print Loop
• error_handler.h/c: Centralized error handling

Implementation Details

The interpreter follows a traditional line-by-line execution model:

1. Tokenization: Source lines are broken into tokens
2. Line Storage: Program lines are stored by line numbers
3. Execution: Lines execute sequentially unless redirected by control structures
4. Expression Evaluation: Recursive descent parsing with operator precedence
5. Memory Management: Custom mark-and-sweep garbage collection
6. Error Handling: Centralized error reporting with file/line information
7. Makefile: Automatic dependency generation with -MMD -MP flags

Incomplete Features and Stubs

The following features are currently implemented as stubs or placeholders:

1. Parser Module (parser.c): Currently just a stub implementation. The tokenizer is used directly rather than a proper parser.

2. Lexer Module (lexer.c): Currently just a stub implementation. The tokenizer (tokenizer.c) is used instead.

3. Graphics Commands: The following commands are stub implementations that don't actually render graphics:

   • LINE (<x1>,<y1>)-(<x2>,<y2>) - Just prints a placeholder message
   • CIRCLE (<x>,<y>), <radius> - Just prints a placeholder message
   • PLOT <x>, <y> - Just prints a placeholder message

4. Sound Commands: The following commands have minimal implementations:

   • BEEP - Uses the terminal bell character rather than a proper sound library
   • SOUND <freq>, <duration> - Parses parameters but doesn't actually generate sounds

These stubs are marked with #WARNING comments in the code to make them easily findable for future developers.

License

This project is free to use and distribute.