Final: HDL Parser and Chip Testing Framework

Nand2Tetris final project

Features

• Parses HDL files with IN, OUT, and PARTS sections
• Simulates both built-in and composed chips recursively
• Supports testing via CSV-style test vectors
• Command-line interface using Typer
• Strict linting, formatting, and typing
• Includes unit tests and test coverage reporting

Getting Started

1. Install Dependencies

   pip install -r requirements.txt

2. Run the CLI

   python3 -m n2t.runner test

3. Run Unit Tests

   pytest

4. Check Linting, Types, and Format

   black n2t tests
   isort n2t tests
   flake8 n2t tests
   mypy n2t tests

5. Run Coverage

   pytest --cov=n2t

Makefile Shortcuts

This project includes a Makefile to simplify development tasks. Here are the available commands:

make lint        # Run black, isort, flake8, and mypy
make test        # Run all unit tests
make coverage    # Show test coverage report
make clean       # Remove cache and temporary files

Instead of typing multiple commands, use make to run them in one go.

Note: You must have make installed (typically preinstalled on Unix/macOS).

Project Structure

n2t/
├── core/            # HDL parser, chip model, simulator
├── util/            # CSV test file parser
├── runner/          # Typer CLI entry point
tests/               # Unit tests and test vectors
chips/               # HDL chip definitions

Example CSV Test Format

a,b; out
0,0; 0
0,1; 0
1,0; 0
1,1; 1

Built-in Gates

These are hardcoded and not parsed from HDL:

• And
• Or
• Not
• Nand

Testing Your Own Chips

You can test your own custom HDL chips by following these steps:

1. Place your .hdl file into the chips/ directory.
   For example:

   chips/MyChip.hdl
   

2. Create a matching test vector file and place it in tests/e2e/ with the same base name.
   For example:

   tests/e2e/MyChip.csv
   

   Example CSV test format:

   a,b; out
   0,0; 0
   1,1; 1
   

3. Run the CLI to test all available chips:

   python3 -m n2t.runner test

The runner will automatically detect and test any HDL files for which a matching .csv file exists in tests/e2e/.