doomemacs/modules/tools/tree-sitter

:tools tree-sitter

• Description
  • Maintainers
  • Module flags
  • Packages
  • Hacks
  • Changelog
• Installation
• Usage
  • Language support
  • Text Objects
  • Goto certain nodes
• Configuration
  • Rebind text objects
  • Add your own text objects
  • Configuring Tree sitter highlighting
• Troubleshooting
  • (error "Bad bounding indices: 0, 1")
• Frequently asked questions
• Appendix

Description   unfold

This module adds tree-sitter support to Doom Emacs.

💬 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

Become a maintainer?

Module flags

This module has no flags.

Packages

• doom-package:evil-textobj-tree-sitter if doom-module::editor evil +everywhere
• doom-package:tree-sitter
• doom-package:tree-sitter-langs

Hacks

No hacks documented for this module.

TODO Changelog

This module does not have a changelog yet.

Installation

Enable this module in your doom! block.

This module has no direct requirements, but some languages may have their own to fulfill before tree-sitter support works for them. Run $ doom doctor to find out what you're missing.

TODO Usage

🔨 This module's usage documentation is incomplete. Complete it?

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 support for specific languages, add the +tree-sitter flag to their respective Doom modules. 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.

🚧 Only languages with parsers in Emacs have text object support at the moment.

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

To 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

TODO Configuration

🔨 This module's configuration documentation is incomplete. Complete it?

Rebind text objects

Rebinding keys works the same as rebinding any other key, but text-object keys must be bound on one or both of the +tree-sitter-inner-text-object-map or +tree-sitter-outer-text-object-map keymaps:

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

Add your own text objects

To add your own custom text objects, bind them to +tree-sitter-{inner, outer}-text-objects-map:

(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]))))

Configuring Tree sitter highlighting

Highlighting is controlled by the variable +tree-sitter-hl-enabled-modes This list allows you to whitelist, blacklist, fully enable or fully disable tree-sitter highlighting for all major modes

To use highlighting in select modes add major-modes to +tree-sitter-hl-enabled-modes. This disables highlighting in all other modes. The symbol that should be used is the major mode symbol, not the package symbol.

(setq +tree-sitter-hl-enabled-modes '(python-mode go-mode))

If you want to disallow highlighting in certain modes then the car of +tree-sitter-hl-enabled-modes should be not. This enables highlighting in all modes except the ones disallowed.

(setq +tree-sitter-hl-enabled-modes '(not web-mode typescript-tsx-mode))

If +tree-sitter-hl-enabled-modes is set to nil or t it will fully disable or fully enable highlighting in every tree sitter enabled language respectively.

Troubleshooting

Report an issue?

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

Frequently asked questions

This module has no FAQs yet. Ask one?

TODO Appendix

🔨 This module has no appendix yet. Write one?