Clojure Tree-Sitter Mode

clojure-ts-mode is an Emacs major mode that provides font-lock (syntax highlighting), indentation, and navigation support for the Clojure(Script) programming language, powered by the tree-sitter-clojure tree-sitter grammar.

Configuration

To see a list of available configuration options do M-x customize-group <RET> clojure-ts.

Most configuration changes will require reverting any active clojure-ts-mode buffers.

Indentation

clojure-ts-mode currently supports 2 different indentation strategies:

• semantic, the default, which tries to match the indentation of clojure-mode and cljfmt
• fixed, a simple indentation strategy outlined by Tonsky in a blog post

Set the var clojure-ts-indent-style to change it.

(setq clojure-ts-indent-style 'fixed)

Note: You can find this article comparing semantic and fixed indentation useful.

Font Locking

To highlight entire rich comment expression with the comment font face, set

(setq clojure-ts-comment-macro-font-lock-body t)

By default this is nil, so that anything within a comment expression is highlighted like regular clojure code.

Navigation and Evaluation

To make forms inside of (comment ...) forms appear as top-level forms for evaluation and navigation, set

(setq clojure-ts-toplevel-inside-comment-form t)

Rationale

clojure-mode has served us well for a very long time, but it suffers from a few long-standing problems, related to Emacs limitations baked into its design. The introduction of built-in support for Tree-sitter in Emacs 29 provides a natural opportunity to address many of them. Enter clojure-ts-mode.

Keep in mind that the transition to clojure-ts-mode won't happen overnight for several reasons:

• getting to feature parity with clojure-mode will take some time
• tools that depend on clojure-mode will need to be updated to work with clojure-ts-mode
• we still need to support users of older Emacs versions that don't support Tree-sitter

That's why clojure-ts-mode is being developed independently of clojure-mode and will one day replace it when the time is right. (e.g. 3 major Emacs version down the road, so circa Emacs 32)

You can read more about the vision for clojure-ts-mode here.

Current Status

This library is still under development. Breaking changes should be expected.

Installation

Emacs 29

This package requires Emacs 29 built with tree-sitter support from the emacs-29 branch.

If you decide to build Emacs from source there's some useful information on this in the Emacs repository:

• Emacs tree-sitter starter-guide
• Emacs install instructions.

To check if your Emacs supports tree sitter run the following (e.g. by using M-:):

(treesit-available-p)

Install clojure-ts-mode

clojure-ts-mode is available on MElPA and NonGNU ELPA. It can be installed with

(package-install 'clojure-ts-mode)

package-vc

Emacs 29 also includes package-vc-install, so you can run

(package-vc-install "https://github.com/clojure-emacs/clojure-ts-mode")

to install this package from source.

Manual installation

You can install it by cloning the repository and adding it to your load path.

git clone https://github.com/clojure-emacs/clojure-ts-mode.git

(add-to-list 'load-path "~/path/to/clojure-ts-mode/")

Once installed, evaluate clojure-ts-mode.el and you should be ready to go.

Install tree-sitter grammars

The compile tree-sitter clojure shared library must be available to Emacs. Additionally, the tree-sitter markdown_inline shared library will also be used for docstrings if available.

If you have git and a C compiler (cc) available on your system's PATH, then these steps should not be necessary. clojure-ts-mode will install the grammars when you first open a Clojure file and clojure-ts-ensure-grammars is set to t (the default).

If clojure-ts-mode fails to automatically install the grammar, you have the option to install it manually.

From your OS

Some distributions may package the tree-sitter-clojure grammar in their package repositories. If yours does you may be able to install tree-sitter-clojure with your system package manager.

If the version packaged by your OS is out of date, you may see errors in the *Messages* buffer or your clojure buffers will not have any syntax highlighting.

If this happens you should install the grammar manually with M-x treesit-install-language-grammar <RET> clojure and follow the prompts. Recommended values for these prompts can be seen in clojure-ts-grammar-recipes.

Compile From Source

If all else fails, you can attempt to download and compile manually. All you need is git and a C compiler (GCC works well).

To start, clone tree-sitter-clojure.

Then run the following code (depending on your OS) from the tree-sitter-clojure repository on your machine.

Linux

mkdir -p dist
cc -c -I./src src/parser.c -o "parser.o"
cc -fPIC -shared src/parser.o -o "dist/libtree-sitter-clojure.so"

macOS

mkdir -p dist
cc -c -I./src src/parser.c -o "parser.o"
cc -fPIC -shared src/parser.o -o "dist/libtree-sitter-clojure.dylib"

Windows

I don't know how to do this on Windows. Patches welcome!

Finally, in emacs

Then tell Emacs where to find the shared library by adding something like this to your init file:

(setq treesit-extra-load-path '( "~/path/to/tree-sitter-clojure/dist"))

OR you can move the libtree-sitter-clojure.so/libtree-sitter-clojure.dylib to a directory named tree-sitter under your user-emacs-directory (typically ~/.emacs.d on Unix systems).

Migrating to clojure-ts-mode

If you are migrating to clojure-ts-mode note that clojure-mode is still required for cider and clj-refactor packages to work properly.

After installing the package do the following.

• Check the value of clojure-mode-hook and copy all relevant hooks to clojure-ts-mode-hook.

(add-hook 'clojure-ts-mode-hook #'cider-mode)
(add-hook 'clojure-ts-mode-hook #'enable-paredit-mode)
(add-hook 'clojure-ts-mode-hook #'rainbow-delimiters-mode)
(add-hook 'clojure-ts-mode-hook #'clj-refactor-mode)

• Update .dir-locals.el in all of your Clojure projects to activate directory local variables in clojure-ts-mode.

((clojure-mode
  (cider-clojure-cli-aliases . ":test:repl"))
 (clojure-ts-mode
  (cider-clojure-cli-aliases . ":test:repl")))

Frequently Asked Questions

Does clojure-ts-mode work with CIDER?

Not yet out of the box, but that should change soon. Feel free to help out with the remaining work, so we can expedite the process.

Support for clojure-ts-mode has landed on the master branch of CIDER (and will be part of CIDER 1.14 when it's released). Make sure to grab the latest CIDER from MELPA/GitHub.

For now, when you take care of the keybindings for the CIDER commands you use and ensure cider-mode is enabled for clojure-ts-mode buffers in your config, most functionality should already work:

(add-hook 'clojure-ts-mode-hook #'cider-mode)

Check out this article for more details.

Does clojure-ts-mode work with inf-clojure?

Ditto.

License

Copyright © 2022-2024 Danny Freeman and contributors.

Distributed under the GNU General Public License; type C-h C-c to view it.