tree_sitter

A MoonBit binding to the tree-sitter parsing library

tree-sitter
parser
syntax
highlighting
moon add tonyfettes/tree_sitter@0.4.6
Download zip
Version
0.4.6
License
Apache-2.0
Last updated
4 months ago
Downloads
123
README

#tonyfettes/tree_sitter

This is a MoonBit binding to the tree-sitter incremental parsing library.

#Quickstart

  1. Add this module as a dependency to your MoonBit project:

    moon update # Update the mooncakes.io package index moon add tonyfettes/tree_sitter

  2. Import the tonyfettes/tree_sitter package in moon.pkg.json:

    { "import": [ "tonyfettes/tree_sitter" ] }

  3. Optionally you may want to install MoonBit bindings to the tree-sitter grammars you want to use. For example, to install the tree-sitter-moonbit grammar:

    moon add tonyfettes/tree_sitter_moonbit

    And then import the tonyfettes/tree_sitter_moonbit package in your moon.pkg.json file as well:

    { "import": [ "tonyfettes/tree_sitter", "tonyfettes/tree_sitter_moonbit" ] }

  4. Use the tonyfettes/tree_sitter API to parse your code:

    fn main {
    let moonbit = @tree_sitter_moonbit.language()
    let parser = @tree_sitter.Parser::new()
    parser.set_language(moonbit)
    let source_code =
    #|fn main {
    #| println("Hello, World!")
    #|}
    let tree = parser.parse_string(None, source_code)
    let root_node = tree.root_node()
    println(root_node.string())
    }

#API Walkthrough

The Tree-sitter User Guide is a good place to start if you're new to tree-sitter. Although the API is written in C, this MoonBit binding is just a thin wrapper around the C API, so the documentation should be mostly applicable.

This binding is at its very early stages, so many APIs are not yet implemented. If you find a missing API that you need, please open an issue or a pull request.

Apart from the standard tree-sitter API, this binding also provides abilities to parse the grammar.json and node-types.json files that are generated by the tree-sitter CLI. This is useful if you want to generate MoonBit type definitions for a tree-sitter grammar.

#Development

#Prerequisites

Other than MoonBit toolchain, this project requires Python (3.9 or later) to build. Please make sure your system has python available in the PATH.

#Build

The build should work out of the box on Linux and macOS. Windows is not tested, and you are more than welcome to open an issue or a pull request if you find problems.

# Initialize the tree-sitter submodule git submodule update --init --recursive moon update moon build --target native

We amalgamate the tree-sitter source code with the C stubs together to build a monolithic C file (src/tree-sitter-lib/lib.c) that can be compiled as a single object file. This step is done by a Python script at scripts/prepare.py. The script is set to run automatically when you run moon build --target native or moon check --target native. If you find the generated C file is out of date, you can run the script manually:

python scripts/prepare.py

#Test

Before running tests, make sure you have completed the build step above.

To avoid introducing the dependency of the tree-sitter grammars, we put the majority of the tests inside the test/ directory. To run the tests, you can cd into the test/ directory and run moon test --target native:

cd test && moon test --target native

[!NOTE] You may find that the LSP is not working when you are editing files under the test/ directory. This is because test/ is a MoonBit module itself, and therefore the LSP process has to be spawned in the test/ directory to work properly. In most cases, this means you need to spin up a new editor instance inside the test/ directory.

#
QueryPredicate

type QueryPredicate = Array[QueryPredicateStep]

An Array is a collection of values that supports random access and can grow in size.

#
DecodeFunction

pub(open) trait DecodeFunction {
encoding(Self) -> InputEncoding = _
decode(BytesView) -> DecodeResult?
}

This function signature reads one code point from the given bytes, returning the number of bytes consumed and the code point. If the input is invalid, return None.

#
LanguageError

type LanguageError derive(Show)

#
ParseError

pub suberror ParseError {
MissingLanguage
Cancelled
} derive(Show)

#
QueryError

type QueryError derive(Show)

#
DecodeResult

type DecodeResult

#
DecodeResult::new

fn DecodeResult::new(code_point~ : Char, bytes_read~ : Int) -> DecodeResult

#
FieldId

type FieldId

#
Input

type Input[DecodeFunction]

#
Input::new

fn[DecodeFunction] Input::new(read : (Int, Point) -> BytesView, decode : DecodeFunction) -> Input[DecodeFunction]

#
InputEdit

type InputEdit

#
InputEdit::new

fn InputEdit::new(start_byte~ : Int, old_end_byte~ : Int, new_end_byte~ : Int, start_point~ : Point, old_end_point~ : Point, new_end_point~ : Point) -> InputEdit

#
InputEncoding

pub(all) enum InputEncoding {
UTF8
UTF16LE
UTF16BE
Custom
}

#
InputEncoding::custom

#
Language

#
Language::abi_version

fn Language::abi_version(self : Language) -> Int

Get the ABI version number for this language. This version number is used to ensure that languages were generated by a compatible version of Tree-sitter.

See also Parser::set_language.

#
Language::copy

fn Language::copy(self : Language) -> Language

Get another reference to the given language.

#
Language::delete

fn Language::delete(self : Language) -> Unit

Free any dynamically-allocated resources for this language, if this is the last reference.

#
Language::field_count

fn Language::field_count(self : Language) -> Int

Get the number of distinct field names in the language.

#
Language::field_id_for_name

fn Language::field_id_for_name(self : Language, name : StringView) -> Int

Get the numerical id for the given field name string.

#
Language::field_name_for_id

fn Language::field_name_for_id(self : Language, id : FieldId) -> String?

Get the field name string for the given numerical id.

#
Language::inner

#deprecated("Use `struct T(A)` to declare a newtype and use `.0` access the underlying type instead.")
fn Language::inner(self : Language) ->
Language
Convert newtype to its underlying type, automatically derived.

#
Language::metadata

fn Language::metadata(self : Language) -> LanguageMetadata

Get the metadata for this language. This information is generated by the CLI, and relies on the language author providing the correct metadata in the language's tree-sitter.json file.

See also LanguageMetadata.

#
Language::name

fn Language::name(self : Language) -> String?

Get the name of this language. This returns None in older parsers.

#
Language::next_state

fn Language::next_state(self : Language, state : StateId, symbol : Symbol) -> StateId

Get the next parse state. Combine this with lookahead iterators to generate completion suggestions or valid symbols in error nodes. Use Node::grammar_symbol for valid symbols.

#
Language::state_count

fn Language::state_count(self : Language) -> Int

Get the number of valid states in this language.

#
Language::subtypes

fn Language::subtypes(self : Language) -> Array[Symbol]

Get a list of all subtype symbol ids for a given supertype symbol.

See Language::supertypes for fetching all supertype symbols.

#
Language::supertypes

fn Language::supertypes(self : Language) -> Array[Symbol]

Get a list of all supertype symbols for the language.

#
Language::symbol_count

fn Language::symbol_count(self : Language) -> Int

Get the number of distinct node types in the language.

#
Language::symbol_for_name

fn Language::symbol_for_name(self : Language, name : StringView) -> Symbol?

Get the numerical id for the given node type string.

#
Language::symbol_name

fn Language::symbol_name(self : Language, symbol : Symbol) -> String?

Get a node type string for the given numerical id.

#
Language::symbol_type

fn Language::symbol_type(self : Language, symbol : Symbol) -> SymbolType

Check whether the given node type id belongs to named nodes, anonymous nodes, or a hidden nodes.

See also Node::is_named. Hidden nodes are never returned from the API.

#
Language::version

#deprecated("Use `Language::abi_version` instead")
fn Language::version(self : Language) -> Int

Get the ABI version number for this language. This version number is used to ensure that languages were generated by a compatible version of Tree-sitter.

See also Parser::set_language.

#
LanguageMetadata

type LanguageMetadata

The metadata associated with a language.

Currently, this metadata can be used to check the Semantic Version of the language. This version information should be used to signal if a given parser might be incompatible with existing queries when upgrading between major versions, or minor versions if it's in zerover.

#
LanguageMetadata::major_version

fn LanguageMetadata::major_version(self : LanguageMetadata) -> Byte

#
LanguageMetadata::minor_version

fn LanguageMetadata::minor_version(self : LanguageMetadata) -> Byte

#
LanguageMetadata::patch_version

fn LanguageMetadata::patch_version(self : LanguageMetadata) -> Byte

#
LogType

pub enum LogType {
Parse
Lex
}

#
Logger

type Logger

#
Logger::new

fn Logger::new(log : (LogType, StringView) -> Unit) -> Logger

#
LookaheadIterator

type LookaheadIterator

#
LookaheadIterator::current_symbol

fn LookaheadIterator::current_symbol(self : LookaheadIterator) -> Symbol

Get the current symbol of the lookahead iterator.

#
LookaheadIterator::current_symbol_name

fn LookaheadIterator::current_symbol_name(self : LookaheadIterator) -> String?

Get the current symbol type of the lookahead iterator as a string.

#
LookaheadIterator::language

Get the current language of the lookahead iterator.

#
LookaheadIterator::new

fn LookaheadIterator::new(language : Language, state : StateId) -> LookaheadIterator?

Create a new lookahead iterator for the given language and parse state.

This returns None if state is invalid for the language.

Repeatedly using LookaheadIterator::next and LookaheadIterator::current_symbol will generate valid symbols in the given parse state. Newly created lookahead iterators will contain the ERROR symbol.

Lookahead iterators can be useful to generate suggestions and improve syntax error diagnostics. To get symbols valid in an ERROR node, use the lookahead iterator on its first leaf node state. For MISSING nodes, a lookahead iterator created on the previous non-extra leaf node may be appropriate.

#
LookaheadIterator::next

fn LookaheadIterator::next(iterator : LookaheadIterator) -> Bool

Advance the lookahead iterator to the next symbol.

This returns true if there is a new symbol and false otherwise.

#
LookaheadIterator::reset

fn LookaheadIterator::reset(self : LookaheadIterator, language : Language, state : StateId) -> Bool

Reset the lookahead iterator.

This returns true if the language was set successfully and false otherwise.

#
LookaheadIterator::reset_state

fn LookaheadIterator::reset_state(self : LookaheadIterator, state : StateId) -> Bool

Reset the lookahead iterator to another state.

This returns true if the iterator was reset to the given state and false otherwise.

#
Node

type Node

impl Eq for Node
impl Hash for Node
impl Show for Node
impl ToJson for Node

#
Node::child

fn Node::child(self : Node, index : Int) -> Node?

Get the node's child at the given index, where zero represents the first child.

#
Node::child_by_field_id

fn Node::child_by_field_id(self : Node, id : FieldId) -> Node?

Get the node's child with the given numerical field id.

You can convert a field name to an id using the Language::field_id_for_name function.

#
Node::child_by_field_name

fn Node::child_by_field_name(self : Node, name : StringView) -> Node?

Get the node's child with the given field name.

#
Node::child_count

fn Node::child_count(self : Node) -> Int

Get the node's number of children.

#
Node::child_with_descendant

fn Node::child_with_descendant(self : Node, descendant : Node) -> Node?

Get the node that contains descendant.

Note that this can return descendant itself.

#
Node::children

fn Node::children(self : Node) -> Iter[Node]

Get all children of the node.

#
Node::descendant_count

fn Node::descendant_count(self : Node) -> Int

Get the node's number of descendants, including one for the node itself.

#
Node::descendant_for_byte_range

fn Node::descendant_for_byte_range(self : Node, start_byte : Int, end_byte : Int) -> Node?

Get the smallest node within this node that spans the given range of bytes.

#
Node::descendant_for_point_range

fn Node::descendant_for_point_range(self : Node, start_point : Point, end_point : Point) -> Node?

Get the smallest node within this node that spans the given range of (row, column) positions.

#
Node::edit

fn Node::edit(self : Node, edit : InputEdit) -> Unit

Edit the node to keep it in-sync with source code that has been edited.

This function is only rarely needed. When you edit a syntax tree with the Tree::edit function, all of the nodes that you retrieve from the tree afterward will already reflect the edit. You only need to use Node::edit when you have a Node instance that you want to keep and continue to use after an edit.

#
Node::end_byte

fn Node::end_byte(self : Node) -> Int

Get the node's end byte.

#
Node::end_point

fn Node::end_point(self : Node) -> Point

#
Node::eq

fn Node::eq(self : Node, other : Node) -> Bool

Check if two nodes are identical.

#
Node::field_name_for_child

fn Node::field_name_for_child(self : Node, child_index : Int) -> String?

Get the field name for node's child at the given index, where zero represents the first child. Returns None, if no field is found.

#
Node::field_name_for_named_child

fn Node::field_name_for_named_child(self : Node, child_index : Int) -> String?

Get the field name for node's named child at the given index, where zero represents the first named child. Returns None, if no field is found.

#
Node::first_child_for_byte

fn Node::first_child_for_byte(self : Node, byte : Int) -> Node?

Get the node's first child that contains or starts after the given byte offset.

#
Node::first_named_child_for_byte

fn Node::first_named_child_for_byte(self : Node, byte : Int) -> Node?

Get the node's first named child that contains or starts after the given byte offset.

#
Node::grammar_symbol

fn Node::grammar_symbol(self : Node) -> Symbol

Get the node's type as a numerical id as it appears in the grammar ignoring aliases. This should be used in Language::next_state instead of Node::symbol.

#
Node::grammar_type

fn Node::grammar_type(self : Node) -> String

Get the node's type as it appears in the grammar ignoring aliases as a string.

#
Node::has_changes

fn Node::has_changes(self : Node) -> Bool

Check if a syntax node has been edited.

#
Node::has_error

fn Node::has_error(self : Node) -> Bool

Check if the node is a syntax error or contains any syntax errors.

#
Node::is_error

fn Node::is_error(self : Node) -> Bool

Check if the node is a syntax error.

#
Node::is_extra

fn Node::is_extra(self : Node) -> Bool

Check if the node is extra. Extra nodes represent things like comments, which are not required the grammar, but can appear anywhere.

#
Node::is_missing

fn Node::is_missing(self : Node) -> Bool

Check if the node is missing. Missing nodes are inserted by the parser in order to recover from certain kinds of syntax errors.

#
Node::is_named

fn Node::is_named(self : Node) -> Bool

Check if the node is named. Named nodes correspond to named rules in the grammar, whereas anonymous nodes correspond to string literals in the grammar.

#
Node::is_null

fn Node::is_null(self : Node) -> Bool

Check if the node is null. Functions like Node::child and Node::next_sibling will return a null node to indicate that no such node was found.

#
Node::language

fn Node::language(self : Node) -> Language

Get the node's language.

#
Node::named_child

fn Node::named_child(self : Node, child_index : Int) -> Node?

Get the node's named child at the given index.

See also Node::is_named.

#
Node::named_child_count

fn Node::named_child_count(self : Node) -> Int

Get the node's number of named children.

See also Node::is_named.

#
Node::named_children

fn Node::named_children(self : Node) -> Iter[Node]

Get all named children of the node.

#
Node::named_descendant_for_byte_range

fn Node::named_descendant_for_byte_range(self : Node, start_byte : Int, end_byte : Int) -> Node?

Get the smallest named node within this node that spans the given range of bytes.

#
Node::named_descendant_for_point_range

fn Node::named_descendant_for_point_range(self : Node, start_point : Point, end_point : Point) -> Node?

Get the smallest named node within this node that spans the given (row, column) positions.

#
Node::next_named_sibling

fn Node::next_named_sibling(self : Node) -> Node?

Get the node's next named sibling.

#
Node::next_parse_state

fn Node::next_parse_state(self : Node) -> StateId

Get the parse state after this node.

#
Node::next_sibling

fn Node::next_sibling(self : Node) -> Node?

Get the node's next sibling.

#
Node::next_symbol_names

fn Node::next_symbol_names(self : Node) -> Iter[String]

#
Node::next_symbols

fn Node::next_symbols(self : Node) -> Iter[Symbol]

#
Node::parent

fn Node::parent(self : Node) -> Node?

Get the node's immediate parent. Prefer Node::child_with_descendant for iterating over the node's ancestors.

#
Node::parse_state

fn Node::parse_state(self : Node) -> StateId

Get this node's parse state.

#
Node::prev_named_sibling

fn Node::prev_named_sibling(self : Node) -> Node?

Get the node's previous named sibling.

#
Node::prev_sibling

fn Node::prev_sibling(self : Node) -> Node?

Get the node's previous sibling.

#
Node::query

fn Node::query(self : Node, source : StringView) -> QueryCursor raise QueryError

#
Node::range

fn Node::range(self : Node) -> Range

#
Node::start_byte

fn Node::start_byte(self : Node) -> Int

Get the node's start byte.

#
Node::start_point

fn Node::start_point(self : Node) -> Point

Get the node's start position in terms of rows and columns.

#
Node::string

fn Node::string(self : Node) -> String

Get an S-expression representing the node as a string.

#
Node::symbol

fn Node::symbol(self : Node) -> Symbol

Get the node's type as a numerical id.

#
Node::symbol_names

fn Node::symbol_names(self : Node) -> Iter[String]

#
Node::symbols

fn Node::symbols(self : Node) -> Iter[Symbol]

#
Node::text

fn Node::text(self : Node) -> StringView

#
Node::type_

fn Node::type_(self : Node) -> String

Get the node's type as a string.

#
Node::walk

fn Node::walk(self : Node) -> TreeCursor

#
ParseOptions

type ParseOptions

Options for parsing.

#
ParseOptions::new

fn ParseOptions::new(progress_callback : (ParseState) -> Bool) -> ParseOptions

Create new parse options with the given progress callback.

#
ParseState

pub struct ParseState {
current_byte_offset : Int
has_error : Bool
}

The state of a parse operation.

#
Parser

type Parser

#
Parser::included_ranges

fn Parser::included_ranges(self : Parser) -> Array[Range]

Get the ranges of text that the parser will include when parsing.

#
Parser::language

fn Parser::language(self : Parser) -> Language?

Get the parser's current language.

#
Parser::logger

fn Parser::logger(self : Parser) -> Logger

Get the parser's current logger.

#
Parser::new

fn Parser::new() -> Parser

Create a new parser.

#
Parser::parse

fn[Encoding : DecodeFunction] Parser::parse(self : Parser, old_tree? : Tree, input : Input[Encoding], options? : ParseOptions) -> Tree raise ParseError

Use the parser to parse some source code and create a syntax tree.

If you are parsing this document for the first time, pass None for the old_tree parameter. Otherwise, if you have already parsed an earlier version of this document and the document has since been edited, pass the previous syntax tree so that the unchanged parts of it can be reused. This will save time and memory. For this to work correctly, you must have already edited the old syntax tree using the Tree::edit function in a way that exactly matches the source code changes.

The Input parameter lets you specify how to read the text. It has the following fields:
  1. read: A function to retrieve a chunk of text at a given byte offset and (row, column) position. The function should return a pointer to the text and write its length to the bytes_read pointer. The parser does not take ownership of this buffer; it just borrows it until it has finished reading it. The function should write a zero value to the bytes_read pointer to indicate the end of the document.
  2. decode: A function to decode the text. This is only used if the encoding is Custom. Additionally, you can pass InputEncoding::UTF8 or InputEncoding::UTF16 to the Input parameter to specify the encoding of the text.

This function returns a syntax tree on success, and None on failure. There are four possible reasons for failure:
  1. The parser does not have a language assigned. Check for this using the Parser::language function.
  2. Parsing was cancelled due to a timeout that was set by an earlier call to the Parser::set_timeout_micros function. You can resume parsing from where the parser left out by calling Parser::parse again with the same arguments. Or you can start parsing from scratch by first calling Parser::reset.
  3. Parsing was cancelled using a cancellation flag that was set by an earlier call to Parser::set_cancellation_flag. You can resume parsing from where the parser left out by calling Parser::parse again with the same arguments.
  4. Parsing was cancelled due to the progress callback returning true. This callback is passed as the options argument inside the ParseOptions struct.

#
Parser::parse_bytes

fn Parser::parse_bytes(self : Parser, old_tree? : Tree, bytes : Bytes, encoding~ : InputEncoding) -> Tree raise ParseError

Use the parser to parse some source code stored in one contiguous buffer with a given encoding. The first three parameters work the same as in the parse method. The final parameter indicates whether the text is encoded as UTF8 or UTF16.

#
Parser::parse_string

fn Parser::parse_string(self : Parser, old_tree? : Tree, string : StringView) -> Tree raise ParseError

Use the parser to parse some source code stored in one contiguous string buffer. The first two parameters are the same as in the parse function. The final parameter is the string to parse.

#
Parser::reset

fn Parser::reset(self : Parser) -> Unit

Instruct the parser to start the next parse from the beginning.

If the parser previously failed because of a timeout or a cancellation, then by default, it will resume where it left off on the next call to parse or other parsing functions. If you don't want to resume, and instead intend to use this parser to parse some other document, you must call reset first.

#
Parser::set_included_ranges

fn Parser::set_included_ranges(self : Parser, ranges : Array[Range]) -> Bool

Set the ranges of text that the parser should include when parsing.

By default, the parser will always include entire documents. This function allows you to parse only a portion of a document but still return a syntax tree whose ranges match up with the document as a whole. You can also pass multiple disjoint ranges.

The second and third parameters specify the location and length of an array of ranges.

If count is zero, then the entire document will be parsed. Otherwise, the given ranges must be ordered from earliest to latest in the document, and they must not overlap. That is, the following must hold for all:

i < count - 1: ranges[i].end_byte <= ranges[i + 1].start_byte

If this requirement is not satisfied, the operation will fail, the ranges will not be assigned, and this function will return false. On success, this function returns true

#
Parser::set_language

fn Parser::set_language(self : Parser, language : Language) -> Unit raise LanguageError

Set the language that the parser should use for parsing.

Returns a boolean indicating whether or not the language was successfully assigned. True means assignment succeeded. False means there was a version mismatch: the language was generated with an incompatible version of the Tree-sitter CLI. Check the language's ABI version using Language::abi_version and compare it to this library's LANGUAGE_VERSION and MIN_COMPATIBLE_LANGUAGE_VERSION constants.

#
Parser::set_logger

fn Parser::set_logger(self : Parser, logger : Logger) -> Unit

Set the logger that a parser should use during parsing.

The parser does not take ownership over the logger payload. If a logger was previously assigned, the caller is responsible for releasing any memory owned by the previous logger.

#
Point

type Point

impl Show for Point

#
Point::column

fn Point::column(self : Point) -> Int

#
Point::new

fn Point::new(row : Int, column : Int) -> Point

#
Point::row

fn Point::row(self : Point) -> Int

#
Quantifier

pub enum Quantifier {
Zero
ZeroOrOne
ZeroOrMore
One
OneOrMore
} derive(Show)

#
Query

type Query

#
Query::capture_count

fn Query::capture_count(self : Query) -> Int

Get the number of captures in the query.

#
Query::capture_name_for_id

fn Query::capture_name_for_id(self : Query, capture_id : Int) -> String

Get the name of one of the query's captures. Each capture is associated with a numeric id based on the order that it appeared in the query's source.

#
Query::capture_quantifier_for_id

fn Query::capture_quantifier_for_id(self : Query, pattern_index : Int, capture_index : Int) -> Quantifier

Get the quantifier of the query's captures. Each capture is associated with a numeric id based on the order that it appeared in the query's source.

#
Query::captures

fn Query::captures(self : Query, node : Node) -> Iter[QueryCapture]

#
Query::disable_capture

fn Query::disable_capture(self : Query, name : StringView) -> Unit

Disable a certain capture within a query.

This prevents the capture from being returned in matches, and also avoids any resource usage associated with recording the capture. Currently, there is no way to undo this.

#
Query::disable_pattern

fn Query::disable_pattern(self : Query, pattern_index : Int) -> Unit

Disable a certain pattern within a query.

This prevents the pattern from matching and removes most of the overhead associated with the pattern. Currently, there is no way to undo this.

#
Query::end_byte_for_pattern

fn Query::end_byte_for_pattern(self : Query, pattern_index : Int) -> Int

Get the byte offset where the given pattern ends in the query's source.

This can be useful when combining queries by concatenating their source code strings.

#
Query::is_pattern_guaranteed_at_step

fn Query::is_pattern_guaranteed_at_step(self : Query, byte_offset : Int) -> Bool

Check if a given pattern is guaranteed to match once a given step is reached. The step is specified by its byte offset in the query's source code.

#
Query::is_pattern_non_local

fn Query::is_pattern_non_local(self : Query, pattern_index : Int) -> Bool

Check if the given pattern in the query is 'non local'.

A non-local pattern has multiple root nodes and can match within a repeating sequence of nodes, as specified by the grammar. Non-local patterns disable certain optimizations that would otherwise be possible when executing a query on a specific range of a syntax tree.

#
Query::is_pattern_rooted

fn Query::is_pattern_rooted(self : Query, pattern_index : Int) -> Bool

Check if the given pattern in the query has a single root node.

#
Query::matches

fn Query::matches(self : Query, node : Node) -> Iter[QueryMatch]

#
Query::new

fn Query::new(language : Language, source : StringView) -> Query raise QueryError

Create a new query from a string containing one or more S-expression patterns. The query is associated with a particular language, and can only be run on syntax nodes parsed with that language.

If all of the given patterns are valid, this returns a Query. If a pattern is invalid, this raises a QueryError.

#
Query::pattern_count

fn Query::pattern_count(self : Query) -> Int

Get the number of patterns in the query.

#
Query::predicates_for_pattern

fn Query::predicates_for_pattern(self : Query, pattern_index : Int) -> Array[Array[QueryPredicateStep]]

Get all of the predicates for the given pattern in the query.

The predicates are represented as a single array of array of steps. There are two types of steps in this array:
  • QueryPredicateStep::Capture - Steps with this type represent names of captures. Their value_id can be used with the Query::capture_name_for_id function to obtain the name of the capture.
  • QueryPredicateStep::String - Steps with this type represent literal strings. Their value_id can be used with the Query::string_value_for_id function to obtain their string value.

#
Query::start_byte_for_pattern

fn Query::start_byte_for_pattern(self : Query, pattern_index : Int) -> Int

Get the byte offset where the given pattern starts in the query's source.

This can be useful when combining queries by concatenating their source code strings.

#
Query::string_count

fn Query::string_count(self : Query) -> Int

Get the number of string literals in the query.

#
Query::string_value_for_id

fn Query::string_value_for_id(self : Query, string_id : Int) -> String?

Get the value of one of the query's string literals. Each string is associated with a numeric id based on the order that it appeared in the query's source.

#
QueryCapture

type QueryCapture

#
QueryCapture::index

fn QueryCapture::index(self : QueryCapture) -> Int

#
QueryCapture::name

fn QueryCapture::name(self : QueryCapture) -> String

#
QueryCapture::node

fn QueryCapture::node(self : QueryCapture) -> Node

#
QueryCursor

type QueryCursor

#
QueryCursor::captures

fn QueryCursor::captures(self : QueryCursor) -> Iter[QueryCapture]

#
QueryCursor::did_exceed_match_limit

fn QueryCursor::did_exceed_match_limit(self : QueryCursor) -> Bool

Check if the query cursor exceeded its match limit.

Query cursors have an optional maximum capacity for storing lists of in-progress captures. If this capacity is exceeded, then the earliest-starting match will silently be dropped to make room for further matches. This maximum capacity is optional — by default, query cursors allow any number of pending matches, dynamically allocating new space for them as needed as the query is executed.

#
QueryCursor::exec

fn QueryCursor::exec(self : QueryCursor, query : Query, node : Node, options? : QueryCursorOptions) -> Unit

Start running a given query on a given node, with optional options.

#
QueryCursor::match_limit

fn QueryCursor::match_limit(self : QueryCursor) -> Int

Get the maximum number of in-progress matches allowed by this query cursor.

See QueryCursor::did_exceed_match_limit.

#
QueryCursor::matches

fn QueryCursor::matches(self : QueryCursor) -> Iter[QueryMatch]

#
QueryCursor::new

Create a new cursor for executing a given query.

The cursor stores the state that is needed to iteratively search for matches. To use the query cursor, first call QueryCursor::exec to start running a given query on a given syntax node. Then, there are two options for consuming the results of the query:
  1. Repeatedly call QueryCursor::next_match to iterate over all of the matches in the order that they were found. Each match contains the index of the pattern that matched, and an array of captures. Because multiple patterns can match the same set of nodes, one match may contain captures that appear before some of the captures from a previous match.
  2. Repeatedly call QueryCursor::next_capture to iterate over all of the individual captures in the order that they appear. This is useful if don't care about which pattern matched, and just want a single ordered sequence of captures.

If you don't care about consuming all of the results, you can stop calling QueryCursor::next_match or QueryCursor::next_capture at any point. You can then start executing another query on another node by calling QueryCursor::exec again.

#
QueryCursor::next_capture

fn QueryCursor::next_capture(self : QueryCursor) -> QueryCapture?

Advance to the next capture of the currently running query.

If there is a capture, returns Some(capture). Otherwise, returns None.

#
QueryCursor::next_match

fn QueryCursor::next_match(self : QueryCursor) -> QueryMatch?

Advance to the next match of the currently running query.

If there is a match, returns Some(match). Otherwise, returns None.

#
QueryCursor::remove_match

fn QueryCursor::remove_match(self : QueryCursor, match_id : Int) -> Unit

Remove a match from the query cursor's results.

#
QueryCursor::set_byte_range

fn QueryCursor::set_byte_range(self : QueryCursor, start_byte : Int, end_byte : Int) -> Unit

Set the range of bytes in which the query will be executed.

The query cursor will return matches that intersect with the given byte range. This means that a match may be returned even if some of its captures fall outside the specified range, as long as at least part of the match overlaps with the range.

#
QueryCursor::set_match_limit

fn QueryCursor::set_match_limit(self : QueryCursor, limit : Int) -> Unit

Set the maximum number of in-progress matches allowed by this query cursor.

See QueryCursor::did_exceed_match_limit.

#
QueryCursor::set_max_start_depth

fn QueryCursor::set_max_start_depth(self : QueryCursor, max_start_depth : Int) -> Unit

Set the maximum start depth for a query cursor.

This prevents cursors from exploring children nodes at a certain depth. Note if a pattern includes many children, then they will still be checked.

The zero max start depth value can be used as a special behavior and it helps to destructure a subtree by staying on a node and using captures for interested parts. Note that the zero max start depth only limit a search depth for a pattern's root node but other nodes that are parts of the pattern may be searched at any depth what defined by the pattern structure.

Set to @uint.max_value to remove the maximum start depth.

#
QueryCursor::set_point_range

fn QueryCursor::set_point_range(self : QueryCursor, start_point : Point, end_point : Point) -> Unit

Set the range of (row, column) positions in which the query will be executed.

The query cursor will return matches that intersect with the given point range. This means that a match may be returned even if some of its captures fall outside the specified range, as long as at least part of the match overlaps with the range.

#
QueryCursorOptions

type QueryCursorOptions

#
QueryCursorOptions::new

fn QueryCursorOptions::new(progress_callback~ : (QueryCursorState) -> Unit) -> QueryCursorOptions

#
QueryCursorState

pub struct QueryCursorState {
current_byte_offset : Int
}

#
QueryMatch

type QueryMatch

#
QueryMatch::captures

fn QueryMatch::captures(self : QueryMatch) -> Iter[QueryCapture]

#
QueryMatch::id

fn QueryMatch::id(self : QueryMatch) -> Int

#
QueryMatch::pattern_index

fn QueryMatch::pattern_index(self : QueryMatch) -> Int

#
QueryMatch::predicates

fn QueryMatch::predicates(self : QueryMatch) -> Array[Array[QueryPredicateStep]]

#
QueryPredicateStep

pub enum QueryPredicateStep {
Capture(String)
String(String)
}

#
Range

type Range

impl Show for Range

#
Range::end_byte

fn Range::end_byte(self : Range) -> Int

#
Range::end_point

fn Range::end_point(self : Range) -> Point

#
Range::new

fn Range::new(start_point : Point, end_point : Point, start_byte : Int, end_byte : Int) -> Range

#
Range::start_byte

fn Range::start_byte(self : Range) -> Int

#
Range::start_point

fn Range::start_point(self : Range) -> Point

#
StateId

type StateId

#
Symbol

type Symbol

#
SymbolType

pub enum SymbolType {
Regular
Anonymous
Supertype
Auxiliary
}

Check whether the given node type id belongs to named nodes, anonymous nodes, or a hidden nodes.

#
Tree

type Tree

#
Tree::copy

fn Tree::copy(self : Tree) -> Tree

Create a shallow copy of the syntax tree. This is very fast.

You need to copy a syntax tree in order to use it on more than one thread at a time, as syntax trees are not thread safe.

#
Tree::edit

fn Tree::edit(self : Tree, edit : InputEdit) -> Unit

Edit the syntax tree to keep it in sync with source code that has been edited.

You must describe the edit both in terms of byte offsets and in terms of (row, column) coordinates.

#
Tree::get_changed_ranges

fn Tree::get_changed_ranges(self : Tree, other : Tree) -> Array[Range]

Compare an old edited syntax tree to a new syntax tree representing the same document, returning an array of ranges whose syntactic structure has changed.

For this to work correctly, the old syntax tree must have been edited such that its ranges match up to the new tree. Generally, you'll want to call this function right after calling one of the Parser::parse functions. You need to pass the old tree that was passed to parse, as well as the new tree that was returned from that function.

The returned ranges indicate areas where the hierarchical structure of syntax nodes (from root to leaf) has changed between the old and new trees. Characters outside these ranges have identical ancestor nodes in both trees.

Note that the returned ranges may be slightly larger than the exact changed areas, but Tree-sitter attempts to make them as small as possible.

#
Tree::included_ranges

fn Tree::included_ranges(self : Tree) -> Array[Range]

Get the array of included ranges that was used to parse the syntax tree.

#
Tree::language

fn Tree::language(self : Tree) -> Language

Get the language that was used to parse the syntax tree.

#
Tree::query

fn Tree::query(self : Tree, source : StringView) -> QueryCursor raise QueryError

#
Tree::root_node

fn Tree::root_node(self : Tree) -> Node

Get the root node of the syntax tree.

#
Tree::root_node_with_offset

fn Tree::root_node_with_offset(self : Tree, offset_bytes : Int, offset_extent : Point) -> Node

Get the root node of the syntax tree, but with its position shifted forward by the given offset.

#
Tree::walk

fn Tree::walk(self : Tree) -> TreeCursor

#
TreeCursor

type TreeCursor

#
TreeCursor::copy

fn TreeCursor::copy(self : TreeCursor) -> TreeCursor

#
TreeCursor::current_depth

fn TreeCursor::current_depth(self : TreeCursor) -> Int

Get the depth of the cursor's current node relative to the original node that the cursor was constructed with.

#
TreeCursor::current_descendant_index

fn TreeCursor::current_descendant_index(self : TreeCursor) -> Int

Get the index of the cursor's current node out of all of the descendants of the original node that the cursor was constructed with.

#
TreeCursor::current_field_id

fn TreeCursor::current_field_id(self : TreeCursor) -> FieldId

Get the field id of the tree cursor's current node.

This returns zero if the current node doesn't have a field. See also Node::child_by_field_id, Language::field_id_for_name.

#
TreeCursor::current_field_name

fn TreeCursor::current_field_name(self : TreeCursor) -> String?

Get the field name of the tree cursor's current node.

This returns None if the current node doesn't have a field. See also Node::child_by_field_name.

#
TreeCursor::current_node

fn TreeCursor::current_node(self : TreeCursor) -> Node

Get the tree cursor's current node.

#
TreeCursor::goto_descendant

fn TreeCursor::goto_descendant(self : TreeCursor, goal_descendant_index : Int) -> Unit

Move the cursor to the node that is the nth descendant of the original node that the cursor was constructed with, where zero represents the original node itself.

#
TreeCursor::goto_first_child

fn TreeCursor::goto_first_child(self : TreeCursor) -> Bool

Move the cursor to the first child of its current node.

This returns true if the cursor successfully moved, and returns false if there were no children.

#
TreeCursor::goto_first_child_for_byte

fn TreeCursor::goto_first_child_for_byte(self : TreeCursor, goal_byte : Int) -> Bool

Move the cursor to the first child of its current node that contains or starts after the given byte offset.

This returns the index of the child node if one was found, and returns -1 if no such child was found.

#
TreeCursor::goto_first_child_for_point

fn TreeCursor::goto_first_child_for_point(self : TreeCursor, goal_point : Point) -> Bool

Move the cursor to the first child of its current node that contains or starts after the given point.

This returns the index of the child node if one was found, and returns -1 if no such child was found.

#
TreeCursor::goto_last_child

fn TreeCursor::goto_last_child(self : TreeCursor) -> Bool

Move the cursor to the last child of its current node.

This returns true if the cursor successfully moved, and returns false if there were no children.

Note that this function may be slower than TreeCursor::goto_first_child because it needs to iterate through all the children to compute the child's position.

#
TreeCursor::goto_next_sibling

fn TreeCursor::goto_next_sibling(self : TreeCursor) -> Bool

Move the cursor to the next sibling of its current node.

This returns true if the cursor successfully moved, and returns false if there was no next sibling node.

Note that the node the cursor was constructed with is considered the root of the cursor, and the cursor cannot walk outside this node.

#
TreeCursor::goto_parent

fn TreeCursor::goto_parent(self : TreeCursor) -> Bool

Move the cursor to the parent of its current node.

This returns true if the cursor successfully moved, and returns false if there was no parent node (the cursor was already on the root node).

Note that the node the cursor was constructed with is considered the root of the cursor, and the cursor cannot walk outside this node.

#
TreeCursor::goto_previous_sibling

fn TreeCursor::goto_previous_sibling(self : TreeCursor) -> Bool

Move the cursor to the previous sibling of its current node.

This returns true if the cursor successfully moved, and returns false if there was no previous sibling node.

Note, that this function may be slower than TreeCursor::goto_next_sibling due to how node positions are stored. In the worst case, this will need to iterate through all the children up to the previous sibling node to recalculate its position. Also note that the node the cursor was constructed with is considered the root of the cursor, and the cursor cannot walk outside this node.

#
TreeCursor::new

fn TreeCursor::new(node : Node) -> TreeCursor

Create a new tree cursor starting from the given node.

A tree cursor allows you to walk a syntax tree more efficiently than is possible using the Node functions. It is a mutable object that is always on a certain syntax node, and can be moved imperatively to different nodes.

Note that the given node is considered the root of the cursor, and the cursor cannot walk outside this node.

#
TreeCursor::reset

fn TreeCursor::reset(self : TreeCursor, node : Node) -> Unit

Re-initialize a tree cursor to start at the original node that the cursor was constructed with.

#
TreeCursor::reset_to

fn TreeCursor::reset_to(self : TreeCursor, other : TreeCursor) -> Unit

Re-initialize a tree cursor to the same position as another cursor.

Unlike TreeCursor::reset, this will not lose parent information and allows reusing already created cursors.

#
LANGUAGE_VERSION

let LANGUAGE_VERSION : Int

The latest ABI version that is supported by the current version of the library. When Languages are generated by the Tree-sitter CLI, they are assigned an ABI version number that corresponds to the current CLI version. The Tree-sitter library is generally backwards-compatible with languages generated using older CLI versions, but is not forwards-compatible.

#
MIN_COMPATIBLE_LANGUAGE_VERSION

let MIN_COMPATIBLE_LANGUAGE_VERSION : Int

The earliest ABI version that is supported by the current version of the library.

#
parser

fn parser(language : Language) -> Parser raise LanguageError