https://github.com/71/vscode-tree-sitter-api
Exposing Tree Sitter parsers and queries to VS Code extensions (with caching & more utilities).
https://github.com/71/vscode-tree-sitter-api
Last synced: about 1 year ago
JSON representation
Exposing Tree Sitter parsers and queries to VS Code extensions (with caching & more utilities).
- Host: GitHub
- URL: https://github.com/71/vscode-tree-sitter-api
- Owner: 71
- License: mpl-2.0
- Created: 2023-04-22T15:07:19.000Z (about 3 years ago)
- Default Branch: master
- Last Pushed: 2023-12-02T11:48:48.000Z (over 2 years ago)
- Last Synced: 2025-04-18T13:16:10.673Z (about 1 year ago)
- Language: TypeScript
- Size: 80.1 KB
- Stars: 16
- Watchers: 2
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# `tree-sitter`
A VS Code extension that exposes the Tree Sitter API to other extensions.
It can:
1. Load the Tree Sitter WebAssembly module, as well as supported languages.
2. Cache parsed trees.
3. Detect languages.
## WIP
This is work-in-progress intended for future use within
[Dance](https://github.com/71/dance). A few more polishing touches are needed
before it will be ready to publish on the extension store. More importantly, the
API is very much subject to change.
## Usage
See [`extension.test.ts`](src/test/suite/extension.test.ts) for an up-to-date
example.
```typescript
const document = await vscode.workspace.openTextDocument({
content: `
pub fn foo() {
println!("bar");
}
`,
language: "rust",
});
const TreeSitter = await vscode.extensions.getExtension(
"gregoire.tree-sitter",
).activate()!;
await TreeSitter.withDocumentTree(document, async (tree) => {
await TreeSitter.withQuery(
document,
`(macro_invocation) @macro`,
(query) => {
const captures = query.captures(tree.rootNode);
const macroCapture = captures.find(({ name }) => name === "macro");
assert.ok(macroCapture);
assert.strictEqual(macroCapture.node.type, "macro_invocation");
assert.strictEqual(macroCapture.node.text, 'println!("bar")');
},
);
});
```
Note:
1. Detection of the language of `document` was done automatically.
2. The Tree Sitter library and Rust parser were both loaded implicitly when
calling `documentTree()`.
3. No object had to be manually deleted with `.delete()`, despite Tree Sitter
being a WebAssembly library which requires manual deallocation.
- It is still possible to manage your objects manually by using
`documentTree()` and `query()` (instead of their `with*` counterparts), but
you will have to make sure to call `.delete()` after using them.
## Development
### Dependencies
[Deno](https://deno.com) and [Emscripten](https://emscripten.org) must be
installed with `deno` and `emcc` both available in the `PATH`.
### Setup
Install dependencies with `yarn`:
```sh
$ yarn
```
A few files must be generated for the build process to continue. Since building
these files can be slow and requires internet access, this must be done
manually:
```sh
$ ./tools.ts --build-wasm --update-text-objects
```
### Building
Run `yarn run compile` to build the extension, and `yarn vsce package` to
package it for publishing in the store.
### Testing
In VS Code, start the `watch:test` task, then launch "Extension Tests" in the
"Run and Debug" menu.
## Scope inspection
This extension provides a command named "Inspect Scopes" which displays the
current scope in the status bar; hovering the scope will display all its
ancestors in a tooltip. This may help write commands that operate on the
returned tree or that perform queries.