nand2tetris-zed/README.md

# 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)
```bash
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`)
```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`)
```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`)
```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`)
```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`)
```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](https://github.com/quantonganh/tree-sitter-hdl)
- **Author**: Quan Tong (@quantonganh)
- **License**: MIT

### Jack Grammar  
- **Source**: [tree-sitter-jack](https://github.com/nverno/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](https://www.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):
```bash
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**: 
   ```bash
   rustup --version
   rustc --version
   ```
2. **Reinstall if needed**:
   ```bash
   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](https://github.com/quantonganh/tree-sitter-hdl))
- **Jack Grammar**: GPL-3.0-or-later (see [tree-sitter-jack](https://github.com/nverno/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](https://www.nand2tetris.org).