bd0bee92cc
BREAKING CHANGE: This commit removes a number of core packages and features from this module and only replaces a handful of them, so that we can lean more on LSP and tree-sitter. To be specific: - We used to rely on `rjsx-mode` (derived from js2-mode) for total JS/JSX support (though imperfect; Emacs was starved for options at the time). This has now been replaced with `js-ts-mode` (built-in after Emacs 29), falling back to `js-mode` (very rudimentary, but a decent fallback). - This also meant the removal of `js2-mode`, which `skewer-mode`, `js2-refactor`, and `xref-js2` depended on, so those were removed too, and have *somewhat* been replaced with LSP integration (offers jump-to-definition/references and *some* refactoring actions, but no replacement for skewer's functionality). - Typescript support no longer relies on the jury-rigged, web-mode-derived major mode (because TSX support in the upstream `typescript-mode` isn't great). We now use `typescript-ts-mode` (built-in into Emacs 29.1+), falling back to `typescript-mode`. - JSX/TSX support now *requires* tree-sitter (and Emacs 29.1+), where `tsx-ts-mode` is available and outshines all the alternatives (at the time of writing). Due to the absolute chaos that is webdev, this module sacrifices some of the graceful-degradation I've implemented for other modules and creates a hard requirement on tree-sitter and Emacs 29.1+ for JSX/TSX. It still tries to degrade gracefully for plain JS and TS, but the module's doctor and docs will actively recommend tree-sitter. Close: #5278 Fix: #6172 Fix: #7042 Close: #8447 Co-authored-by: ribaricplusplus <ribaricplusplus@users.noreply.github.com>
: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-indent
- 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?