nvim_runtime_lua

vim.treesitter

Methods17 

function M._create_parser(buf: integer, lang: string, opts: nil | table) -> object vim.treesitter.LanguageTree

Creates a new parser

It is not recommended to use this; use |get_parser()| instead.

Parameters
bufinteger

Buffer the parser will be tied to (0 for current buffer)

langstring

Language of the parser

optsnil | table

Options to pass to the created language tree

Returns
objectvim.treesitter.LanguageTree

to use for parsing

function M.get_parser(buf: nil | integer, lang: nil | string, opts: nil | table) -> (object vim.treesitter.LanguageTree | nil, error nil | string)

Returns the parser for a specific buffer and attaches it to the buffer

If needed, this will create the parser.

If no parser can be created, nil (and an error message) is returned.

Parameters
bufnil | integer

(default: current buffer) Buffer the parser should be tied to

langnil | string

(default: from 'filetype') Language of this parser

optsnil | table

Options to pass to the created language tree

Returns
objectvim.treesitter.LanguageTree | nil

to use for parsing

errornil | string

message, if applicable

function M.get_string_parser(str: string, lang: string, opts: nil | table) -> object vim.treesitter.LanguageTree

Returns a string parser

Parameters
strstring

Text to parse

langstring

Language of this string

optsnil | table

Options to pass to the created language tree

Returns
objectvim.treesitter.LanguageTree

to use for parsing

function M.is_ancestor(dest: TSNode, source: TSNode) -> True boolean

Determines whether a node is the ancestor of another

Parameters
destTSNode

Possible ancestor

sourceTSNode

Possible descendant

Returns
Trueboolean

if {dest} is an ancestor of {source}

function M.get_node_range(node_or_range: TSNode | Range4) -> (start_row integer, start_col integer, end_row integer, end_col integer)

Returns the node's range or an unpacked range table

Parameters
node_or_rangeTSNode | Range4

Node or table of positions

Returns
start_rowinteger
start_colinteger

(byte offset)

end_rowinteger
end_colinteger

(byte offset)

function M.get_range(node: TSNode, source: nil | string | integer, metadata: vim.treesitter.query.TSMetadata | nil) -> Range6

Get the range of a |TSNode|. Can also supply {source} and {metadata} to get the range with directives applied.

Parameters
nodeTSNode
sourcenil | string | integer

Buffer or string from which the {node} is extracted

metadatavim.treesitter.query.TSMetadata | nil
Returns
Range6
function M.get_node_text(node: TSNode, source: string | integer, opts: nil | table) -> string

Gets the text corresponding to a given node

Parameters
nodeTSNode
sourcestring | integer

Buffer or string from which the {node} is extracted

optsnil | table

Optional parameters.

  • metadata (table) Metadata of a specific capture. This would be

    • set to metadata[capture_id] when using |vim.treesitter.query.add_directive()|.

Returns
string
function M.is_in_node_range(node: TSNode, line: integer, col: integer) -> True boolean

Determines whether (line, col) position is in node range

Parameters
nodeTSNode

defining the range

lineinteger

Line (0-based)

colinteger

Column (0-based)

Returns
Trueboolean

if the position is in node range

function M.node_contains(node: TSNode, range: table) -> True boolean

Determines if a node contains a range

Parameters
nodeTSNode
rangetable
Returns
Trueboolean

if the {node} contains the {range}

function M.get_captures_at_pos(buf: integer, row: integer, col: integer) -> { capture: string, id: integer, lang: string, metadata: vim.treesitter.query.TSMetadata, pattern_id: integer }[]

Returns a list of highlight captures at the given position

Each capture is represented by a table containing the capture name as a string, the capture's language, a table of metadata (priority, conceal, ...; empty if none are defined), the id of the capture, and the (0-indexed) id of the matched pattern in the query.

Parameters
bufinteger

Buffer number (0 for current buffer)

rowinteger

Position row

colinteger

Position column

Returns
{ capture: string, id: integer, lang: string, metadata: vim.treesitter.query.TSMetadata, pattern_id: integer }[]
function M.get_captures_at_cursor(win: nil | integer) -> List string[]

Returns a list of highlight capture names under the cursor

Parameters
winnil | integer

|window-ID| or 0 for current window (default)

Returns
Liststring[]

of capture names

function M.get_node(opts: vim.treesitter.get_node.Opts | nil) -> Node TSNode | nil

Returns the smallest named node at the given position

NOTE: Calling this on an unparsed tree can yield an invalid node. If the tree is not known to be parsed by, e.g., an active highlighter, parse the tree first via

vim.treesitter.get_parser(bufnr):parse(range)
Parameters
optsvim.treesitter.get_node.Opts | nil
Returns
NodeTSNode | nil

at the given position

function M.start(buf: nil | integer, lang: nil | string) -> nil

Starts treesitter highlighting for a buffer

Can be used in an ftplugin or FileType autocommand.

Note: By default, disables regex syntax highlighting, which may be required for some plugins. In this case, add vim.bo.syntax = 'ON' after the call to start.

Note: By default, the highlighter parses code asynchronously, using a segment time of 3ms.

Example:

vim.api.nvim_create_autocmd( 'FileType', { pattern = 'tex',
    callback = function(ev)
        vim.treesitter.start(ev.buf, 'latex')
        vim.bo[ev.buf].syntax = 'ON'  -- only if additional legacy syntax is needed
    end
})
Parameters
bufnil | integer

(default: current buffer) Buffer to be highlighted

langnil | string

(default: from 'filetype') Language of the parser

Returns
nil
function M.stop(buf: nil | integer) -> nil

Stops treesitter highlighting for a buffer

Parameters
bufnil | integer

(default: current buffer) Buffer to stop highlighting

Returns
nil
function M.inspect_tree(opts: nil | table) -> nil

Open a window that displays a textual representation of the nodes in the language tree.

While in the window, press "a" to toggle display of anonymous nodes, "I" to toggle the display of the source language of each node, "o" to toggle the query editor, and press [<Enter>] to jump to the node under the cursor in the source buffer. Folding also works (try |zo|, |zc|, etc.).

Can also be shown with :InspectTree. :InspectTree

Parameters
optsnil | table

Optional options table with the following possible keys:

  • bufnr (integer|nil): Buffer to draw the tree into. If omitted, a new

    • buffer is created.

  • command (string|nil): Vimscript command to create the window. Default

    • value is "60vnew". Only used when {winid} is nil.

  • lang (string|nil): The language of the source buffer. If omitted, detect

    • from the filetype of the source buffer.

  • title (string|fun(bufnr:integer):string|nil): Title of the window. If a

    • function, it accepts the buffer number of the source buffer as its only argument and should return a string.

  • winid (integer|nil): Window id to display the tree buffer in. If omitted,

    • a new window is created with {command}.

Returns
nil

@since 11

function M.foldexpr(lnum: nil | integer) -> string

Returns the fold level for {lnum} in the current buffer. Can be set directly to 'foldexpr':

vim.wo.foldexpr = vim.treesitter.foldexpr
Parameters
lnumnil | integer

Line number to calculate fold level for

Returns
string

@since 11

function M.select(target: "parent" | "child" | "next" | "prev" | "extend_next" | "extend_prev", count: nil | integer) -> nil

Starts or adjusts a |Visual| selection at cursor, based on tree nodes. The target parameter decides the selection behavior.

Parameters
target"parent" | "child" | "next" | "prev" | "extend_next" | "extend_prev"

Decides the selection behavior.

countnil | integer

(default: 1) Expand or adjust the selection this many times.

Returns
nil

Fields11

M._fold : vim.treesitter._fold
 
M._query_linter : vim.treesitter._query_linter
 
M._range : vim.treesitter._range
 
M.dev : vim.treesitter.dev
 
M.highlighter : vim.treesitter.highlighter
 
M.language : vim.treesitter.language
 
M.languagetree : vim.treesitter.languagetree
 
M.query : vim.treesitter.query
 
M._select : vim.treesitter._select
 
M.language_version : integer

@nodoc

M.minimum_language_version : integer

@nodoc