gvol / elisp-tree-sitter

Tree-sitter bindings for Emacs Lisp

ELisp Tree-sitter

This is an Emacs Lisp binding for tree-sitter, an incremental parsing library. It requires Emacs 25.1 or above, built with dynamic module support.

It aims to be the foundation for a new breed of Emacs packages that understand code structurally. For example:

• Faster, fine-grained code highlighting.
• More flexible code folding.
• Structural editing (like Paredit, or even better) for non-Lisp code.
• More informative indexing for imenu.

The author of tree-sitter articulated its merits a lot better in this Strange Loop talk.

Installation

See the installation section in the documentation.

If you want to hack on emacs-tree-sitter itself, see the next section instead.

Setup for Development

Note: On Windows, use Powershell instead of Bash or cmd.exe.

• Clone this repo with the --recursive flag.
• Add 3 of its directories to load-path: core/, lisp/ and langs/.
• Install cask.
• Run bin/setup.

If you want to hack on the high-level features (in Lisp) only:

• Make changes to the .el files.
• Add tests to tree-sitter-tests.el and run them with bin/test.

If you want to build additional (or all) grammars from source, or work on the core dynamic module, see the next 2 sections.

Building grammars from source

Note: If you are only interested in building the grammar binaries, not the dynamic module, check out tree-sitter-langs.

• Install NodeJS. It is needed to generate the grammar code from the JavaScript DSL. The recommended tool to manage NodeJS is volta.
• Install tree-sitter CLI tool: (Its binary can also be downloaded directly from GitHub.) Note: version 0.20+ cannot be used, as they introduced a breaking change in binary storage location.

  # For yarn user
  yarn global add tree-sitter-cli@0.19.3
  
  # For npm user
  npm install -g tree-sitter-cli@0.19.3

• Run langs/script/compile. For example:

  langs/script/compile rust

Working on the dynamic module

• Install the Rust toolchain.
• Install clang, to generate the raw Rust binding for emacs-module.h. On Windows, set LIBCLANG_PATH as well. For example:

  $env:LIBCLANG_PATH = "$(scoop prefix llvm)\bin"

• Build:

  bin/build

• Test:

  bin/test

• Continuously rebuild and test on change (requires cargo-watch):

  bin/test watch

To test against a different version of Emacs, set the environment variable EMACS (e.g. EMACS=/snap/bin/emacs make test).

Alternative

Binding through C instead of Rust: https://github.com/karlotness/tree-sitter.el

Contribution

Contributions are welcomed. Please take a look at the issue list for ideas, or create a new issue to describe any idea you have for improvement.

For language-specific issues/features, please check out tree-sitter-langs instead.

Show respect and empathy towards others. Both technical empathy and general empathy are highly valued.