Awesome
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 ofclojure-mode
andcljfmt
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 withclojure-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:
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 toclojure-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 inclojure-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?
Yes! Preliminary support for clojure-ts-mode
was released in CIDER 1.14. Make sure to grab the latest CIDER from MELPA/GitHub. Note that clojure-mode
is still needed for some APIs that haven't yet been ported to clojure-ts-mode
.
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
?
Currently, there is an open PR adding support for inf-clojure.
License
Copyright © 2022-2024 Danny Freeman and contributors.
Distributed under the GNU General Public License; type <kbd>C-h C-c</kbd> to view it.