doomemacs/modules/tools/tree-sitter

tools/tree-sitter

• Description
  • Maintainers
  • Module Flags
  • Plugins
• Prerequisites
• Features
  • Language support
  • Text Objects
  • Goto certain nodes
• Configuration
  • Disable text objects for certain modes
  • Adding your own text objects
  • Disabling highlighting for certain modes
• Troubleshooting
  • (error "Bad bounding indices: 0, 1")
  • No 'TEXTOBJ' text object found

Description

This module adds tree-sitter support to doom:

Tree sitter is a parser generator tool and an incremental parsing library. It can build a concrete syntax tree for a source file and efficiently update the syntax tree as the source file is edited. This allows for features of the editor to become syntax aware.

It includes:

• Better syntax highlighting of supported languages
• Structural text objects to manipulate functions statements and other code structures like any other text object

Currently this module does not support M1 macbooks due to grammars being built for x86

Maintainers

• @jeetelongname

Module Flags

This module provides no flags.

Plugins

• tree-sitter
• tree-sitter-langs
• evil-textobj-tree-sitter* (:editor evil +everywhere)

Prerequisites

This module has no prerequisites. but if you are using an M1 mac (or a system that's is not using an X86 instruction set) then you will not be able to use this module for the moment, functions are being put in place for this use case but they are still being worked on.

Features

Language support

Currently Emacs tree sitter has got parsers for these languages with syntax highlighting support for these languages as well as typescript-tsx-mode

Text Objects

Not all language support all text objects (yet). Here is a table of the text objects languages support Note: only languages with parser's in emacs have text object support currently. Currently text objects are bound to:

key	text object
a	parameter list
f	function definition
F	function call
C	class
c	comment
i	conditional
l	loop

They are used in a container context (not vf but vaf or vif)

Goto certain nodes

you can also jump to the next / previous node type in a buffer by using [g or ]g respectfully, the following key will correspond to the text object you want to jump to

Configuration

Disable text objects for certain modes

If you wish to disable tree sitter text objects then you can just remove +tree-sitter-keys-mode from the language mode hook, for example if we did not want it for ruby we would use this snippet

(remove-hook! 'ruby-mode-hook #'+tree-sitter-keys-mode)

Adding your own text objects

If you wish to add your own custom text objects then you need to bind them and add them to the +tree-sitter-{inner, outer}-text-objects-map for example:

(map! (:map +tree-sitter-outer-text-objects-map
       "m" (evil-textobj-tree-sitter-get-textobj "import"
             '((python-mode . [(import_statement) @import])
               (rust-mode . [(use_declaration) @import])))))

Disabling highlighting for certain modes

If you want to disable highlighting by default you can add a

(after! MODE-PACKAGE
  (tree-sitter-hl-mode -1))

If you only want it for certain modes then

(remove-hook! 'tree-sitter-after-on-hook #'tree-sitter-hl-mode)

(add-hook! 'MAJOR-MODE-HOOK #'tree-sitter-hl-mode)

Troubleshooting

(error "Bad bounding indices: 0, 1")

This means that the text object does not have the underlying query needed, this can be fixed by either adding in a custom query (which would override the current key bound.) or contributing upstream!

No 'TEXTOBJ' text object found

the main reason for this is the underlying text object using the #make-range! predicate, which at the moment is not implemented in emacs tree sitter (see this issue on evil-textobj-tree-sitter).

the only way around it is to rewrite the query to not use #make-range! or to implement that predicate the elisp tree sitter core