The current language ABI version supported by the used version of tree-sitter

The minimum language ABI version supported by the used version of tree-sitter

Load a language from a given file Keep in mind that this includes the .so, .dll, or .dynlib extension On Unix this uses dlopen, on Windows this uses LoadLibrary so if a path without a path separator is given, these functions have their own path's that they will search for your file in. So if in doubt use a file path like

local my_language = ltreesitter.load("./my_parser.so", "my_language")

Search package.cpath for a parser with the filename library_file_name.so or parsers/library_file_name.so (or .dll on Windows) and try to load the symbol tree_sitter_'language_name' language_name is optional and will be set to library_file_name if not provided. So if you want to load a Lua parser from a file named lua.so then use ltreesitter.require("lua") But if you want to load a Lua parser from a file named parser.so then use ltreesitter.require("parser", "lua") Like the regular require, this will error if the parser is not found or the symbol couldn't be loaded. Use either pcall or ltreesitter.load to not error out on failure. Returns the language and the path it was loaded from.

local my_language, loaded_from = ltreesitter.require("my_language")
print(my_language:name(), loaded_from) -- "my_language", /home/user/.luarocks/lib/lua/5.4/parsers/my_language.so
-- etc.

The version of the tree-sitter library ltreesitter was built with

The version of ltreesitter

Get the ABI version number for the given parser's language

Get the number of distinct field names in the given parser's language

Get the numeric id for the given field name

Get the metadata for the given language. This information relies on the language author providing the correct data in the language's tree-sitter.json May return nil

Get the name of the language. May return nil.

Get the name for a numeric field id

Get the next parse state

Create a parser of the given language

Create a query out of the given string for this language

Get the number of valid states in the given language

Get a list of all supertype symbols for the given language

Get a list of all supertype symbols for the given language

Get the number of distinct node types in the given language

Get the numerical id for the given node type string

Get a node type string for the given symbol id

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

Get the node's zero_index'th child (0-indexed)

Get a node's child given a field id

Get a node's child given a field name

Get the number of children a node has

Get the node that contains descendant. Can return descendant itself

Iterate over a node's children

Create a new tree cursor at the given node

Returns the number of descendants this node has

Returns the smallest descendant node that spans the given range

Returns the smallest descendant node that spans the given range

Create an edit to the given node

Create an edit to the given node

Create an edit to the given node

Get the byte offset of the source string that the given node ends at (exclusive)

Get the inclusive 1-index of the source string that the given node ends at

Get the row and column of where the given node ends

Returns the field name for the child at the given zero index (if any)

Returns the field name for the named child at the given zero index (if any)

Returns the first child that contains or starts after the given byte offset

Returns the first named child that contains or starts after the given byte offset

Returns the type of a given node as a numeric id as it appears in the grammar ignoring aliases This is what should be used in Parser:language_next_state() instead of Node:symbol

Returns the type of a given node as a string as it appears in the grammar ignoring aliases

Returns true when the node has been changed by an edit

Returns true when the node is an error

Returns the language used to parse the Node

Get whether or not the current node is extra

Get whether or not the current node is missing

Get whether or not the current node is named

Returns the language used to parse the Node

Get the node's zero_index'th named child

Get the number of named children a node has

Iterate over a node's named children

Returns the smallest named descendant node that spans the given range

Returns the smallest named descendant node that spans the given range

Get a node's next named sibling

Get the parse state after this node

Get a node's next sibling

Returns the parent of a given node. It is recommended to use Node.child_with_descendant for iterating over ancestors

Get this node's parse state

Get a node's previous named sibling

Get a node's previous sibling

Get the substring of the source that was parsed to create Node

Get the byte offset of the source string that the given node starts at

Get the inclusive 1-index of the source string that the given node starts at

Get the row and column of where the given node starts

Returns the type of a given node as a numeric id

Get the type of the given node

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

Get the language associated with this parser

Uses the given parser to parse the string If Tree is provided then it will be used to create a new updated tree (but it is the responsibility of the programmer to make the correct Tree:edit calls)

reader should be a function that takes a zero-based byte offset and a Point and returns the text at that point. The function should return either nil or an empty string to signal that there is no more text.

progress_callback should be a function that takes a boolean signalling if an error has occurred, and an integer byte offset. This function will be called intermittently while parsing and may return true to cancel parsing.

A Tree can be provided to reuse parts of it for parsing, provided that Tree:edit has been called previously

encoding defaults to "utf-8" when not provided.

May return nil if the progress callback cancelled parsing.

Set the file that the parser should dump debugging DOT graphs to during parsing.

Reset the parser, causing the next parse to start from the beginning

Sets the ranges that Parser will include when parsing, so you don't have to parse an entire document, but the ranges in the tree will still match the document. The array of Ranges must satisfy the following relationship: for a positive integer i within the length of ranges: {Range}:

ranges[i].end_byte <= ranges[i + 1].start_byte

returns whether or not setting the range succeeded

Iterate over the captures of a given query in Node, name pairs.
start and end are optional.
They must be passed together with the same type, describing either two bytes or two points.
If passed, the query will be executed within the range denoted.
If not passed, the default behaviour is to execute the query through the entire range of the node.

local q = parser:query[[ (comment) @my_match ]]
for capture, name in q:capture(node) do
   print(capture, name) -- => (comment), "my_match"
end

Returns the number of captures this query has

Create a query cursor from the given query, executing over the given node.

Disable a certain capture within a query, preventing it from being returned in matches. Currently there is no way to undo this.

Disable a certain pattern within a query, preventing it from being returned in matches. Currently there is no way to undo this.

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

Runs a query. That's it. Nothing more, nothing less.

This is intended to be used with predicates that have side effects, i.e. for when you would use Query.match or Query.capture, but do nothing in the for loop.

start and end are optional.
They must be passed together with the same type, describing either two bytes or two points.
If passed, the query will be executed within the range denoted.
If not passed, the default behaviour is to execute the query through the entire range of the node.

local parser = ltreesitter.require("teal"):parser()

-- grab a node to query against
local root_node = parser:parse_string[[
   local x: string = "foo"
   local y: string = "bar"
]]:root()

parser
   :query[[(
      (var_declaration
         (var) @var-name
         (string) @value)
      (#set! @var-name @value)
   )]]
   :exec(root_node, {["set!"] = function(a, b) _G[a] = b:sub(2, -2) end})

print(x) -- => foo
print(y) -- => bar

If you'd like to interact with the matches/captures of a query, see the Query.match and Query.capture iterators

Returns whether the pattern at the given index is guaranteed to match when it is reached

Returns whether the pattern at the given index is non-local

Returns whether the pattern at the given index is rooted

Iterate over the matches of a given query. start and end are optional. They must be passed together with the same type, describing either two bytes or two points. If passed, the query will be executed within the range denoted. If not passed, the default behaviour is to execute the query through the entire range of the node.
The match object is a record populated with all the information given by treesitter

interface Match
   id: integer
   pattern_index: integer
   capture_count: integer
   captures: {string:Node|{Node}}
end

If a capture can only contain at most one node (as is the case with regular (node) @capture-name patterns and (node)? @capture-name patterns), it will either be nil or that Node. If a capture can contain multiple nodes (as is the case with (node)* @capture-name and (node)+ @capture-name patterns) it will either be nil or an array of Node Example:

local q = parser:query[[ (comment) @my_match ]]
for match in q:match(node) do
   print(match.captures.my_match)
end

predicates is a map of functions to determine whether a query matches and/or execute side effects Predicates that end in a '?' character will be seen as conditions that must be met for the pattern to be matched. Predicates that don't will be seen just as functions to be executed given the matches provided. Additionally, you will not have access to the return values of these functions, if you'd like to keep the results of a computation, make your functions have side-effects to write somewhere you can access.

By default the following predicates are provided.

• (#eq? ...) will match if all arguments provided are equal
• (#not-eq? a b) will match if the two arguments provided are not equal
• (#match? text pattern) will match the provided text matches the given pattern. Matches are determined by Lua's standard string.match function.
• (#not-match? text pattern) inverse of match?
• (#find? text substring) will match if text contains substring. The substring is found with Lua's standard string.find, but the search always starts from the beginning, and pattern matching is disabled. This is equivalent to string.find(text, substring, 0, true)
• (#not-find? text substring) inverse of find?

Predicate evaluation order:

Since predicates that end with a ? affect whether a node matches, these are run first, in the order they appear in the query's source. Once all ? queries are run, all the non-? queries are run in the order they appear in the query's source.

Example:
The following snippet will match lua functions that have a single LDoc/EmmyLua style comment above them

local parser = ltreesitter.require("lua"):parser()

-- grab a node to query against
local root_node = parser:parse_string[[
   ---@Doc this does stuff
   local function stuff_doer()
      do_stuff()
   end
]]:root()

for match in parser
   :query[[(
      (comment) @the-comment
      .
      (function_definition
         (function_name) @the-function-name)
      (#is-doc-comment? @the-comment)
   )]]
   :match(root_node, {
      ["is-doc-comment?"] = function(str)
         return str:source():sub(1, 4) == "---@"
      end
   })
do
   print("Function: " .. match.captures["the-function-name"] .. " has documentation")
   print("   " .. match.captures["the-comment"])
end

Returns the number of patterns this query has

Given a pattern index, return an array representing each predicate Each predicate is an array of either strings, representing literal strings in the predicate, or a table with a capture_name field, representing a @capture in the predicate. e.g. Given a (c) query like with source:

local q = c:query [[
  ((_ declarator: (identifier) @name)
   (#match? @name "[a-z]+")
   (#set! @name true))
]]

q:predicates_for_pattern(0) would return:

{
   { "match?", { capture_name = "name" }, "[a-z]+" },
   { "set!", { capture_name = "name" }, "true" },
}

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

Returns the number of strings this query has

Returns true if the given cursor exceeded its match limit. See set_match_limit and match_limit

Get the match limit of the given cursor. See set_match_limit and did_exceed_match_limit

Find the next capture of the given cursor. As implied by the name, this does NOT execute any predicates. See Query.predicates_for_pattern or Query.capture for executing predicates.

Find the next match of the given cursor. As implied by the name, this does NOT execute any predicates. See Query.predicates_for_pattern or Query.match for executing predicates.

Prevent the given query cursor from matching the given match id

returns true when the given range was non-empty

Set the byte range within which all matches must be fully contained.

Set the byte range within which all matches must be fully contained.

Set the maximum number of in-progress matches allowed by this query cursor. Set to nil to set to the maximum limit (2^32-1)

Set the maximum start depth of the given cursor. Set to nil to set the maximum. This prevents cursors from exploring children nodes at a certain depth.

returns true when the given range was non-empty

Creates a copy of the tree. Tree-sitter recommends to create copies if you are going to use multithreading since tree accesses are not thread-safe, but copying them is cheap and quick

Create an edit to the given tree

Create an edit to the given tree

Create an edit to the given tree

Compare an old syntax tree to a new syntax tree. This would usually be called right after a set of calls to Tree.edit(_s) and Parser.parse_{string,with}

Returns the array of ranges used to parse the syntax tree

Returns the language used to parse the tree

Write a DOT graph to the given file. Defaults to standard error.

Returns the root node of the given parse tree

Returns the root node of the given parse tree, but with its position shifted forward

Create a copy of the given cursor

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

Get the cursor's current node index

Get the field id of the given cursor's current node
May return nil

Get the field name of the current node under the cursor

Get the current node under the cursor

Move the cursor to the nth descendant of the original node this cursor was constructed with. Zero represents the original node itself.

Position the cursor at the first child of the current node Returns true if the cursor was able to move

Move the given cursor to the first child of its current node that contains or starts after the given offset Returns the index of the child node or nil if no such child was found

Move the given cursor to the first child of its current node that contains or starts after the given point Returns the index of the child node or nil if no such child was found

Position the cursor at the first child of the current node Returns true if the cursor was able to move

Position the cursor at the next sibling of the current node Returns true if there was a sibling to move to

Position the cursor at the parent of the current node

Position the cursor at the sibling of the current node Returns true if there was a sibling to move to

Position the cursor at the given node

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