NonGNU-devel ELPA - clojure-ts-mode

clojure-ts-mode

Description
Major mode for Clojure code
Latest
clojure-ts-mode-0.2.2.0.20240229.201549.tar (.sig), 2024-Feb-29, 120 KiB
Maintainer
Danny Freeman <danny@dfreeman.email>
Website
http://github.com/clojure-emacs/clojure-ts-mode
Browse ELPA's repository
CGit or Gitweb
Badge

To install this package from Emacs, use package-install or list-packages.

Full description

NonGNU ELPA MELPA Stable MELPA License GPL 3 Lint Status

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:

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

emacs-lisp (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

emacs-lisp (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

emacs-lisp (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-:):

emacs-lisp (treesit-available-p)

Install clojure-ts-mode

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

emacs-lisp (package-install 'clojure-ts-mode)

package-vc

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

emacs-lisp (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.

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

emacs-lisp (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

bash 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

bash 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:

emacs-lisp (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.

emacs-lisp (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.

emacs-lisp ((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:

emacs-lisp (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.

Old versions

clojure-ts-mode-0.2.2.0.20240219.200709.tar.lz2024-Feb-1925.6 KiB
clojure-ts-mode-0.2.2.0.20240216.132330.tar.lz2024-Feb-1625.6 KiB
clojure-ts-mode-0.2.0.0.20240215.54347.tar.lz2024-Feb-1525.6 KiB
clojure-ts-mode-0.2.0.0.20240214.85218.tar.lz2024-Feb-1425.6 KiB
clojure-ts-mode-0.2.0.0.20240211.191755.tar.lz2024-Feb-1125.0 KiB
clojure-ts-mode-0.2.0.0.20240207.191206.tar.lz2024-Feb-0724.7 KiB
clojure-ts-mode-0.2.0.0.20230924.232019.tar.lz2023-Sep-2524.6 KiB
clojure-ts-mode-0.1.5.0.20230924.94650.tar.lz2023-Sep-2424.3 KiB
clojure-ts-mode-0.1.5.0.20230830.112950.tar.lz2023-Aug-3020.4 KiB
clojure-ts-mode-0.1.4.0.20230829.171042.tar.lz2023-Aug-3020.4 KiB

News

Changelog

main (unreleased)

  • [#38]: Add support for in-ns forms in clojure-ts-find-ns.

0.2.2 (2024-02-16)

  • [#37]: Fix derived modes broken with [#36].

0.2.1 (2024-02-14)

  • [#36]: Rename all derived mode vars to match the package prefix.
    • clojurescript-ts-mode -> clojure-ts-clojurescript-mode
    • clojurec-ts-mode -> clojure-ts-clojurec-mode
    • clojure-dart-ts-mode -> clojure-ts-clojuredart-mode
    • clojure-jank-ts-mode -> clojure-ts-jank-mode
  • [#30]: Add custom option clojure-ts-toplevel-inside-comment-form as an equivalent to clojure-toplevel-inside-comment-form in clojure-mode.
  • [#32]: Change behavior of beginning-of-defun and end-of-defun to consider all Clojure sexps as defuns.

0.2.0

0.1.5

0.1.4

0.1.3

  • Add custom option for highlighting comment macro body forms as comments. ae3790adc0fc40ad905b8c30b152122991592a4e
    • Defaults to OFF, highlighting comment body forms like any other expressions. ... ...