QBasic to BBC BASIC Transpiler for AgonLight

A Python-based transpiler that converts QBasic programs to BBC BASIC for the AgonLight retro computer.

Features

• Full QBasic standard support
• Comprehensive test coverage (unit and integration tests)
• AgonLight-specific extensions for graphics and filesystem operations
• AST-based transpilation for accurate code transformation

Requirements

• Python 3.10 or higher
• uv (recommended for dependency management)

Installation

Using uv (Recommended)

# Clone the repository
git clone <repository-url>
cd q-bbc-basic-transpiler

# Install dependencies and set up the virtual environment
uv sync

Using pip

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e ".[dev]"

Usage

Transpile a QBasic file

# Using uv
uv run python -m src input.bas output.bas

# Or activate the virtual environment first
source .venv/bin/activate
python -m src input.bas output.bas

Examples

# Transpile the hello world example
uv run python -m src ./examples/hello.bas hello_bbc.bas

# Transpile the calculator example
uv run python -m src ./examples/calculator.bas calculator_bbc.bas

# Transpile the graphics demo (uses AgonLight extensions)
uv run python -m src ./examples/graphics_demo.bas graphics_bbc.bas

Development

Running Tests

# Run all tests with coverage
uv run pytest

# Run tests with verbose output
uv run pytest -v

# Run specific test file
uv run pytest tests/unit/test_lexer.py -v

# Run tests and generate HTML coverage report
uv run pytest --cov=src --cov-report=html
# Open htmlcov/index.html in your browser

Code Quality

# Run linting (if ruff is configured)
uv run ruff check src/

# Run type checking (if mypy is configured)
uv run mypy src/

Project Structure

q-bbc-basic-transpiler/
├── src/                  # Source code
│   ├── __init__.py
│   ├── __main__.py       # CLI entry point
│   ├── ast.py            # Abstract Syntax Tree definitions
│   ├── lexer.py          # Lexical analyzer
│   ├── parser.py         # Recursive descent parser
│   ├── transpiler.py     # QBasic to BBC BASIC transpiler
│   ├── codegen.py        # BBC BASIC code generator
│   ├── extensions.py     # AgonLight extension handlers
│   └── mappings.py       # QBasic to BBC BASIC mappings
├── tests/                # Test suite
│   ├── unit/             # Unit tests
│   │   ├── test_lexer.py
│   │   ├── test_parser.py
│   │   ├── test_transpiler.py
│   │   └── test_codegen.py
│   └── integration/      # Integration tests
│       ├── test_integration.py
│       └── test_cases/   # Test case files
├── examples/             # Example QBasic programs
│   ├── hello.bas
│   ├── calculator.bas
│   └── graphics_demo.bas
├── docs/                 # Documentation
│   ├── agonlight_extensions.md
│   ├── bbc_basic_mapping.md
│   └── qbasic_features.md
├── pyproject.toml        # Project configuration
└── README.md

Supported QBasic Features

• Control Flow: IF/THEN/ELSE, FOR/NEXT, WHILE/WEND, DO/LOOP, SELECT CASE
• Variables: Integer, Long, Single, Double, String types
• Arrays: Multi-dimensional arrays with DIM
• Procedures: SUB and FUNCTION definitions
• I/O: PRINT, INPUT, OPEN, CLOSE, READ, WRITE, DATA, RESTORE
• Expressions: Arithmetic, logical, and comparison operators
• AgonLight Extensions: MODE, GCOL, MOVE, DRAW, PLOT, CLS, COLOUR

License

MIT