En esta página

Guidedog / Documentación 0.2.0

treesitter

Package treesitter is a thin binding of the tree-sitter C library and its Python grammar: parsers, trees, nodes, and cursors, and nothing more. It imports only Odin’s own packages, so any Odin program can use it; Guidedog’s autodoc reads Python source through it.

Types

treesitter.Cursor :: struct

Cursor is TSTreeCursor; cursor_delete frees it.

tree: rawptr

id: rawptr

ctx: [3]u32

treesitter.Field_Id :: u16

treesitter.Iterator :: struct

Iterator visits a node’s children in order, named or all, for for child in ....

node: Node

index: int

count: int

named: bool

treesitter.Language :: struct

treesitter.Node :: struct

Node is TSNode, a value that is valid while its tree lives.

ctx: [4]u32

id: rawptr

tree: ^Tree

treesitter.Parser :: struct

Opaque handles.

treesitter.Point :: struct

row: u32

column: u32

in bytes

treesitter.Symbol :: u16

treesitter.Tree :: struct

Procedures

treesitter.abi_version :: proc(l: ^Language) -> int

abi_version is the grammar’s ABI, which the runtime must support.

treesitter.child :: proc(n: Node, i: int) -> Node

child is the node’s child i of child_count, or a null node.

treesitter.child_count :: proc(n: Node) -> int

child_count counts the node’s children, named and anonymous.

treesitter.children :: proc(n: Node, named := true) -> Iterator

children iterates n’s children, named ones only unless named is false, with next_child.

treesitter.cursor_delete :: proc(c: ^Cursor)

cursor_delete frees what cursor_new allocated.

treesitter.cursor_field_name :: proc(c: ^Cursor) -> string

cursor_field_name names the field the cursor’s node fills in its parent, or «».

treesitter.cursor_first_child :: proc(c: ^Cursor) -> bool

cursor_first_child moves to the first child; false, and no move, when there is none.

treesitter.cursor_new :: proc(n: Node) -> Cursor

cursor_new starts a cursor at n, for walks that allocate nothing per step. tree-sitter allocates the cursor’s stack; the caller frees it with cursor_delete.

treesitter.cursor_next_sibling :: proc(c: ^Cursor) -> bool

cursor_next_sibling moves to the next sibling; false, and no move, when there is none.

treesitter.cursor_node :: proc(c: ^Cursor) -> Node

cursor_node is the node the cursor is at.

treesitter.cursor_parent :: proc(c: ^Cursor) -> bool

cursor_parent moves to the parent; false, and no move, at the node the cursor started at.

treesitter.deeper_than :: proc(n: Node, limit: int) -> bool

deeper_than reports whether the tree below n nests more than limit levels (n’s children are level 1). Parsing needs no recursion however deep the source nests, but recursive walks over the tree do: a program checks first, and refuses trees deeper than its walks can hold. It walks with a cursor, so it needs no recursion itself.

treesitter.end_byte :: proc(n: Node) -> int

end_byte is the byte offset just past the node in the parsed text.

treesitter.end_point :: proc(n: Node) -> Point

end_point is the 0-based row and byte column where the node ends; see start_point.

treesitter.equal :: proc(a, b: Node) -> bool

equal reports whether a and b are the same node of the same tree.

treesitter.field :: proc(n: Node, name: string) -> Node

field is the child the grammar names, such as «name» or «body»; a null node when absent.

treesitter.field_name_for_child :: proc(n: Node, i: int) -> string

field_name_for_child names the field child i fills, or «».

treesitter.has_error :: proc(n: Node) -> bool

has_error reports whether the node or any node below it is an error or missing node.

treesitter.is_error :: proc(n: Node) -> bool

is_error reports a node the parser could not fit into the grammar.

treesitter.is_extra :: proc(n: Node) -> bool

is_extra: comments and other tokens that may appear anywhere.

treesitter.is_missing :: proc(n: Node) -> bool

is_missing reports a node the parser inserted to recover from a syntax error.

treesitter.is_named :: proc(n: Node) -> bool

is_named reports a node the grammar names, rather than an anonymous token such as «(«.

treesitter.is_null :: proc(n: Node) -> bool

is_null reports a null node: an absent field, child, sibling, or parent.

treesitter.kind :: proc(n: Node) -> string

kind is the node’s type name, such as «function_definition», or the token itself for anonymous nodes such as «(« or «def».

treesitter.named_child :: proc(n: Node, i: int) -> Node

named_child is the node’s named child i of named_child_count, or a null node.

treesitter.named_child_count :: proc(n: Node) -> int

named_child_count counts the node’s named children.

treesitter.next_child :: proc(it: ^Iterator) -> (n: Node, i: int, ok: bool)

next_child returns the next child and its index, for for child, i in next_child(&it).

treesitter.next_named_sibling :: proc(n: Node) -> Node

next_named_sibling is the next named node under n’s parent, or a null node.

treesitter.next_sibling :: proc(n: Node) -> Node

next_sibling is the node after n under its parent, or a null node.

treesitter.parent :: proc(n: Node) -> Node

parent is the node’s parent, or a null node for the root.

treesitter.parse :: proc(p: ^Parser, text: string) -> ^Tree

parse parses UTF-8 text into a tree, which tree-sitter allocates and the caller frees with tree_delete. The tree refers to text by byte offsets only, so text need not outlive it, but text slices whatever text it is given. Nil when parsing was impossible (text over 4 GiB, or no language set); syntax errors give a tree with error nodes instead (has_error).

treesitter.parser_delete :: proc(p: ^Parser)

parser_delete frees a parser from parser_new; nil is ignored. Trees it parsed stay valid.

treesitter.parser_new :: proc(language: ^Language) -> ^Parser

parser_new returns a parser for language, which tree-sitter allocates and the caller frees with parser_delete, or nil when this runtime cannot read the grammar (a shared runtime older than the grammar’s ABI).

treesitter.prev_named_sibling :: proc(n: Node) -> Node

prev_named_sibling is the previous named node under n’s parent, or a null node.

treesitter.prev_sibling :: proc(n: Node) -> Node

prev_sibling is the node before n under its parent, or a null node.

treesitter.python :: proc() -> ^Language

python returns the Python grammar, static data that is never freed.

treesitter.root :: proc(t: ^Tree) -> Node

root is the tree’s root node, valid while the tree lives.

treesitter.start_byte :: proc(n: Node) -> int

start_byte is the byte offset where the node starts in the parsed text.

treesitter.start_point :: proc(n: Node) -> Point

start_point and end_point are 0-based rows and byte columns.

treesitter.symbol :: proc(n: Node) -> Symbol

symbol is the grammar’s number for the node’s type.

treesitter.text :: proc(n: Node, source: string) -> string

text is the source the node spans, a slice of the parsed text.

treesitter.tree_delete :: proc(t: ^Tree)

tree_delete frees a tree from parse, and with it every node of the tree; nil is ignored.

Constants

treesitter.NOTICES :: #load("licenses/tree-sitter.txt", string) + "\n" + #load("licenses/tree-sitter-python.txt", string)

The MIT licence notices of the two libraries, which a program that links them ships.

treesitter.PYTHON_VERSION :: "0.25.0"

treesitter.RUNTIME_VERSION :: "0.26.13"

The versions native/tree-sitter/build.sh pins; a shared build links whatever is installed.

treesitter.STATIC :: #config(TREESITTER_STATIC, BUILT)

Foreign imports

@(extra_linker_flags = #config(TREESITTER_LINK_FLAGS, "")) foreign import treesitter.ts {"../../native/tree-sitter/out/lib/tree-sitter-python.lib", "../../native/tree-sitter/out/lib/tree-sitter.lib"}

@(extra_linker_flags = #config(TREESITTER_LINK_FLAGS, "")) foreign import treesitter.ts {"../../native/tree-sitter/out/lib/libtree-sitter-python.a", "../../native/tree-sitter/out/lib/libtree-sitter.a"}

@(extra_linker_flags = #config(TREESITTER_LINK_FLAGS, "")) foreign import treesitter.ts {"system:tree-sitter-python", "system:tree-sitter"}