:tools tree-sitter
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
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
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
(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?