nvim_runtime_lua

vim.treesitter.LanguageTree

Methods22 

function LanguageTree.new(source: string | integer, lang: string, opts: vim.treesitter.LanguageTree.new.Opts | nil) -> parser vim.treesitter.LanguageTree
Parameters
sourcestring | integer

Buffer or text string to parse

langstring

Root language of this tree

optsvim.treesitter.LanguageTree.new.Opts | nil
Returns
parservim.treesitter.LanguageTree

object

@nodoc

function LanguageTree.invalidate(reload: nil | boolean) -> nil

Invalidates this parser and its children.

Should only be called when the tracked state of the LanguageTree is not valid against the parse tree in treesitter. Doesn't clear filesystem cache. Called often, so needs to be fast.

function LanguageTree.trees() -> {integer, TSTree}

Returns all trees of the regions parsed by this parser. Does not include child languages. The result is list-like if

  • this LanguageTree is the root, in which case the result is empty or a singleton list; or
  • the root LanguageTree is fully parsed.
function LanguageTree.lang() -> string

Gets the language of this tree node.

function LanguageTree.is_valid(exclude_children: nil | boolean, range: Range | Range[] | nil) -> boolean

Returns whether this LanguageTree is valid, i.e., |LanguageTree:trees()| reflects the latest state of the source. If invalid, user should call |LanguageTree:parse()|.

Parameters
exclude_childrennil | boolean

whether to ignore the validity of children (default false)

rangeRange | Range[] | nil

range (or list of ranges, sorted by starting point in ascending order) to check for validity

Returns
boolean
function LanguageTree.children() -> {string, vim.treesitter.LanguageTree}

Returns a map of language to child tree.

function LanguageTree.source() -> string | integer

Returns the source content of the language tree (bufnr or string).

function LanguageTree.parse(range: boolean | Range | Range[] | nil, on_parse: fun(err: nil | string, trees: {integer, TSTree} | nil) -> nil | nil) -> {integer, TSTree} | nil

Recursively parse all regions in the language tree using |treesitter-parsers| for the corresponding languages and run injection queries on the parsed trees to determine whether child trees should be created and parsed.

Any region with empty range ({}, typically only the root tree) is always parsed; otherwise (typically injections) only if it intersects {range} (or if {range} is true).

Parameters
rangeboolean | Range | Range[] | nil

: Parse this range (or list of ranges, sorted by starting point in ascending order) in the parser's source. Set to true to run a complete parse of the source (Note: Can be slow!) Set to false|nil to only parse regions with empty ranges (typically only the root tree without injections).

on_parsefun(err: nil | string, trees: {integer, TSTree} | nil) -> nil | nil

Function invoked when parsing completes. When provided and vim.g._ts_force_sync_parsing is not set, parsing will run asynchronously. The first argument to the function is a string representing the error type, in case of a failure (currently only possible for timeouts). The second argument is the list of trees returned by the parse (upon success), or nil if the parse timed out (determined by 'redrawtime').

If parsing was still able to finish synchronously (within 3ms), parse() returns the list of trees. Otherwise, it returns nil.

Returns
{integer, TSTree} | nil
function LanguageTree._subtract_time(thread_state: ParserThreadState, time: integer) -> nil
 
function LanguageTree.for_each_tree(fn: fun(tree: TSTree, ltree: vim.treesitter.LanguageTree) -> nil) -> nil

Invokes the callback for each |LanguageTree| recursively.

Note: This includes the invoking tree's child trees as well.

function LanguageTree.parent() -> vim.treesitter.LanguageTree | nil

Returns the parent tree. nil for the root tree.

function LanguageTree.destroy() -> nil

Destroys this |LanguageTree| and all its children.

Any cleanup logic should be performed here.

Note: This DOES NOT remove this tree from a parent. Instead, remove_child must be called on the parent to remove it.

function LanguageTree.included_regions() -> {integer, Range6[]}

Gets the set of included regions managed by this LanguageTree. This can be different from the regions set by injection query, because a partial |LanguageTree:parse()| drops the regions outside the requested range. Each list represents a range in the form of { {startrow}, {startcol}, {startbytes}, {endrow}, {endcol}, {endbytes} }.

function LanguageTree._on_bytes(buf: integer, changed_tick: integer, start_row: integer, start_col: integer, start_byte: integer, old_row: integer, old_col: integer, old_byte: integer, new_row: integer, new_col: integer, new_byte: integer) -> nil
 
function LanguageTree._on_reload() -> nil
 
function LanguageTree._on_detach(...) -> nil
 
function LanguageTree.register_cbs(cbs: {TSCallbackNameOn, function}, recursive: nil | boolean) -> nil

Registers callbacks for the [LanguageTree].

Parameters
cbs{TSCallbackNameOn, function}

An [nvimbufattach()]-like table argument with the following handlers:

  • on_bytes : see [nvimbufattach()].
  • on_changedtree : a callback that will be called every time the tree has syntactical changes.

    • It will be passed two arguments: a table of the ranges (as node ranges) that changed and the changed tree.

  • on_child_added : emitted when a child is added to the tree.
  • on_child_removed : emitted when a child is removed from the tree.
  • on_detach : emitted when the buffer is detached, see [nvimbufdetach_event].

    • Takes one argument, the number of the buffer.

recursivenil | boolean

Apply callbacks recursively for all children. Any new children will also inherit the callbacks.

Returns
nil
function LanguageTree.contains(range: Range4) -> boolean

Determines whether {range} is contained in the |LanguageTree|.

function LanguageTree.tree_for_range(range: Range4, opts: vim.treesitter.LanguageTree.tree_for_range.Opts | nil) -> TSTree | nil

Gets the tree that contains {range}.

function LanguageTree.node_for_range(range: Range4, opts: vim.treesitter.LanguageTree.tree_for_range.Opts | nil) -> TSNode | nil

Gets the smallest node that contains {range}.

function LanguageTree.named_node_for_range(range: Range4, opts: vim.treesitter.LanguageTree.tree_for_range.Opts | nil) -> TSNode | nil

Gets the smallest named node that contains {range}.

function LanguageTree.language_for_range(range: Range4) -> tree vim.treesitter.LanguageTree

Gets the appropriate language that contains {range}.

Parameters
rangeRange4
Returns
treevim.treesitter.LanguageTree

Managing {range}

Fields2

LanguageTree._logger : fun(logtype: string, msg: string) -> nil | nil
 
LanguageTree.__index : vim.treesitter.LanguageTree