README.org

tools/tree-sitter

Table of Contents

• Description
  • Maintainers
  • Module Flags
  • Plugins
• Prerequisites
• Features
  • Language support
  • Text Objects
  • Goto certain nodes
• Configuration
  • Rebinding text objects
  • Adding your own text objects
  • Disabling highlighting for certain modes
• Troubleshooting
  • =(error “Bad bounding indices: 0, 1”)=

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.

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.

Features

Language support

Currently Emacs tree sitter has parsers for these languages, and syntax highlighting support for these languages as well as typescript-tsx-mode.

To enable tree sitter for individual languages, add the +tree-sitter flag. Check the module readme of your language for support.

Text Objects

Not all languages support all text objects (yet). Here is a table of the text object languages support.

Note: Only languages with parsers 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
v	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.

Currently keys are bound to:

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

Configuration

Rebinding text objects

Rebinding keys is the same as any other key, but do note that they need to be bound to the keymaps +tree-sitter-inner-text-object-map or +tree-sitter-outer-text-object-map.

(map! (:map +tree-sitter-outer-text-objects-map
       "f" nil
       "f" (evil-textobj-tree-sitter-get-textobj "call.inner")
       "F" nil
       "F" (evil-textobj-tree-sitter-get-textobj "function.inner"))
      (:map +tree-sitter-inner-text-objects-map
       "f" nil
       "f" (evil-textobj-tree-sitter-get-textobj "call.inner")
       "F" nil
       "F" (evil-textobj-tree-sitter-get-textobj "function.inner")))

Adding your own text objects

If you wish to add your own custom text objects then you need to bind them to +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 do:

(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!