Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/wilfred/tree-sitter-elisp
tree-sitter grammar for emacs lisp
https://github.com/wilfred/tree-sitter-elisp
emacs emacs-lisp tree-sitter
Last synced: 13 days ago
JSON representation
tree-sitter grammar for emacs lisp
- Host: GitHub
- URL: https://github.com/wilfred/tree-sitter-elisp
- Owner: Wilfred
- License: mit
- Created: 2021-08-15T01:17:18.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2024-06-18T15:48:11.000Z (5 months ago)
- Last Synced: 2024-10-19T10:42:38.738Z (25 days ago)
- Topics: emacs, emacs-lisp, tree-sitter
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/tree-sitter-elisp
- Size: 280 KB
- Stars: 65
- Watchers: 4
- Forks: 7
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Tree-sitter Grammar for Emacs Lisp
A tree-sitter grammar for elisp.
Syntax supported:
* Atoms (integers, floats, strings, characters, symbols)
* Lists (normal syntax `(a b)` and dotted `(a . b)`)
* Vectors
* Quoting and unquoting (`'`, `#'`, `` ` ``, `,`, `,@`)
* Some special read syntax (`$#`, `##`, `#("foo" 1 2 x)`)
* Bytecode literals (`#[1 2 3 4]`)
* Special forms (`let` etc)
* Comments
Limitations:
* Autoload cookies are treated as plain comments
## Limitations
Elisp is a lisp-2 with user-defined macros. A simple parser cannot
detect if e.g. `(foo (let ...))` is a function call with a `let`
expression argument, or a macro call where `let` means something else.
Currently tree-sitter-elisp treats everything as an s-expression. This
is accurate, but makes this package less useful for generating a
summary of file contents, or for syntax highlighting.
Emacs itself has more information that it can use. Emacs will
highlight macro calls based on which macros are defined in the current
instance. Some elisp packages also offer custom highlighting logic,
such as `dash-fontify-mode` in
[dash.el](https://github.com/magnars/dash.el).
## Developing
Check out the repo, then use `npm` to install dependencies.
```
$ npm install
```
You can then parse your favourite elisp files.
```
$ npm run parse ~/.emacs.d/init.el
```
The grammar itself is in
[grammar.js](https://github.com/Wilfred/tree-sitter-elisp/blob/main/grammar.js). You'll
need to regenerate the code after editing the grammar.
```
$ npm run generate
```
This project also contains a few tests.
```
$ npm test
```
You can also run this parser against your `.emacs.d` to confirm it can
parse everything.
```
$ npm run parse -- '/home/wilfred/.emacs.d/**/*.el' --quiet --stat
```
## Why?
The best place to read and write elisp is of course Emacs.
However, there is a growing ecosystem of tools built on top of
tree-sitter, such as GitHub. This project should allow them to support
emacs lisp too.
## Related Projects
[tree-sitter-clojure](https://github.com/sogaiu/tree-sitter-clojure)
is another tree-sitter package for the lisp family. It's a useful
project to compare with, and [has notes discussing lisp-specific
challenges](https://github.com/sogaiu/tree-sitter-clojure/blob/master/doc/scope.md).
[language-emacs-lisp](https://github.com/Alhadis/language-emacs-lisp)
is a textmate grammar for elisp that's used for Atom and GitHub.