-
Notifications
You must be signed in to change notification settings - Fork 32
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add more configuration examples to README
- Loading branch information
Showing
1 changed file
with
94 additions
and
68 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,68 +1,94 @@ | ||
| #+TITLE: treesit-auto | ||
| #+AUTHOR: Robb Enzmann | ||
|
|
||
| Automatically pick between TreeSitter and default major modes in Emacs 29+. | ||
|
|
||
| * Installation | ||
|
|
||
| #+begin_src example | ||
| M-x package-vc-install RET https://github.com/renzmann/treesit-auto.git | ||
| #+end_src | ||
|
|
||
| Then, in your Emacs configuration file (=~/.emacs.d/init.el=), | ||
|
|
||
| #+begin_src emacs-lisp | ||
| (use-package treesit-auto | ||
| :demand t | ||
| :config | ||
| (treesit-auto-apply-remap)) | ||
| #+end_src | ||
|
|
||
| If you have modified =treesit-language-source-alist= through =setq=, then it is | ||
| recommended to put this =use-package= delcaration AFTER that =setq=. Also, if you | ||
| want =treesit-auto-apply-remap= to re-run after installing a grammar with | ||
| =treesit-install-language-grammar=, try advising the function with something like | ||
| this: | ||
|
|
||
| #+begin_src emacs-lisp | ||
| (advice-add 'treesit-install-language-grammar | ||
| :after (lambda (&rest _r) (treesit-auto-apply-remap))) | ||
| #+end_src | ||
|
|
||
| Once I learn how to publish to MELPA and ELPA, then I will update the | ||
| installation instructions accordingly. | ||
|
|
||
| * What this package does | ||
|
|
||
| Emacs 29, while featuring =treesit.el= and a convenient | ||
| =treesit-install-language-grammar=, [[https://archive.casouri.cc/note/2023/tree-sitter-in-emacs-29/index.html][will not feature an intelligent way to choose]] | ||
| between a default mode, such as =python-mode=, and it's tree-sitter enhanced | ||
| version, =python-ts-mode=, automatically. This package attempts to remedy that | ||
| by applying these rules: | ||
|
|
||
| *1. If the grammar is installed, then switch to the appropriate tree-sitter mode:* | ||
|
|
||
| In this case, assuming we open a Python buffer, and the [[https://github.com/tree-sitter/tree-sitter-python][Python tree-sitter | ||
| grammar]] is installed, then Emacs will use =python-ts-mode= instead of | ||
| =python-mode=. | ||
|
|
||
| *2. If the grammar is NOT installed, and the user has specified a specific mode | ||
| to use instead:* | ||
|
|
||
| This packages exposes a customizable variable =treesit-auto-fallback-alist= that you | ||
| may use to specify a specific mode to use instead of the tree-sitter mode, | ||
| should the grammar not be installed. For instance, if we apply this: | ||
|
|
||
| #+begin_src emacs-lisp | ||
| (add-to-list 'treesit-auto-fallback-alist '(toml-ts-mode . conf-toml-mode)) | ||
| #+end_src | ||
|
|
||
| Then, when the TOML grammar is missing, Emacs will use =conf-toml-mode=, instead | ||
| of trying to use =toml-mode=. | ||
|
|
||
| **3. If the grammar is NOT installed and the user has NOT specified a specific | ||
| mode to use AND an appropriately named base mode exists, switch to it** | ||
|
|
||
| This is the most general case. If, for example, the Go tree-sitter grammar is | ||
| not installed, but we have installed [[https://github.com/dominikh/go-mode.el][go-mode]], then Emacs will use that instead | ||
| of =go-ts-mode=, since they share the same =go-= prefix. | ||
| #+TITLE: treesit-auto | ||
| #+AUTHOR: Robb Enzmann | ||
|
|
||
| Automatically pick between TreeSitter and default major modes in Emacs 29+. | ||
|
|
||
| * Installation | ||
|
|
||
| #+begin_src example | ||
| M-x package-vc-install RET https://github.com/renzmann/treesit-auto.git | ||
| #+end_src | ||
|
|
||
| Then, in your Emacs configuration file (=~/.emacs.d/init.el=), | ||
|
|
||
| #+begin_src emacs-lisp | ||
| (use-package treesit-auto | ||
| :config | ||
| (treesit-auto-apply-remap)) | ||
| #+end_src | ||
|
|
||
| Once I learn how to publish to MELPA and ELPA, then I will update the | ||
| installation instructions accordingly. | ||
|
|
||
| * What this package does | ||
|
|
||
| Emacs 29, while featuring =treesit.el= and a convenient | ||
| =treesit-install-language-grammar=, [[https://archive.casouri.cc/note/2023/tree-sitter-in-emacs-29/index.html][will not feature an intelligent way to choose]] | ||
| between a default mode, such as =python-mode=, and it's tree-sitter enhanced | ||
| version, =python-ts-mode=, automatically. This package attempts to remedy that | ||
| by applying these rules: | ||
|
|
||
| *1. If the grammar is installed, then switch to the appropriate tree-sitter mode:* | ||
|
|
||
| In this case, assuming we open a Python buffer, and the [[https://github.com/tree-sitter/tree-sitter-python][Python tree-sitter | ||
| grammar]] is installed, then Emacs will use =python-ts-mode= instead of | ||
| =python-mode=. | ||
|
|
||
| *2. If the grammar is NOT installed, and the user has specified a specific mode | ||
| to use instead:* | ||
|
|
||
| This packages exposes a customizable variable =treesit-auto-fallback-alist= that you | ||
| may use to specify a specific mode to use instead of the tree-sitter mode, | ||
| should the grammar not be installed. For instance, if we apply this: | ||
|
|
||
| #+begin_src emacs-lisp | ||
| (add-to-list 'treesit-auto-fallback-alist '(toml-ts-mode . conf-toml-mode)) | ||
| #+end_src | ||
|
|
||
| Then, when the TOML grammar is missing, Emacs will use =conf-toml-mode=, instead | ||
| of trying to use =toml-mode=. | ||
|
|
||
| **3. If the grammar is NOT installed and the user has NOT specified a specific | ||
| mode to use AND an appropriately named base mode exists, switch to it** | ||
|
|
||
| This is the most general case. If, for example, the Go tree-sitter grammar is | ||
| not installed, but we have installed [[https://github.com/dominikh/go-mode.el][go-mode]], then Emacs will use that instead | ||
| of =go-ts-mode=, since they share the same =go-= prefix. | ||
|
|
||
| * Configuration | ||
|
|
||
| If you have modified =treesit-language-source-alist= through =setq=, then it is | ||
| recommended to put any configuration of this package AFTER that =setq=. | ||
|
|
||
| Not all default major modes make sense to bump up to a similar tree-sitter mode. | ||
| For example, when /I/ open a =.sh= file, my intent is nearly always to be using it | ||
| with Bash. This is not the case for everyone, though, so by default this | ||
| package will not replace =sh-mode= with =bash-ts-mode=. If you do want such a | ||
| remap, simply include a line like this before calling =treesit-auto-apply-remap=: | ||
|
|
||
| #+begin_src emacs-lisp | ||
| (add-to-list 'treesit-auto-fallback-alist '(bash-ts-mode . sh-mode)) | ||
| #+end_src | ||
|
|
||
| If you want =treesit-auto-apply-remap= to re-run after installing a grammar with | ||
| =treesit-install-language-grammar=, try advising the function with something like | ||
| this: | ||
|
|
||
| #+begin_src emacs-lisp | ||
| (advice-add 'treesit-install-language-grammar | ||
| :after (lambda (&rest _r) (treesit-auto-apply-remap))) | ||
| #+end_src | ||
|
|
||
| ** Full example | ||
|
|
||
| This is how I configure =treesit-auto= for my own personal use. | ||
|
|
||
| #+begin_src emacs-lisp | ||
| (use-package treesit-auto | ||
| :demand t | ||
| :config | ||
| (add-to-list 'treesit-auto-fallback-alist '(bash-ts-mode . sh-mode)) | ||
| (treesit-auto-apply-remap) | ||
| (advice-add 'treesit-install-language-grammar | ||
| :after (lambda (&rest _r) (treesit-auto-apply-remap)))) | ||
| #+end_src |