Nand2Tetris Language Extension for Zed

Complete language support for the nand2tetris course in the Zed editor, providing syntax highlighting, parsing, and editor integration for all major nand2tetris file types.

Supported Languages

• HDL (Hardware Description Language) - for describing digital circuits and chips
• Jack - the high-level programming language used in the software construction part
• Hack Assembly - the assembly language for the Hack computer platform
• Hack Binary - machine code files (.hack) with 16-bit binary instructions
• VM Language - the virtual machine intermediate language
• Test Scripts - for testing and simulation of hardware and software components
• Compare/Output Files - for test result comparison and output verification
• XML - compiler output files from Jack compiler

Features

HDL Support

• Enhanced syntax highlighting for chip declarations, pin definitions, and part instantiations
• Array notation support for a[16], out[0..7], and bit ranges
• Boolean literal support for true and false values in connections
• Recognizes HDL keywords: CHIP, IN, OUT, PARTS
• Improved highlighting for identifiers, numbers, comments, and operators
• Complete bracket matching for {}, (), and []
• Enhanced code outline showing chip structure with better hierarchy
• Comment toggling with Cmd+/ (or Ctrl+/)
• Better indentation support for nested structures

Jack Support

• Full syntax highlighting for Jack language constructs
• Support for classes, methods, functions, constructors
• Recognizes all Jack keywords and built-in types
• Proper highlighting for control flow (if, while, return)
• Bracket matching and smart indentation
• Code outline showing class structure with methods and fields
• Comment support for both // and /* */ style comments
• Special highlighting for built-in constants (this, true, false, null)

Hack Assembly Support

• Enhanced syntax highlighting for A-instructions (@value, @symbol)
• Comprehensive C-instruction highlighting with dest, comp, and jump fields
• Full support for all computation operations and jump conditions
• Label declaration highlighting ((LABEL)) with proper bracket matching
• Complete predefined symbol recognition (R0-R15, SP, LCL, ARG, THIS, THAT, SCREEN, KBD)
• User-defined variable and symbol support with proper highlighting
• Negative constant support (@-1, @-32768)
• Enhanced comment highlighting (// comment)
• Better code outline showing labels, symbols, and control flow
• Improved bracket matching for parentheses in labels

VM Language Support

• Syntax highlighting for all VM commands
• Stack arithmetic operations (add, sub, neg, eq, gt, lt, and, or, not)
• Memory access commands (push, pop) with all segments
• Program flow commands (label, goto, if-goto)
• Function commands (function, call, return)
• Memory segment highlighting (argument, local, static, constant, this, that, pointer, temp)
• Code outline showing function declarations and labels

Test Script Support

• Syntax highlighting for test commands (load, output-file, compare-to, set, eval, output)
• Simulation control commands (tick, tock, ticktock)
• Control flow structures (repeat, while)
• Variable reference highlighting (RAM[n], register names, pin names)
• Binary and format specification highlighting
• Bracket matching for control blocks

Compare/Output File Support

• Tabular data formatting for test results
• Header row highlighting with column names
• Binary and decimal value highlighting
• Register and pin reference recognition
• Table structure visualization

Changelog

Version 2.3.0 - Individual Grammar Repositories

• NEW: All grammars now have individual GitHub repositories for better maintenance
• NEW: Complete language support for all 8 nand2tetris languages
• IMPROVED: More reliable grammar loading with external repositories
• IMPROVED: Better organization and dependency management
• IMPROVED: Easier updates and maintenance of individual grammars

Version 2.1.0 - Enhanced HDL Support

• NEW: Array notation support (a[16], out[0..7], bit ranges)
• NEW: Boolean literal support (true, false in connections)
• IMPROVED: Enhanced syntax highlighting with better visual distinction
• IMPROVED: Complete bracket matching including [] for arrays
• IMPROVED: Better code outline and indentation support
• FIXED: Grammar parsing for complex HDL constructs

Version 2.2.0 - Comprehensive Language Support

• NEW: Hack Binary support (.hack files) for machine code
• NEW: XML support (.xml files) for compiler output
• IMPROVED: Enhanced Hack Assembly highlighting and parsing
• IMPROVED: Better predefined symbol recognition
• IMPROVED: Negative constant support in assembly
• IMPROVED: Enhanced code outline for all languages
• IMPROVED: Better bracket matching across all file types

Installation

Prerequisites

• Zed Editor (latest version recommended)
• Rust installed via rustup (required for grammar compilation)

Install Rust (if needed)

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

Install Extension

1. Install as dev extension:

   • In Zed: Cmd+Shift+P → zed: install dev extension
   • Select the nand2tetris-zed directory

2. Test the extension:

   • Open any .hdl, .jack, .asm, .vm, .tst, .cmp, or .out files
   • Verify syntax highlighting appears

Supported File Types

• .hdl files - HDL (Hardware Description Language)
• .jack files - Jack programming language
• .asm files - Hack Assembly language
• .hack files - Hack Binary machine code
• .vm files - VM (Virtual Machine) language
• .tst files - Test scripts for simulation and testing
• .cmp files - Compare files (expected test outputs)
• .out files - Output files (actual test results)
• .xml files - XML compiler output files

Example Files

HDL Example (And.hdl)

/**
 * And gate:
 * out = 1 if (a == 1 and b == 1)
 *       0 otherwise
 */
CHIP And {
    IN a, b;
    OUT out;

    PARTS:
    Nand(a=a, b=b, out=nandOut);
    Not(in=nandOut, out=out);
}

Jack Example (Math.jack)

class Math {
    static Array twoToThe;
    
    /** Initializes the library. */
    function void init() {
        var int i;
        let twoToThe = Array.new(16);
        let twoToThe[0] = 1;
        let i = 1;
        while (i < 16) {
            let twoToThe[i] = twoToThe[i-1] + twoToThe[i-1];
            let i = i + 1;
        }
        return;
    }
    
    function int multiply(int x, int y) {
        var int sum, shiftedX;
        let sum = 0;
        let shiftedX = x;
        // Implementation details...
        return sum;
    }
}

Hack Assembly Example (Add.asm)

// Computes R0 = 2 + 3
@2
D=A
@3
D=D+A
@0
M=D

// Loop example with labels
@i
M=1
(LOOP)
    @i
    D=M
    @10
    D=D-A
    @END
    D;JGT
    
    @i
    M=M+1
    @LOOP
    0;JMP
(END)
    @END
    0;JMP

VM Language Example (SimpleAdd.vm)

// Stack arithmetic operations
push constant 7
push constant 8
add

// Memory operations
push local 0
push local 1
add
pop local 2

// Function definition
function Math.multiply 2
    push constant 0
    pop local 0
    
    label LOOP
    push local 1
    push constant 0
    eq
    if-goto END
    
    push local 0
    push argument 0
    add
    pop local 0
    
    goto LOOP
    
    label END
    push local 0
    return

Test Script Example (CPU.tst)

load CPU.hdl,
output-file CPU.out,
compare-to CPU.cmp,

output-list time%S1.3.1 instruction%B0.16.0 pc%D0.5.0;

set instruction %B0011000000111001, // @12345
tick, output, tock, output;

set instruction %B1110110000010000, // D=A
tick, output, tock, output;

repeat 10 {
    ticktock;
}

output;

Compare File Example (And.cmp)

| a | b |out|
| 0 | 0 | 0 |
| 0 | 1 | 0 |
| 1 | 0 | 0 |
| 1 | 1 | 1 |

Grammar Sources and Credits

This extension uses the following Tree-sitter grammars:

HDL Grammar

• Source: tree-sitter-hdl
• Author: Quan Tong (@quantonganh)
• License: MIT

Jack Grammar

• Source: tree-sitter-jack
• Author: nverno (@nverno)
• License: GPL-3.0-or-later

Hack Assembly Grammar

• Source: Custom tree-sitter grammar (included in this extension)
• License: MIT

VM Language Grammar

• Source: Custom tree-sitter grammar (included in this extension)
• License: MIT

Test Script Grammar

• Source: Custom tree-sitter grammar (included in this extension)
• License: MIT

Compare/Output File Grammar

• Source: Custom tree-sitter grammar (included in this extension)
• License: MIT

Nand2Tetris Course

This extension supports the languages from:

• Course: "The Elements of Computing Systems" (nand2tetris)
• Authors: Noam Nisan and Shimon Schocken
• Website: nand2tetris.org
• Book: "The Elements of Computing Systems: Building a Modern Computer from First Principles"

Language Features

Syntax Highlighting

All languages support comprehensive syntax highlighting with proper categorization of:

• Keywords and built-in types
• Identifiers and variables
• Numbers and literals (including binary values)
• Comments and documentation
• Operators and punctuation
• String and character literals
• Memory references and registers
• Labels and function names

Code Structure

• HDL: Shows chip declarations, input/output pins, and part instantiations
• Jack: Shows class structure, methods, functions, and field declarations
• Hack Assembly: Shows labels, A-instructions, and C-instructions
• VM: Shows function declarations, labels, and command structure
• Test Scripts: Shows test blocks, repeat/while loops, and file operations
• Compare/Output: Shows tabular data structure with headers and values

Editor Integration

• Bracket matching and auto-closing for {}, (), and []
• Smart indentation based on language structure
• Comment toggling with standard shortcuts (Cmd+/ or Ctrl+/)
• Code outline in the sidebar showing:
  • HDL: Chip structures
  • Jack: Class methods and fields
  • Assembly: Labels and major sections
  • VM: Functions and labels
  • Test Scripts: Test blocks and file operations
  • Compare/Output: Table structure

Project Structure

This extension includes custom tree-sitter grammars for maximum compatibility:

nand2tetris-zed/
├── extension.toml              # Extension configuration
├── README.md                   # This file
├── examples/                   # Example files for testing
│   ├── test.asm               # Hack Assembly example
│   ├── test.vm                # VM language example
│   ├── test.tst               # Test script example
│   └── test.cmp               # Compare file example
├── languages/                  # Language configurations
│   ├── hdl/                   # HDL language config
│   ├── jack/                  # Jack language config
│   ├── hack-assembly/         # Assembly language config
│   ├── vm/                    # VM language config
│   ├── test-script/           # Test script config
│   └── compare-output/        # Compare/Output config
└── grammars/                   # Tree-sitter grammars
    ├── hdl/                   # External HDL grammar
    ├── jack/                  # External Jack grammar
    ├── hack-assembly/         # Custom Assembly grammar
    ├── vm/                    # Custom VM grammar
    ├── test-script/           # Custom Test Script grammar
    └── compare-output/        # Custom Compare/Output grammar

Development

Grammar Development

The custom grammars are built with tree-sitter and include:

• grammar.js - Grammar definition
• src/parser.c - Generated parser
• queries/highlights.scm - Syntax highlighting queries
• bindings/rust/ - Rust language bindings
• Full tree-sitter package configuration

Building Grammars

To rebuild the grammars (requires tree-sitter-cli):

cd grammars/hack-assembly
tree-sitter generate
tree-sitter test

cd ../vm
tree-sitter generate
tree-sitter test

cd ../test-script
tree-sitter generate
tree-sitter test

cd ../compare-output
tree-sitter generate
tree-sitter test

Troubleshooting

No syntax highlighting appears

1. Check file extension: Ensure files have the correct extensions (.hdl, .jack, .asm, .vm, .tst, .cmp, .out) (lowercase)
2. Check Zed logs: Cmd+Shift+P → zed: open log → look for extension errors
3. Verify Rust installation: Run rustc --version (must be installed via rustup)
4. Restart Zed: Close and reopen Zed completely
5. Try manual language selection: Cmd+Shift+P → editor: select language → choose the appropriate language

Grammar compilation fails

1. Ensure Rust is from rustup:

   rustup --version
   rustc --version
   

2. Reinstall if needed:

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   

Extension loading issues

1. Check extension path: Make sure you're selecting the root nand2tetris-zed directory
2. Verify file structure: Ensure all required files are present
3. Check logs: Look for specific error messages in Zed logs

Expected Results

When the extension is working correctly, you should see:

• Colorized syntax for all supported file types (HDL, Jack, Assembly, VM, Test Scripts, Compare/Output)
• Keywords highlighted in one color, types in another
• Variables, functions, and properties with distinct colors
• Memory references and registers properly highlighted
• Binary values and numbers with appropriate colors
• Working bracket matching for all bracket types
• Code outline in the sidebar showing language-appropriate structure
• Comment toggling with Cmd+/ or Ctrl+/
• Smart indentation when typing

Use Cases

This extension is perfect for:

• Students taking the nand2tetris course
• Educators teaching computer architecture and systems programming
• Developers exploring low-level computing concepts
• Anyone interested in understanding how computers work from first principles

The extension supports all phases of the nand2tetris course:

• Projects 1-3: HDL development for logic gates, ALU, and memory
• Project 4: Assembly language programming
• Project 5: Computer architecture (with assembly testing)
• Project 6: Assembler development
• Projects 7-8: VM implementation and stack arithmetic
• Projects 9-11: High-level language (Jack) and compiler development
• Project 12: Operating system development

Contributing

Contributions are welcome! Please feel free to:

• Report bugs or issues
• Suggest new features
• Improve documentation
• Submit pull requests

License and Attribution

This extension is provided for educational use with the nand2tetris course materials.

Extension License

This Zed extension code is available under the MIT License.

Grammar Licenses

• HDL Grammar: MIT License (see tree-sitter-hdl)
• Jack Grammar: GPL-3.0-or-later (see tree-sitter-jack)
• Custom Grammars: MIT License (Hack Assembly, VM, Test Script, Compare/Output)

Acknowledgments

• Quan Tong for creating the HDL Tree-sitter grammar
• nverno for creating the Jack Tree-sitter grammar
• Noam Nisan and Shimon Schocken for the nand2tetris course and language specifications
• The Zed team for the excellent extension API and Tree-sitter integration
• The tree-sitter community for the parsing framework

---

Happy computing from first principles! 🎓✨

For more information about the nand2tetris course, visit nand2tetris.org.