Expand description
§willbooster-tree-sitter
Rust bindings to this fork of the Tree-sitter parsing library. The crate keeps the library name
tree_sitter, so depending on it under the name tree-sitter (as below) needs no code changes.
§Basic Usage
First, create a parser:
use tree_sitter::{Parser, Point};
let mut parser = Parser::new();Then, add the runtime and a language crate to Cargo.toml:
cargo add willbooster-tree-sitter --rename tree-sitter
cargo add willbooster-tree-sitter-rust --rename tree-sitter-rustUse a grammar generated by this fork’s CLI for an ABI in MIN_COMPATIBLE_LANGUAGE_VERSION..=LANGUAGE_VERSION. Cargo
does not check the generated language ABI; set_language rejects upstream grammars and grammars generated for an
incompatible ABI.
To use a language, you assign them to the parser.
parser.set_language(&tree_sitter_rust::LANGUAGE.into()).expect("Error loading Rust grammar");Now you can parse source code:
let source_code = "fn test() {}";
let tree = parser.parse(source_code).unwrap();
let root_node = tree.root_node();
assert_eq!(root_node.kind(), "source_file");
assert_eq!(root_node.start_position().column, 0);
assert_eq!(root_node.end_position().column, 12);§Text Input
The source code to parse can be provided either as a string, a slice, a vector, or as a function that returns a slice. The text can be encoded as either UTF8 or UTF16:
// Store some source code in an array of lines.
let lines = &[
"pub fn foo() {",
" 1",
"}",
];
// Parse the source code using a custom callback. The callback is called
// with both a byte offset and a row/column offset.
let tree = parser.parse_with_options(&mut |_byte: usize, position: Point| -> &[u8] {
let row = position.row as usize;
let column = position.column as usize;
if row < lines.len() {
if column < lines[row].as_bytes().len() {
&lines[row].as_bytes()[column..]
} else {
b"\n"
}
} else {
&[]
}
}, None).unwrap();
assert_eq!(
tree.root_node().to_sexp(),
"(source_file (function_item (visibility_modifier) name: (identifier) parameters: (parameters) body: (block (integer_literal))))"
);§Using Wasm Grammar Files
Requires the wasm feature and Rust 1.96 or newer. This optional feature has a higher compiler requirement than the crate default because it uses Wasmtime.
First, create a parser with a Wasm store:
use tree_sitter::{wasmtime::Engine, Parser, WasmStore};
let engine = Engine::default();
let store = WasmStore::new(&engine).unwrap();
let mut parser = Parser::new();
parser.set_wasm_store(store).unwrap();Then, load the language from a Wasm file that the CLI of this runtime’s major version built from a parser it generated
(tree-sitter generate, then tree-sitter build --wasm); other Wasm files are rejected like other parsers:
const JAVASCRIPT_GRAMMAR: &[u8] = include_bytes!("path/to/tree-sitter-javascript.wasm");
let mut store = WasmStore::new(&engine).unwrap();
let javascript = store
.load_language("javascript", JAVASCRIPT_GRAMMAR)
.unwrap();
// The language may be loaded from a different WasmStore than the one set on
// the parser but it must use the same underlying WasmEngine.
parser.set_language(&javascript).unwrap();Now you can parse source code:
let source_code = "let x = 1;";
let tree = parser.parse(source_code).unwrap();
assert_eq!(
tree.root_node().to_sexp(),
"(program (lexical_declaration (variable_declarator name: (identifier) value: (number))))"
);§Features
- std - This feature is enabled by default and allows
tree-sitterto use the standard library.- Error types implement the
std::error::Errortrait. - The DOT graph methods are enabled.
- Error types implement the
- wasm - Loads Wasm grammar files through Wasmtime. See Using Wasm Grammar Files for its compiler requirement.
Re-exports§
pub use wasmtime_c_api::wasmtime;
Modules§
Structs§
- Allocator
- A complete set of memory allocation functions for the core C library.
- Included
Ranges Error - An error that occurred in
Parser::set_included_ranges. - Language
- An opaque object that defines how to parse a particular language. The code
for each
Languageis generated by the Tree-sitter CLI. - Language
Metadata - The metadata associated with a language.
- Language
Ref - Node
- A single node within a syntax
Tree. - Parse
Options - Parse
State - A stateful object that is passed into a [
ParseProgressCallback] to pass in the current state of the parser. - Parser
- A stateful object that this is used to produce a
Treebased on some source code. - Point
- A position in a multi-line text document, in terms of rows and columns.
- Range
- A range of positions in a multi-line text document, both in terms of bytes and of rows and columns.
- Tree
- A tree that represents the syntactic structure of a source code file.
- Tree
Cursor - A stateful object for walking a syntax
Treeefficiently. - Wasm
Error wasm - Wasm
Store wasm - wasm_
engine_ t wasm
Enums§
- Language
Error - An error that occurred when trying to assign a
Languageto aParser. If thewasmfeature is enabled, this can also indicate a failure to load the Wasm store. - LogType
- A type of log message.
- Wasm
Error Kind wasm
Constants§
- LANGUAGE_
VERSION - The latest ABI version that the current version of the library supports.
- MIN_
COMPATIBLE_ LANGUAGE_ VERSION - The earliest ABI version that is supported by the current version of the
library. Its parse tables are a subset of those of
LANGUAGE_VERSION, so the library loads both. - PARSER_
HEADER
Traits§
Functions§
- set_
allocator ⚠ - Replaces the memory allocation functions used by the core C library.
- wasm_
stdlib_ symbols