emacs-tree-sitter / tree-sitter-langs

#+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: • 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. • 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]]. • 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