vim.treesitter.query

Methods11

function M.get_files(lang: string, query_name: string, is_included: nil | boolean) -> query_files string[]

Gets the list of files used to make up a query

Parameters

langstring: Language to get query for
query_namestring: Name of the query to load (e.g., "highlights")
is_includednil | boolean: Internal parameter, most of the time left as nil

Returns

query_filesstring[]: List of files to load for given query and language

function M.set(lang: string, query_name: string, text: string) -> nil

Sets the runtime query named {query_name} for {lang}

This allows users to override or extend any runtime files and/or configuration set by plugins.

For example, you could enable spellchecking of C identifiers with the following code:

vim.treesitter.query.set(
  'c',
  'highlights',
  [[;inherits c
  (identifier) @spell]]
)

Parameters

langstring: Language to use for the query
query_namestring: Name of the query (e.g., "highlights")
textstring: Query text (unparsed).

Returns

nil

function M.get(lang: string, query_name: string) -> vim.treesitter.Query | nil

Returns the runtime query {query_name} for {lang}.

Parameters

langstring: Language to use for the query
query_namestring: Name of the query (e.g. "highlights")

Returns

vim.treesitter.Query | nil: : Parsed query. nil if no query files are found.

function M.parse(lang: string, query: string) -> vim.treesitter.Query

Parses a {query} string and returns a Query object (|lua-treesitter-query|), which can be used to search the tree for the query patterns (via |Query:itercaptures()|, |Query:itermatches()|), or inspect/modify the query via these fields:

captures: a list of unique capture names defined in the query (alias: info.captures).
info.patterns: information about predicates.
query: the underlying |TSQuery| which can be used to disable patterns or captures.

Example:

local query = vim.treesitter.query.parse('vimdoc', [[
  ; query
  ((h1) @str
    (#trim! @str 1 1 1 1))
]])
local tree = vim.treesitter.get_parser():parse()[1]
for id, node, metadata in query:iter_captures(tree:root(), 0) do
   -- Print the node name and source text.
   vim.print({node:type(), vim.treesitter.get_node_text(node, vim.api.nvim_get_current_buf())})
end

Parameters

langstring: Language to use for the query
querystring: Query text, in s-expr syntax

Returns

vim.treesitter.Query: : Parsed query

See:

[vim.treesitter.query.get()]

function M.add_predicate(name: string, handler: fun(match: {integer, TSNode[]}, pattern: integer, source: string | integer, predicate: any[], metadata: vim.treesitter.query.TSMetadata) -> nil | boolean, opts: vim.treesitter.query.add_predicate.Opts | nil) -> nil

Adds a new predicate to be used in queries

Parameters

namestring: Name of the predicate, without leading #
handlerfun(match: {integer, TSNode[]}, pattern: integer, source: string | integer, predicate: any[], metadata: vim.treesitter.query.TSMetadata) -> nil | boolean: see |vim.treesitter.query.add_directive()| for argument meanings
optsvim.treesitter.query.add_predicate.Opts | nil

Returns

nil

function M.add_directive(name: string, handler: fun(match: {integer, TSNode[]}, pattern: integer, source: string | integer, predicate: any[], metadata: vim.treesitter.query.TSMetadata) -> nil, opts: vim.treesitter.query.add_predicate.Opts) -> nil

Adds a new directive to be used in queries

Handlers can set match level data by setting directly on the metadata object metadata.key = value. Additionally, handlers can set node level data by using the capture id on the metadata table metadata[capture_id].key = value

Parameters

namestring: Name of the directive, without leading #
handlerfun(match: {integer, TSNode[]}, pattern: integer, source: string | integer, predicate: any[], metadata: vim.treesitter.query.TSMetadata) -> nil: match: A table mapping capture IDs to a list of captured nodes
pattern: the index of the matching pattern in the query file
predicate: list of strings containing the full directive being called, e.g.
(node (#set! conceal "-")) would get the predicate { "#set!", "conceal", "-" }
optsvim.treesitter.query.add_predicate.Opts

Returns

nil

function M.list_directives() -> string[]

Lists the currently available directives to use in queries.

Returns

string[]: : Supported directives.

function M.list_predicates() -> string[]

Lists the currently available predicates to use in queries.

Returns

string[]: : Supported predicates.

function M.lint(buf: integer, opts: vim.treesitter.query.lint.Opts | nil) -> nil

Lint treesitter queries using installed parser, or clear lint errors.

Use |treesitter-parsers| in runtimepath to check the query file in {buf} for errors:

verify that used nodes are valid identifiers in the grammar.
verify that predicates and directives are valid.
verify that top-level s-expressions are valid.

The found diagnostics are reported using |diagnostic-api|. By default, the parser used for verification is determined by the containing folder of the query file, e.g., if the path ends in /lua/highlights.scm, the parser for the lua language will be used.

Parameters

bufinteger: Buffer handle
optsvim.treesitter.query.lint.Opts | nil

Returns

nil

function M.omnifunc(findstart: 0 | 1, base: string) -> number | table

Omnifunc for completing node names and predicates in treesitter queries.

Use via

vim.bo.omnifunc = vim.treesitter.query.omnifunc

function M.edit(lang: nil | string) -> nil

Opens a live editor to query the buffer you started from.

Can also be shown with the :EditQuery command. :EditQuery <tab> completes available parsers.

If you move the cursor to a capture name ("@foo"), text matching the capture is highlighted with |hl-DiagnosticVirtualTextHint| in the source buffer. The query editor is a scratch buffer, use :write to save it. You can find example queries at $VIMRUNTIME/queries/.

Parameters

langnil | string: language to open the query editor for. If omitted, inferred from the current buffer's filetype.

Returns

nil