https://github.com/emacs-tree-sitter/tree-sitter-langs

Language bundle for Emacs's tree-sitter package
https://github.com/emacs-tree-sitter/tree-sitter-langs

emacs parsing tree-sitter

Last synced: 4 days ago
JSON representation

Language bundle for Emacs's tree-sitter package

• Host: GitHub
• URL: https://github.com/emacs-tree-sitter/tree-sitter-langs
• Owner: emacs-tree-sitter
• License: mit
• Created: 2021-02-19T09:42:19.000Z (almost 4 years ago)
• Default Branch: master
• Last Pushed: 2024-12-10T09:21:48.000Z (15 days ago)
• Last Synced: 2024-12-10T10:26:46.253Z (15 days ago)
• Topics: emacs, parsing, tree-sitter
• Language: Emacs Lisp
• Homepage: https://emacs-tree-sitter.github.io/languages/
• Size: 1.15 MB
• Stars: 268
• Watchers: 7
• Forks: 132
• Open Issues: 85
• Metadata Files:
  • Readme: README.org
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

README

        
#+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. [email protected]~.

   + ~@method~ vs. [email protected]~.

   + [email protected]~ vs. [email protected]~.

- ~@variable~ and [email protected]~ 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): [email protected]~, [email protected]~, [email protected]~.

- 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]].) *Note: versions 0.20+ cannot be used, as they introduce [[https://github.com/tree-sitter/tree-sitter/pull/1157][a breaking change]] in binary storage location*.

*** 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