doomemacs/modules/tools/tree-sitter/README.org

#+title:    :tools tree-sitter
#+subtitle: Syntax and parsing, sitting in a tree...
#+created:  August 17, 2021
#+since:    22.06.0 (#5401)

* Description :unfold:
This module adds [[https://tree-sitter.github.io/tree-sitter/][tree-sitter]] support to Doom Emacs.

#+begin_quote
 💬 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.
#+end_quote

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
- [[doom-user:][@jeetelongname]]

[[doom-contrib-maintainer:][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 section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./

* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][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
#+begin_quote
 🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote

** Language support
Currently Emacs tree sitter has [[https://github.com/emacs-tree-sitter/tree-sitter-langs/tree/master/repos][parsers for these languages]], and syntax
highlighting support for [[https://github.com/emacs-tree-sitter/tree-sitter-langs/tree/master/queries][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). [[https://github.com/nvim-treesitter/nvim-treesitter-textobjects#built-in-textobjects][Here is a table of the text
object languages support]].

#+begin_quote
 🚧 Only languages with parsers in Emacs have text object support at the moment.
#+end_quote

Currently text objects are bound to:
| key | text object         |
|-----+---------------------|
| [[kbd:][A]]   | parameter list      |
| [[kbd:][f]]   | function definition |
| [[kbd:][F]]   | function call       |
| [[kbd:][C]]   | class               |
| [[kbd:][c]]   | comment             |
| [[kbd:][v]]   | conditional         |
| [[kbd:][l]]   | loop                |

They are used in a container context (not [[kbd:][vf]], but [[kbd:][vaf]] or [[kbd:][vif]]).

** Goto certain nodes
To jump to the next/previous node, type in a buffer by using [[kbd:][[g]] or [[kbd:][]g]]
respectfully, the following key will correspond to the text object you want to
jump to.

Currently keys are bound to:
| key | text object    |
|-----+----------------|
| [[kbd:][a]]   | parameter list |
| [[kbd:][f]]   | function       |
| [[kbd:][F]]   | function call  |
| [[kbd:][c]]   | comment        |
| [[kbd:][C]]   | class          |
| [[kbd:][v]]   | conditional    |
| [[kbd:][l]]   | loop           |

* TODO Configuration
#+begin_quote
 🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote

** 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:
#+begin_src emacs-lisp
(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")))
#+end_src

** Add your own text objects
To [[https://github.com/meain/evil-textobj-tree-sitter#custom-textobjects][add your own custom text objects]], bind them to ~+tree-sitter-{inner,
outer}-text-objects-map~:
#+begin_src emacs-lisp
(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]))))
#+end_src

** 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*.
#+begin_src emacs-lisp
(setq +tree-sitter-hl-enabled-modes '(python-mode go-mode))
#+end_src

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.
#+begin_src emacs-lisp
(setq +tree-sitter-hl-enabled-modes '(not web-mode typescript-tsx-mode))
#+end_src

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
[[doom-report:][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 [[https://github.com/nvim-treesitter/nvim-treesitter-textobjects/][contributing upstream!]]

* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]

* TODO Appendix
#+begin_quote
 🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote