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

#+TITLE:   tools/tree-sitter
#+DATE:    August 17, 2021
#+SINCE:   3.0.0
#+STARTUP: inlineimages nofold

* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
  - [[#maintainers][Maintainers]]
  - [[#module-flags][Module Flags]]
  - [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
  - [[#language-support][Language support]]
  - [[#text-objects][Text Objects]]
- [[#configuration][Configuration]]
  - [[#disable-text-objects-for-certain-modes][Disable text objects for certain modes]]
  - [[#adding-your-own-text-objects][Adding your own text objects]]
  - [[#disabling-highlighting-for-certain-modes][Disabling highlighting for certain modes]]
- [[#troubleshooting][Troubleshooting]]
  - [[#error-bad-bounding-indices-0-1][=(error "Bad bounding indices: 0, 1")=]]

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

#+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

*Currently this module does not support M1 macbooks due to grammars being built for x86*

** Maintainers
- @jeetelongname

** Module Flags
This module provides no flags.

** Plugins
+ [[https://github.com/emacs-tree-sitter/elisp-tree-sitter][tree-sitter]]
+ [[https://github.com/emacs-tree-sitter/tree-sitter-langs][tree-sitter-langs]]
+ [[https://github.com/meain/evil-textobj-tree-sitter][evil-textobj-tree-sitter]]* (=:editor evil +everywhere=)

* Prerequisites
This module has no prerequisites. but if you are using an M1 mac (or a system
that's is not using an X86 instruction set) then you will not be able to use this
module for the moment, functions are being put in place for this use case but
they are still being worked on.

* Features
** Language support
Currently Emacs tree sitter has got [[https://github.com/emacs-tree-sitter/tree-sitter-langs/tree/master/repos][parsers for these languages]] with syntax
highlighting support for [[https://emacs-tree-sitter.github.io/syntax-highlighting/][these languages]].

** Text Objects
Not all language support all text objects (yet). [[https://github.com/nvim-treesitter/nvim-treesitter-textobjects#built-in-textobjects][Here is a table of the text
objects languages support]]
Note: only languages with parser's 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             |
| =i= | conditional         |
| =l= | loop                |

They are used in a container context (not =vf= but =vaf= or =vif=)

* Configuration
** Disable text objects for certain modes
If you wish to disable tree sitter text objects then you can just remove
=+tree-sitter-keys-mode= from the language mode hook, for example if we did not
want it for ruby we would use this snippet
#+begin_src emacs-lisp
(remove-hook! 'ruby-mode-hook #'+tree-sitter-keys-mode)
#+end_src

** Adding your own text objects
If you wish to [[https://github.com/meain/evil-textobj-tree-sitter#custom-textobjects][add your own custom text objects]] then you need to bind them and
add them to the ~+tree-sitter-{inner, outer}-text-objects-map~
for example:
#+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

** Disabling highlighting for certain modes
If you want to disable highlighting by default you can add a 
#+begin_src emacs-lisp
(after! MODE-PACKAGE
  (tree-sitter-hl-mode -1))
#+end_src

If you only want it for certain modes then
#+begin_src emacs-lisp
(remove-hook! 'tree-sitter-after-on-hook #'tree-sitter-hl-mode)

(add-hook! 'MAJOR-MODE-HOOK #'tree-sitter-hl-mode)
#+end_src

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