20 lines
1.6 KiB
Markdown
20 lines
1.6 KiB
Markdown
- TODO: document VSCode extension development practices
|
|
- TODO: document Helix Kerolox language setup
|
|
- TODO: document licensing and attribution guidelines
|
|
|
|
# Contributing to the Tree-sitter Grammar
|
|
|
|
The Kerolox tooling makes use of a custom [tree-sitter](https://github.com/tree-sitter/tree-sitter) grammar for fast incremental parsing.
|
|
|
|
The tree-sitter grammar lives in the `tree-sitter-kerolox` directory in the repository. The main file of interest is `grammar.js`, which defines the actual Kerolox grammar. The [tree-sitter documentation](https://tree-sitter.github.io/tree-sitter/creating-parsers/index.html) has very useful documentation on how to work with this grammar definition.
|
|
|
|
Any time the grammar is modified, the tree-sitter parser needs to be regenerated using the [tree-sitter CLI](https://github.com/tree-sitter/tree-sitter/blob/master/crates/cli/README.md). Otherwise, the changes to the grammar won't actually be compiled. To regenerate the parser from the grammar, ensure the CLI is installed, and run this command in the `tree-sitter-kerolox` directory:
|
|
|
|
```bash
|
|
tree-sitter generate --abi 14
|
|
```
|
|
|
|
We use an [ABI version](https://tree-sitter.github.io/tree-sitter/using-parsers/7-abi-versions.html) of 14 because it's known to work with older versions of [Helix](https://helix-editor.com), Marceline's preferred text editor. This is a deliberately overly cautious policy, but we're open to changing it if there's a good reason to.
|
|
|
|
The generated files should be committed and pushed as normal, since it's conventional for third-party tools to pull and compile pregenerated tree-sitter parsers directly from their upstream repositories.
|