#+TITLE: Tree-sitter Language Bundle for Emacs

#+BEGIN_HTML #+END_HTML

This is a convenient language bundle for the Emacs package [[https://github.com/emacs-tree-sitter/elisp-tree-sitter][tree-sitter]]. It serves as an interim distribution mechanism, until tree-sitter is widespread enough for language-specific major modes to incorporate its functionalities.

For each supported language, this package provides:

1. Pre-compiled grammar binaries for 3 major platforms: macOS, Linux and Windows, on x86_64. In the future, tree-sitter-langs may provide tooling for major modes to do this on their own.
2. An optional highlights.scm file that provides highlighting patterns. This is mainly intended for major modes that are not aware of tree-sitter. A language major mode that wants to use tree-sitter for syntax highlighting should instead provide the query patterns on its own, using the mechanisms defined by [[https://emacs-tree-sitter.github.io/syntax-highlighting/interface-for-modes/][tree-sitter-hl]].
3. Optional query patterns for other minor modes that provide high-level functionalities on top of tree-sitter, such as code folding, evil text objects... As with highlighting patterns, major modes that are directly aware of tree-sitter should provide the query patterns on their own.

** Highlighting Queries

Note: Highlighting styles are a mattter of taste.

Highlighting query patterns for a language are in the file queries//highlights.scm. Most of them are intentionally different from those from upstream repositories, which are more geared towards /GitHub's use cases/. We try to be more consistent with /Emacs's existing conventions/. (For some languages, this is WIP, so their patterns may look similar to upstream's.)

In general, try to follow what the docstrings of tree-sitter-hl-face: faces say. Most importantly:

• Definitions and uses should be differentiated:
  • @function vs. @function.call.
  • @method vs. @method.call.
  • @type.parameter vs. @type.argument.
• @variable and @variable.parameter should be applied only to declarations/definitions/bindings/mutations (/writes/), not usage (/reads/).
• Special faces should have high priority (placed earlier in the pattern list): @function.macro, @type.builtin, @variable.special.
• Patterns whose internals may be highlighted should have low priority (placed towards the end). Example: strings with interpolation.

*** Mode-specific highlighting Some languages are associated with multiple major modes. Mode-specific highlighting patterns are provided by the files queries//highlights..scm. These are combined with the base highlighting patterns in queries//highlights.scm, but have higher precedence.

** Building Grammars from Source Note: If you also plan to work on [[https://github.com/emacs-tree-sitter/elisp-tree-sitter#building-grammars-from-source][elisp-tree-sitter]], it might be more convenient to work with this repository as a submodule.

*** Tools and dependencies

• Install [[https://emacs-eask.github.io/][eask]].
• Install ELisp dependencies: #+begin_src bash eask install-deps #+end_src
• Install NodeJS. It is needed to generate the grammar code from the JavaScript DSL. The recommended tool to manage NodeJS is [[https://volta.sh/][volta]].
• Install [[https://tree-sitter.github.io/tree-sitter/creating-parsers#installation][tree-sitter CLI tool]]. (Its binary can also be downloaded directly from [[https://github.com/tree-sitter/tree-sitter/releases][GitHub]].)

*** Building grammars To build a specific language's grammar, run script/compile. (See the list of registered languages in [[./repos][repos/]].) For example: #+begin_src bash script/compile rust #+end_src

To build all registered languages, and creating the bundle: #+begin_src bash script/compile all #+end_src

*** Adding a new grammar

• Register a new submodule. For example: #+begin_src bash # git submodule add -b -- repos/ git submodule add -b master -- https://github.com/tree-sitter/tree-sitter-rust repos/rust #+end_src
• Modify its settings in [[.gitmodules][.gitmodules]]: #+begin_src conf update = none ignore = dirty #+end_src
• Try building and testing it. For example: #+begin_src bash script/compile rust script/test rust #+end_src