jack-format ⚡

An opinionated, fast, and robust code formatter for the Jack programming language from the popular Nand2Tetris course (Projects 9, 10, and 11).

Standard Java/C formatters (like google-java-format or clang-format) fail or corrupt Jack programs due to Jack's unique grammar (function, method, constructor, var int x;, let x = ..., and do SubroutineCall;). jack-format solves this by providing a dedicated parser and formatter designed specifically for Jack.

Features

• 🚀 Zero external dependencies: Pure Python standard library.
• 📐 Standard Nand2Tetris indentation: Clean 4-space indentation for classes, subroutines, loops, and branching.
• 🛡️ Safe & non-destructive: Preserves string literals, line comments (//), block comments (/* ... */), and doc comments (/** ... */).
• 🔄 In-place formatting: Reformat individual files or entire project directories recursively with -i.
• 🔍 CI/CD Check Mode: Returns exit code 1 if unformatted code is detected (--check), perfect for grading scripts and CI pipelines.
• 🔌 Universal Editor Integration: Works seamlessly with Neovim, VS Code, Vim, and terminal workflows.

Installation

pip install jack-format

Verify installation:

jack-format --version

Usage

1. Format a single file (prints to stdout)

jack-format Main.jack

2. Format files in-place (-i)

jack-format -i Main.jack Square.jack

3. Format an entire project directory recursively

jack-format -i src/

4. Format from standard input (stdin)

cat Main.jack | jack-format

5. Check if code is properly formatted (CI mode)

Exits with code 0 if formatted, or 1 if any file needs formatting:

jack-format --check *.jack

6. View unified diff of changes

jack-format --diff Main.jack

7. Custom indentation size (e.g. 2 spaces instead of 4)

jack-format -s 2 -i Main.jack

Editor Integration

Neovim (conform.nvim)

Add jack-format to your conform.nvim configuration:

require("conform").setup({
  formatters_by_ft = {
    jack = { "jack_format" },
  },
  formatters = {
    jack_format = {
      command = "jack-format",
      stdin = true,
    },
  },
})

VS Code

You can use the popular Run on Save extension or configure a custom task:

Add to your .vscode/settings.json:

{
  "emeraldwalk.runonsave": {
    "commands": [
      {
        "match": "\\.jack$",
        "cmd": "jack-format -i ${file}"
      }
    ]
  }
}

Vim

Add this to your .vimrc to format on <leader>f or before saving:

autocmd FileType jack setlocal equalprg=jack-format

Example

Before

class Main {
function void main() {
var int x;
let x=5;
if (x>0){
do Output.printInt(x);
}else{
do Output.printString("zero");
}
return;
}
}

After (jack-format)

class Main {
    function void main() {
        var int x;
        let x = 5;
        if (x > 0) {
            do Output.printInt(x);
        } else {
            do Output.printString("zero");
        }
        return;
    }
}

Development & Testing

Run unit tests:

python3 -m unittest discover -s tests

Build distribution packages:

python3 -m pip install build twine
python3 -m build
twine check dist/*

License

MIT License. See LICENSE for details.