tree-sitter-clojure

Status

tree-sitter-clojure has been:

• Tested in various ways
• Used in some ways
• Scoped for better behavior
• Brought about through cooperation

Prerequisites

Unfortunately, the short of it is that it may be a bit complicated depending on what you want to do.

• If you don't use any of the wasm-related functionality (e.g. previewing parse results in your web browser or you want to build a .wasm file for use in a plugin or extension), you probably just need:

  • an appropriate version of node (I've tested with various versions >= 12, 14) and
  • other typical development-related bits (e.g. git, appropriate c compiler, etc.)

• If you want wasm-related functionality, you get to have fun figuring out which version of emsdk currently works with tree-sitter. At the time of this writing, this file indicates a version that might be appropriate. That may depend on precisely what the versions of other bits (e.g. tree-sitter-cli, web-tree-sitter, etc.) might be though, so if something doesn't work right away, you might consider trying different versions that have been recorded.

Note that there may be an upside to using emsdk though -- it may figure out and arrange for an appropriate version of node, making a separate installation of node unnecessary. I don't use such a setup on a day-to-day basis, but it did work for me at least once.

Fine Print

• The instructions below assume emsdk has been installed, but emcc (tool that can be used to compile to wasm) is not necessarily on one's PATH. If an appropriate emcc is on one's PATH (e.g. emscripten installed via homebrew), the emsdk steps (e.g. source ~/src/emsdk/emsdk_env.sh) below may be ignored.

• node-gyp (tool for compiling native addon modules for Node.js) may fail on machines upgraded to macos Catalina. This document may help cope with such a situation.

Initial Setup

Suppose typical development sources are stored under ~/src.

# clone repository
cd ~/src
git clone https://github.com/sogaiu/tree-sitter-clojure
cd tree-sitter-clojure

# ensure tree-sitter-cli is avaliable as a dev dependency
npm install --save-dev tree-sitter-cli

# create `src` and populate with tree-sitter `.c` goodness
npx tree-sitter generate

# populate `node_modules` with dependencies
npm install

# create `build` and populate appropriately
npx node-gyp configure

# create `build/Release` and build `tree_sitter_clojure_binding.node`
npx node-gyp rebuild

Grammar Development

Hack on grammar.

# edit grammar.js using some editor

# rebuild tree-sitter stuff
npx tree-sitter generate && \
npx node-gyp rebuild

Parse individual files.

# create and populate sample code file for parsing named `sample.clj`

# parse sample file
npx tree-sitter parse sample.clj

# if output has errors, figure out what's wrong

Interactively test in the browser (requires emsdk).

# prepare emsdk (specifically emcc) for building .wasm
source ~/src/emsdk/emsdk_env.sh

# build .wasm bits and invoke web-ui for interactive testing
npx tree-sitter build-wasm && \
npx tree-sitter web-ui

# in appropriate browser window, paste code in left pane

# examine results in right pane -- can even click on nodes

# if output has errors, figure out what's wrong

Measure Performance

# single measurement
npx tree-sitter parse --time sample.clj

# mutliple measurements with `multitime`
multitime -n10 -s1 npx tree-sitter parse --time --quiet sample.clj

Build .wasm

Assuming emsdk is installed appropriately under ~/src/emsdk.

# prepare emsdk (specifically emcc) for use
source ~/src/emsdk/emsdk_env.sh

# create `tree-sitter-clojure.wasm`
npx tree-sitter build-wasm

Resources

• Guide to your first Tree-sitter grammar
• sublime-clojure
• syntax-highlighter
• tree-sitter
• tree-sitter-clojure.oakmac
• tree-sitter-clojure.SergeevPavel
• tree-sitter-clojure.Tavistock
• vscode-tree-sitter
• web-tree-sitter API

Acknowledgments

Please see the credits.