Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/emacs-tree-sitter/elisp-tree-sitter
Emacs Lisp bindings for tree-sitter
https://github.com/emacs-tree-sitter/elisp-tree-sitter
binding emacs emacs-modules incremental parsing rust tree-sitter
Last synced: 3 months ago
JSON representation
Emacs Lisp bindings for tree-sitter
- Host: GitHub
- URL: https://github.com/emacs-tree-sitter/elisp-tree-sitter
- Owner: emacs-tree-sitter
- License: mit
- Created: 2019-07-09T09:36:13.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-05-12T23:10:09.000Z (8 months ago)
- Last Synced: 2024-09-27T10:41:13.784Z (4 months ago)
- Topics: binding, emacs, emacs-modules, incremental, parsing, rust, tree-sitter
- Language: Emacs Lisp
- Homepage: https://emacs-tree-sitter.github.io
- Size: 1.36 MB
- Stars: 821
- Watchers: 26
- Forks: 74
- Open Issues: 78
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# ELisp Tree-sitter 
[](https://emacs-tree-sitter.github.io/)
[](https://github.com/emacs-tree-sitter/elisp-tree-sitter/actions/workflows/main.yml)
For Emacs 29+, please use [the built-in integration](https://lists.gnu.org/archive/html/emacs-devel/2022-11/msg01443.html) instead of this package.
This is an Emacs Lisp binding for [tree-sitter](https://tree-sitter.github.io/tree-sitter/), an incremental parsing library. It requires Emacs 25.1 or above, built with dynamic module support.
It aims to be the foundation for a new breed of Emacs packages that understand code structurally. For example:
- Faster, fine-grained code highlighting.
- More flexible code folding.
- Structural editing (like Paredit, or even better) for non-Lisp code.
- More informative indexing for imenu.
The author of tree-sitter articulated its merits a lot better in this [Strange Loop talk](https://www.thestrangeloop.com/2018/tree-sitter---a-new-parsing-system-for-programming-tools.html).
## Installation
See the [installation section](https://emacs-tree-sitter.github.io/installation/) in the documentation.
If you want to hack on `emacs-tree-sitter` itself, see the next section instead.
## Setup for Development
**Note**: On Windows, use Powershell instead of Bash or cmd.exe.
- Clone this repo with the `--recursive` flag.
- Add 3 of its directories to `load-path`: `core/`, `lisp/` and `langs/`.
- Install [eask](https://emacs-eask.github.io/).
- Run `bin/setup`.
If you want to hack on the high-level features (in Lisp) only:
- Make changes to the `.el` files.
- Add tests to `tree-sitter-tests.el` and run them with `bin/test`.
If you want to build additional (or all) grammars from source, or work on the core dynamic module, see the next 2 sections.
### Building grammars from source
**Note**: If you are only interested in building the grammar binaries, not the dynamic module, check out [tree-sitter-langs](https://github.com/emacs-tree-sitter/tree-sitter-langs#building-grammars-from-source).
- Install NodeJS. It is needed to generate the grammar code from the JavaScript DSL. The recommended tool to manage NodeJS is [volta](https://volta.sh/).
- Install [tree-sitter CLI tool](https://tree-sitter.github.io/tree-sitter/creating-parsers#installation): (Its binary can also be downloaded directly from [GitHub](https://github.com/tree-sitter/tree-sitter/releases).) **Note: version 0.20+ cannot be used, as they introduced [a breaking change](https://github.com/tree-sitter/tree-sitter/pull/1157) in binary storage location.**
```bash
# For yarn user
yarn global add [email protected]
# For npm user
npm install -g [email protected]
```
- Run `langs/script/compile`. For example:
```bash
langs/script/compile rust
```
### Working on the dynamic module
- Install the [Rust toolchain](https://rustup.rs/).
- Build:
```bash
bin/build
```
- Test:
```bash
bin/test
```
- Continuously rebuild and test on change (requires [cargo-watch](https://github.com/passcod/cargo-watch)):
```bash
bin/test watch
```
To test against a different version of Emacs, set the environment variable `EMACS` (e.g. `EMACS=/snap/bin/emacs make test`).
## Alternatives
- [Tree-sitter in Emacs's core](https://lists.gnu.org/archive/html/emacs-devel/2022-11/msg01443.html) (the future)
- Binding through C instead of Rust: https://github.com/karlotness/tree-sitter.el (dormant)
## Contribution
Contributions are welcomed. Please take a look at the [issue list](https://github.com/emacs-tree-sitter/elisp-tree-sitter/issues) for ideas, or [create a new issue](https://github.com/emacs-tree-sitter/elisp-tree-sitter/issues/new) to describe any idea you have for improvement.
For language-specific issues/features, please check out [tree-sitter-langs](https://github.com/emacs-tree-sitter/tree-sitter-langs) instead.
Show respect and empathy towards others. Both technical empathy and general empathy are highly valued.