Crate tree_sitter

Expand description

§Rust Tree-sitter

Rust bindings to the Tree-sitter parsing library.

§Basic Usage

First, create a parser:

use tree_sitter::{InputEdit, Language, Parser, Point};

let mut parser = Parser::new();

Add the cc crate to your Cargo.toml under [build-dependencies]:

[build-dependencies]
cc="*"

Then, add a language as a dependency:

[dependencies]
tree-sitter = "0.24"
tree-sitter-rust = "0.23"

To then 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 mut tree = parser.parse(source_code, None).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);

§Editing

Once you have a syntax tree, you can update it when your source code changes. Passing in the previous edited tree makes parse run much more quickly:

let new_source_code = "fn test(a: u32) {}";

tree.edit(&InputEdit {
  start_byte: 8,
  old_end_byte: 8,
  new_end_byte: 14,
  start_position: Point::new(0, 8),
  old_end_position: Point::new(0, 8),
  new_end_position: Point::new(0, 14),
});

let new_tree = parser.parse(new_source_code, Some(&tree));

§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(&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) (identifier) (parameters) (block (number_literal))))"
);

§Features

std - This feature is enabled by default and allows tree-sitter to use the standard library.
- Error types implement the std::error:Error trait.
- regex performance optimizations are enabled.
- The DOT graph methods are enabled.
wasm - This feature allows tree-sitter to be built for Wasm targets using the wasmtime-c-api crate.

Re-exports§

pub use wasmtime_c_api::wasmtime;

Modules§

ffi

Structs§

IncludedRangesError: An error that occurred in Parser::set_included_ranges.
InputEdit: A summary of a change to a text document.
Language: An opaque object that defines how to parse a particular language. The code for each Language is generated by the Tree-sitter CLI.
LanguageError: An error that occurred when trying to assign an incompatible Language to a Parser.
LanguageMetadata: The metadata associated with a language.
LanguageRef
LookaheadIterator: A stateful object that is used to look up symbols valid in a specific parse state
LossyUtf8
Node: A single node within a syntax Tree.
ParseOptions
ParseState: 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 Tree based on some source code.
Point: A position in a multi-line text document, in terms of rows and columns.
Query: A set of patterns that match nodes in a syntax tree.
QueryCapture: A particular Node that has been captured with a particular name within a Query.
QueryCaptures: A sequence of QueryCaptures associated with a given QueryCursor.
QueryCursor: A stateful object for executing a Query on a syntax Tree.
QueryCursorOptions
QueryCursorState: A stateful object that is passed into a [QueryProgressCallback] to pass in the current state of the query execution.
QueryError: An error that occurred when trying to create a Query.
QueryMatch: A match of a Query to a particular set of Nodes.
QueryMatches: A sequence of QueryMatches associated with a given QueryCursor.
QueryPredicate: A key-value pair associated with a particular pattern in a Query.
QueryProperty: A key-value pair associated with a particular pattern in a Query.
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.
TreeCursor: A stateful object for walking a syntax Tree efficiently.
WasmErrorwasm
WasmStorewasm
wasm_engine_twasm

Enums§

CaptureQuantifier: A quantifier for captures
LogType: A type of log message.
QueryErrorKind
QueryPredicateArg
WasmErrorKindwasm

Constants§

LANGUAGE_VERSION: The latest ABI version that is supported by the current version of the library.
MIN_COMPATIBLE_LANGUAGE_VERSION: The earliest ABI version that is supported by the current version of the library.
PARSER_HEADER

Traits§

Decode
StreamingIterator: An interface for dealing with streaming iterators.
StreamingIteratorMut: An interface for dealing with mutable streaming iterators.
TextProvider

Functions§

set_allocator^⚠: Sets the memory allocation functions that the core library should use.
wasm_stdlib_symbols

Crate tree_sitterCopy item path