*treesitter.txt* Nvim NVIM REFERENCE MANUAL Treesitter integration *treesitter* Nvim integrates the `tree-sitter` library for incremental parsing of buffers: https://tree-sitter.github.io/tree-sitter/ WARNING: Treesitter support is still experimental and subject to frequent changes. This documentation may also not fully reflect the latest changes. Type |gO| to see the table of contents. ============================================================================== PARSER FILES *treesitter-parsers* Parsers are the heart of tree-sitter. They are libraries that tree-sitter will search for in the `parser` runtime directory. By default, Nvim bundles only parsers for C, Lua, and Vimscript, but parsers can be installed manually or via a plugin like https://github.com/nvim-treesitter/nvim-treesitter. Parsers are searched for as `parser/{lang}.*` in any 'runtimepath' directory. If multiple parsers for the same language are found, the first one is used. (This typically implies the priority "user config > plugins > bundled". A parser can also be loaded manually using a full path: >lua vim.treesitter.require_language("python", "/path/to/python.so") < ============================================================================== LANGUAGE TREES *treesitter-languagetree* *LanguageTree* As buffers can contain multiple languages (e.g., Vimscript commands in a Lua file), multiple parsers may be needed to parse the full buffer. These are combined in a |LanguageTree| object. To create a LanguageTree (parser object) for a buffer and a given language, use >lua tsparser = vim.treesitter.get_parser(bufnr, lang) < `bufnr=0` can be used for current buffer. `lang` will default to 'filetype'. Currently, the parser will be retained for the lifetime of a buffer but this is subject to change. A plugin should keep a reference to the parser object as long as it wants incremental updates. Whenever you need to access the current syntax tree, parse the buffer: >lua tstree = tsparser:parse() < This will return a table of immutable |treesitter-tree|s that represent the current state of the buffer. When the plugin wants to access the state after a (possible) edit it should call `parse()` again. If the buffer wasn't edited, the same tree will be returned again without extra work. If the buffer was parsed before, incremental parsing will be done of the changed parts. Note: To use the parser directly inside a |nvim_buf_attach()| Lua callback, you must call |vim.treesitter.get_parser()| before you register your callback. But preferably parsing shouldn't be done directly in the change callback anyway as they will be very frequent. Rather a plugin that does any kind of analysis on a tree should use a timer to throttle too frequent updates. See |lua-treesitter-languagetree| for the list of available methods. ============================================================================== TREESITTER TREES *treesitter-tree* *tstree* A "treesitter tree" represents the parsed contents of a buffer, which can be used to perform further analysis. It is a |luaref-userdata| reference to an object held by the tree-sitter library. An instance `tstree` of a treesitter tree supports the following methods. tstree:root() *tstree:root()* Return the root node of this tree. tstree:copy() *tstree:copy()* Returns a copy of the `tstree`. ============================================================================== TREESITTER NODES *treesitter-node* *tsnode* A "treesitter node" represents one specific element of the parsed contents of a buffer, which can be captured by a |Query| for, e.g., highlighting. It is a |luaref-userdata| reference to an object held by the tree-sitter library. An instance `tsnode` of a treesitter node supports the following methods. tsnode:parent() *tsnode:parent()* Get the node's immediate parent. tsnode:next_sibling() *tsnode:next_sibling()* Get the node's next sibling. tsnode:prev_sibling() *tsnode:prev_sibling()* Get the node's previous sibling. tsnode:next_named_sibling() *tsnode:next_named_sibling()* Get the node's next named sibling. tsnode:prev_named_sibling() *tsnode:prev_named_sibling()* Get the node's previous named sibling. tsnode:iter_children() *tsnode:iter_children()* Iterates over all the direct children of {tsnode}, regardless of whether they are named or not. Returns the child node plus the eventual field name corresponding to this child node. tsnode:field({name}) *tsnode:field()* Returns a table of the nodes corresponding to the {name} field. tsnode:child_count() *tsnode:child_count()* Get the node's number of children. tsnode:child({index}) *tsnode:child()* Get the node's child at the given {index}, where zero represents the first child. tsnode:named_child_count() *tsnode:named_child_count()* Get the node's number of named children. tsnode:named_child({index}) *tsnode:named_child()* Get the node's named child at the given {index}, where zero represents the first named child. tsnode:start() *tsnode:start()* Get the node's start position. Return three values: the row, column and total byte count (all zero-based). tsnode:end_() *tsnode:end_()* Get the node's end position. Return three values: the row, column and total byte count (all zero-based). tsnode:range() *tsnode:range()* Get the range of the node. Return four values: the row, column of the start position, then the row, column of the end position. tsnode:type() *tsnode:type()* Get the node's type as a string. tsnode:symbol() *tsnode:symbol()* Get the node's type as a numerical id. tsnode:named() *tsnode:named()* Check if the node is named. Named nodes correspond to named rules in the grammar, whereas anonymous nodes correspond to string literals in the grammar. tsnode:missing() *tsnode:missing()* Check if the node is missing. Missing nodes are inserted by the parser in order to recover from certain kinds of syntax errors. tsnode:has_error() *tsnode:has_error()* Check if the node is a syntax error or contains any syntax errors. tsnode:sexpr() *tsnode:sexpr()* Get an S-expression representing the node as a string. tsnode:id() *tsnode:id()* Get an unique identifier for the node inside its own tree. No guarantees are made about this identifier's internal representation, except for being a primitive Lua type with value equality (so not a table). Presently it is a (non-printable) string. Note: The `id` is not guaranteed to be unique for nodes from different trees. *tsnode:descendant_for_range()* tsnode:descendant_for_range({start_row}, {start_col}, {end_row}, {end_col}) Get the smallest node within this node that spans the given range of (row, column) positions *tsnode:named_descendant_for_range()* tsnode:named_descendant_for_range({start_row}, {start_col}, {end_row}, {end_col}) Get the smallest named node within this node that spans the given range of (row, column) positions ============================================================================== TREESITTER QUERIES *treesitter-query* Treesitter queries are a way to extract information about a parsed |tstree|, e.g., for the purpose of highlighting. Briefly, a `query` consists of one or more patterns. A `pattern` is defined over node types in the syntax tree. A `match` corresponds to specific elements of the syntax tree which match a pattern. Patterns may optionally define captures and predicates. A `capture` allows you to associate names with a specific node in a pattern. A `predicate` adds arbitrary metadata and conditional data to a match. Queries are written in a lisp-like language documented in https://tree-sitter.github.io/tree-sitter/using-parsers#query-syntax Note: The predicates listed there page differ from those Nvim supports. See |treesitter-predicates| for a complete list of predicates supported by Nvim. Nvim looks for queries as `*.scm` files in a `queries` directory under `runtimepath`, where each file contains queries for a specific language and purpose, e.g., `queries/lua/highlights.scm` for highlighting Lua files. By default, the first query on `runtimepath` is used (which usually implies that user config takes precedence over plugins, which take precedence over queries bundled with Neovim). If a query should extend other queries instead of replacing them, use |treesitter-query-modeline-extends|. See |lua-treesitter-query| for the list of available methods for working with treesitter queries from Lua. TREESITTER QUERY PREDICATES *treesitter-predicates* Predicates are special scheme nodes that are evaluated to conditionally capture nodes. For example, the `eq?` predicate can be used as follows: > ((identifier) @foo (#eq? @foo "foo")) < to only match identifier corresponding to the `"foo"` text. The following predicates are built in: `eq?` *treesitter-predicate-eq?* Match a string against the text corresponding to a node: > ((identifier) @foo (#eq? @foo "foo")) ((node1) @left (node2) @right (#eq? @left @right)) < `match?` *treesitter-predicate-match?* `vim-match?` *treesitter-predicate-vim-match?* Match a |regexp| against the text corresponding to a node: > ((identifier) @constant (#match? @constant "^[A-Z_]+$")) < Note: The `^` and `$` anchors will match the start and end of the node's text. `lua-match?` *treesitter-predicate-lua-match?* Match |lua-patterns| against the text corresponding to a node, similar to `match?` `contains?` *treesitter-predicate-contains?* Match a string against parts of the text corresponding to a node: > ((identifier) @foo (#contains? @foo "foo")) ((identifier) @foo-bar (#contains? @foo-bar "foo" "bar")) < `any-of?` *treesitter-predicate-any-of?* Match any of the given strings against the text corresponding to a node: > ((identifier) @foo (#any-of? @foo "foo" "bar")) < This is the recommended way to check if the node matches one of many keywords, as it has been optimized for this. *lua-treesitter-not-predicate* Each predicate has a `not-` prefixed predicate that is just the negation of the predicate. Further predicates can be added via |vim.treesitter.query.add_predicate()|. Use |vim.treesitter.query.list_predicates()| to list all available predicates. TREESITTER QUERY DIRECTIVES *treesitter-directives* Treesitter directives store metadata for a node or match and perform side effects. For example, the `set!` directive sets metadata on the match or node: > ((identifier) @foo (#set! "type" "parameter")) < The following directives are built in: `set!` *treesitter-directive-set!* Sets key/value metadata for a specific match or capture. Value is accessible as either `metadata[key]` (match specific) or `metadata[capture_id][key]` (capture specific). Parameters: ~ {capture_id} (optional) {key} {value} Examples: > ((identifier) @foo (#set! @foo "kind" "parameter")) ((node1) @left (node2) @right (#set! "type" "pair")) < `offset!` *treesitter-directive-offset!* Takes the range of the captured node and applies an offset. This will generate a new range object for the captured node as `metadata[capture_id].range`. Parameters: ~ {capture_id} {start_row} {start_col} {end_row} {end_col} Example: > ((identifier) @constant (#offset! @constant 0 1 0 -1)) < Further directives can be added via |vim.treesitter.query.add_directive()|. Use |vim.treesitter.query.list_directives()| to list all available directives. TREESITTER QUERY MODELINES *treesitter-query-modeline* Neovim supports to customize the behavior of the queries using a set of "modelines", that is comments in the queries starting with `;`. Here are the currently supported modeline alternatives: `inherits: {lang}...` *treesitter-query-modeline-inherits* Specifies that this query should inherit the queries from {lang}. This will recursively descend in the queries of {lang} unless wrapped in parentheses: `({lang})`. Note: This is meant to be used to include queries from another language. If you want your query to extend the queries of the same language, use `extends`. `extends` *treesitter-query-modeline-extends* Specifies that this query should be used as an extension for the query, i.e. that it should be merged with the others. Note: The order of the extensions, and the query that will be used as a base depends on your 'runtimepath' value. Note: These modeline comments must be at the top of the query, but can be repeated, for example, the following two modeline blocks are both valid: > ;; inherits: foo,bar ;; extends ;; extends ;; ;; inherits: baz < ============================================================================== TREESITTER SYNTAX HIGHLIGHTING *treesitter-highlight* Syntax highlighting is specified through queries named `highlights.scm`, which match a |tsnode| in the parsed |tstree| to a `capture` that can be assigned a highlight group. For example, the query > (parameters (identifier) @parameter) < matches any `identifier` node inside a function `parameter` node (e.g., the `bar` in `foo(bar)`) to the capture named `@parameter`. It is also possible to match literal expressions (provided the parser returns them): > "return" @keyword.return < Assuming a suitable parser and `highlights.scm` query is found in runtimepath, treesitter highlighting for the current buffer can be enabled simply via |vim.treesitter.start()|. *treesitter-highlight-groups* The capture names, with `@` included, are directly usable as highlight groups. For many commonly used captures, the corresponding highlight groups are linked to Nvim's standard |highlight-groups| by default but can be overridden in colorschemes. A fallback system is implemented, so that more specific groups fallback to more generic ones. For instance, in a language that has separate doc comments, `@comment.doc` could be used. If this group is not defined, the highlighting for an ordinary `@comment` is used. This way, existing color schemes already work out of the box, but it is possible to add more specific variants for queries that make them available. As an additional rule, capture highlights can always be specialized by language, by appending the language name after an additional dot. For instance, to highlight comments differently per language: >vim hi @comment.c guifg=Blue hi @comment.lua guifg=DarkBlue hi link @comment.doc.java String < The following captures are linked by default to standard |group-name|s: > @text.literal Comment @text.reference Identifier @text.title Title @text.uri Underlined @text.underline Underlined @text.todo Todo @comment Comment @punctuation Delimiter @constant Constant @constant.builtin Special @constant.macro Define @define Define @macro Macro @string String @string.escape SpecialChar @string.special SpecialChar @character Character @character.special SpecialChar @number Number @boolean Boolean @float Float @function Function @function.builtin Special @function.macro Macro @parameter Identifier @method Function @field Identifier @property Identifier @constructor Special @conditional Conditional @repeat Repeat @label Label @operator Operator @keyword Keyword @exception Exception @variable Identifier @type Type @type.definition Typedef @storageclass StorageClass @structure Structure @namespace Identifier @include Include @preproc PreProc @debug Debug @tag Tag < *treesitter-highlight-spell* The special `@spell` capture can be used to indicate that a node should be spell checked by Nvim's builtin |spell| checker. For example, the following capture marks comments as to be checked: > (comment) @spell < There is also `@nospell` which disables spellchecking regions with `@spell`. *treesitter-highlight-conceal* Treesitter highlighting supports |conceal| via the `conceal` metadata. By convention, nodes to be concealed are captured as `@conceal`, but any capture can be used. For example, the following query can be used to hide code block delimiters in Markdown: > (fenced_code_block_delimiter) @conceal (#set! conceal "") < It is also possible to replace a node with a single character, which (unlike legacy syntax) can be given a custom highlight. For example, the following (ill-advised) query replaces the `!=` operator by a Unicode glyph, which is still highlighted the same as other operators: > "!=" @operator (#set! conceal "≠") < Conceals specified in this way respect 'conceallevel'. *treesitter-highlight-priority* Treesitter uses |nvim_buf_set_extmark()| to set highlights with a default priority of 100. This enables plugins to set a highlighting priority lower or higher than tree-sitter. It is also possible to change the priority of an individual query pattern manually by setting its `"priority"` metadata attribute: > (super_important_node) @ImportantHighlight (#set! "priority" 105) < ============================================================================== VIM.TREESITTER *lua-treesitter* The remainder of this document is a reference manual for the `vim.treesitter` Lua module, which is the main interface for Nvim's tree-sitter integration. Most of the following content is automatically generated from the function documentation. *vim.treesitter.language_version* The latest parser ABI version that is supported by the bundled tree-sitter library. *vim.treesitter.minimum_language_version* The earliest parser ABI version that is supported by the bundled tree-sitter library. ============================================================================== Lua module: vim.treesitter *lua-treesitter-core* *vim.treesitter.get_captures_at_cursor()* get_captures_at_cursor({winnr}) Returns a list of highlight capture names under the cursor Parameters: ~ • {winnr} (number|nil) Window handle or 0 for current window (default) Return: ~ string[] List of capture names *vim.treesitter.get_captures_at_pos()* get_captures_at_pos({bufnr}, {row}, {col}) Returns a list of highlight captures at the given position Each capture is represented by a table containing the capture name as a string as well as a table of metadata (`priority`, `conceal`, ...; empty if none are defined). Parameters: ~ • {bufnr} (number) Buffer number (0 for current buffer) • {row} (number) Position row • {col} (number) Position column Return: ~ table[] List of captures `{ capture = "capture name", metadata = { ... } }` get_node_at_cursor({winnr}) *vim.treesitter.get_node_at_cursor()* Returns the smallest named node under the cursor Parameters: ~ • {winnr} (number|nil) Window handle or 0 for current window (default) Return: ~ (string) Name of node under the cursor *vim.treesitter.get_node_at_pos()* get_node_at_pos({bufnr}, {row}, {col}, {opts}) Returns the smallest named node at the given position Parameters: ~ • {bufnr} (number) Buffer number (0 for current buffer) • {row} (number) Position row • {col} (number) Position column • {opts} (table) Optional keyword arguments: • lang string|nil Parser language • ignore_injections boolean Ignore injected languages (default true) Return: ~ userdata|nil |tsnode| under the cursor get_node_range({node_or_range}) *vim.treesitter.get_node_range()* Returns the node's range or an unpacked range table Parameters: ~ • {node_or_range} (userdata|table) |tsnode| or table of positions Return: ~ (table) `{ start_row, start_col, end_row, end_col }` get_parser({bufnr}, {lang}, {opts}) *vim.treesitter.get_parser()* Returns the parser for a specific buffer and filetype and attaches it to the buffer If needed, this will create the parser. Parameters: ~ • {bufnr} (number|nil) Buffer the parser should be tied to (default: current buffer) • {lang} (string|nil) Filetype of this parser (default: buffer filetype) • {opts} (table|nil) Options to pass to the created language tree Return: ~ LanguageTree |LanguageTree| object to use for parsing *vim.treesitter.get_string_parser()* get_string_parser({str}, {lang}, {opts}) Returns a string parser Parameters: ~ • {str} (string) Text to parse • {lang} (string) Language of this string • {opts} (table|nil) Options to pass to the created language tree Return: ~ LanguageTree |LanguageTree| object to use for parsing is_ancestor({dest}, {source}) *vim.treesitter.is_ancestor()* Determines whether a node is the ancestor of another Parameters: ~ • {dest} userdata Possible ancestor |tsnode| • {source} userdata Possible descendant |tsnode| Return: ~ (boolean) True if {dest} is an ancestor of {source} *vim.treesitter.is_in_node_range()* is_in_node_range({node}, {line}, {col}) Determines whether (line, col) position is in node range Parameters: ~ • {node} userdata |tsnode| defining the range • {line} (number) Line (0-based) • {col} (number) Column (0-based) Return: ~ (boolean) True if the position is in node range node_contains({node}, {range}) *vim.treesitter.node_contains()* Determines if a node contains a range Parameters: ~ • {node} userdata |tsnode| • {range} (table) Return: ~ (boolean) True if the {node} contains the {range} show_tree({opts}) *vim.treesitter.show_tree()* 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, and press to jump to the node under the cursor in the source buffer. Parameters: ~ • {opts} (table|nil) Optional options table with the following possible keys: • lang (string|nil): The language of the source buffer. If omitted, the filetype of the source buffer is used. • bufnr (number|nil): Buffer to draw the tree into. If omitted, a new buffer is created. • winid (number|nil): Window id to display the tree buffer in. If omitted, a new window is created with {command}. • command (string|nil): Vimscript command to create the window. Default value is "topleft 60vnew". Only used when {winid} is nil. • title (string|fun(bufnr:number):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. start({bufnr}, {lang}) *vim.treesitter.start()* 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`. Example: >lua vim.api.nvim_create_autocmd( 'FileType', { pattern = 'tex', callback = function(args) vim.treesitter.start(args.buf, 'latex') vim.bo[args.buf].syntax = 'on' -- only if additional legacy syntax is needed end }) < Parameters: ~ • {bufnr} (number|nil) Buffer to be highlighted (default: current buffer) • {lang} (string|nil) Language of the parser (default: buffer filetype) stop({bufnr}) *vim.treesitter.stop()* Stops treesitter highlighting for a buffer Parameters: ~ • {bufnr} (number|nil) Buffer to stop highlighting (default: current buffer) ============================================================================== Lua module: vim.treesitter.language *lua-treesitter-language* inspect_language({lang}) *vim.treesitter.language.inspect_language()* Inspects the provided language. Inspecting provides some useful information on the language like node names, ... Parameters: ~ • {lang} (string) Language Return: ~ (table) *vim.treesitter.language.require_language()* require_language({lang}, {path}, {silent}, {symbol_name}) Asserts that a parser for the language {lang} is installed. Parsers are searched in the `parser` runtime directory, or the provided {path} Parameters: ~ • {lang} (string) Language the parser should parse • {path} (string|nil) Optional path the parser is located at • {silent} (boolean|nil) Don't throw an error if language not found • {symbol_name} (string|nil) Internal symbol name for the language to load Return: ~ (boolean) If the specified language is installed ============================================================================== Lua module: vim.treesitter.query *lua-treesitter-query* *vim.treesitter.query.add_directive()* add_directive({name}, {handler}, {force}) 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: ~ • {name} (string) Name of the directive, without leading # • {handler} function(match:string, pattern:string, bufnr:number, predicate:function, metadata:table) *vim.treesitter.query.add_predicate()* add_predicate({name}, {handler}, {force}) Adds a new predicate to be used in queries Parameters: ~ • {name} (string) Name of the predicate, without leading # • {handler} function(match:string, pattern:string, bufnr:number, predicate:function) *vim.treesitter.query.get_node_text()* get_node_text({node}, {source}, {opts}) Gets the text corresponding to a given node Parameters: ~ • {node} userdata |tsnode| • {source} (number|string) Buffer or string from which the {node} is extracted • {opts} (table|nil) Optional parameters. • concat: (boolean) Concatenate result in a string (default true) Return: ~ (string[]|string) get_query({lang}, {query_name}) *vim.treesitter.query.get_query()* Returns the runtime query {query_name} for {lang}. Parameters: ~ • {lang} (string) Language to use for the query • {query_name} (string) Name of the query (e.g. "highlights") Return: ~ Query Parsed query *vim.treesitter.query.get_query_files()* get_query_files({lang}, {query_name}, {is_included}) Gets the list of files used to make up a query Parameters: ~ • {lang} (string) Language to get query for • {query_name} (string) Name of the query to load (e.g., "highlights") • {is_included} (boolean|nil) Internal parameter, most of the time left as `nil` Return: ~ string[] query_files List of files to load for given query and language list_directives() *vim.treesitter.query.list_directives()* Lists the currently available directives to use in queries. Return: ~ string[] List of supported directives. list_predicates() *vim.treesitter.query.list_predicates()* Lists the currently available predicates to use in queries. Return: ~ string[] List of supported predicates. parse_query({lang}, {query}) *vim.treesitter.query.parse_query()* Parse {query} as a string. (If the query is in a file, the caller should read the contents into a string before calling). Returns a `Query` (see |lua-treesitter-query|) object which can be used to search nodes in the syntax tree for the patterns defined in {query} using `iter_*` methods below. Exposes `info` and `captures` with additional context about {query}. • `captures` contains the list of unique capture names defined in {query}. -`info.captures` also points to `captures`. • `info.patterns` contains information about predicates. Parameters: ~ • {lang} (string) Language to use for the query • {query} (string) Query in s-expr syntax Return: ~ Query Parsed query *Query:iter_captures()* Query:iter_captures({self}, {node}, {source}, {start}, {stop}) Iterate over all captures from all matches inside {node} {source} is needed if the query contains predicates; then the caller must ensure to use a freshly parsed tree consistent with the current text of the buffer (if relevant). {start_row} and {end_row} can be used to limit matches inside a row range (this is typically used with root node as the {node}, i.e., to get syntax highlight matches in the current viewport). When omitted, the {start} and {end} row values are used from the given node. The iterator returns three values: a numeric id identifying the capture, the captured node, and metadata from any directives processing the match. The following example shows how to get captures by name: >lua for id, node, metadata in query:iter_captures(tree:root(), bufnr, first, last) do local name = query.captures[id] -- name of the capture in the query -- typically useful info about the node: local type = node:type() -- type of the captured node local row1, col1, row2, col2 = node:range() -- range of the capture ... use the info here ... end < Parameters: ~ • {node} userdata |tsnode| under which the search will occur • {source} (number|string) Source buffer or string to extract text from • {start} (number) Starting line for the search • {stop} (number) Stopping line for the search (end-exclusive) • {self} Return: ~ (number) capture Matching capture id (table) capture_node Capture for {node} (table) metadata for the {capture} *Query:iter_matches()* Query:iter_matches({self}, {node}, {source}, {start}, {stop}) Iterates the matches of self on a given range. Iterate over all matches within a {node}. The arguments are the same as for |Query:iter_captures()| but the iterated values are different: an (1-based) index of the pattern in the query, a table mapping capture indices to nodes, and metadata from any directives processing the match. If the query has more than one pattern, the capture table might be sparse and e.g. `pairs()` method should be used over `ipairs` . Here is an example iterating over all captures in every match: >lua for pattern, match, metadata in cquery:iter_matches(tree:root(), bufnr, first, last) do for id, node in pairs(match) do local name = query.captures[id] -- `node` was captured by the `name` capture in the match local node_data = metadata[id] -- Node level metadata ... use the info here ... end end < Parameters: ~ • {node} userdata |tsnode| under which the search will occur • {source} (number|string) Source buffer or string to search • {start} (number) Starting line for the search • {stop} (number) Stopping line for the search (end-exclusive) • {self} Return: ~ (number) pattern id (table) match (table) metadata *vim.treesitter.query.set_query()* set_query({lang}, {query_name}, {text}) Sets the runtime query named {query_name} for {lang} This allows users to override any runtime files and/or configuration set by plugins. Parameters: ~ • {lang} (string) Language to use for the query • {query_name} (string) Name of the query (e.g., "highlights") • {text} (string) Query text (unparsed). ============================================================================== Lua module: vim.treesitter.highlighter *lua-treesitter-highlighter* new({tree}, {opts}) *vim.treesitter.highlighter.new()* Creates a new highlighter using Parameters: ~ • {tree} LanguageTree |LanguageTree| parser object to use for highlighting • {opts} (table|nil) Configuration of the highlighter: • queries table overwrite queries used by the highlighter Return: ~ TSHighlighter Created highlighter object TSHighlighter:destroy({self}) *TSHighlighter:destroy()* Removes all internal references to the highlighter Parameters: ~ • {self} ============================================================================== Lua module: vim.treesitter.languagetree *lua-treesitter-languagetree* LanguageTree:children({self}) *LanguageTree:children()* Returns a map of language to child tree. Parameters: ~ • {self} LanguageTree:contains({self}, {range}) *LanguageTree:contains()* Determines whether {range} is contained in the |LanguageTree|. Parameters: ~ • {range} (table) `{ start_line, start_col, end_line, end_col }` • {self} Return: ~ (boolean) LanguageTree:destroy({self}) *LanguageTree:destroy()* 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. Parameters: ~ • {self} *LanguageTree:for_each_child()* LanguageTree:for_each_child({self}, {fn}, {include_self}) Invokes the callback for each |LanguageTree| and its children recursively Parameters: ~ • {fn} function(tree: LanguageTree, lang: string) • {include_self} (boolean) Whether to include the invoking tree in the results • {self} LanguageTree:for_each_tree({self}, {fn}) *LanguageTree:for_each_tree()* Invokes the callback for each |LanguageTree| recursively. Note: This includes the invoking tree's child trees as well. Parameters: ~ • {fn} function(tree: TSTree, languageTree: LanguageTree) • {self} LanguageTree:included_regions({self}) *LanguageTree:included_regions()* Gets the set of included regions Parameters: ~ • {self} LanguageTree:invalidate({self}, {reload}) *LanguageTree:invalidate()* Invalidates this parser and all its children Parameters: ~ • {self} LanguageTree:is_valid({self}) *LanguageTree:is_valid()* Determines whether this tree is valid. If the tree is invalid, call `parse()` . This will return the updated tree. Parameters: ~ • {self} LanguageTree:lang({self}) *LanguageTree:lang()* Gets the language of this tree node. Parameters: ~ • {self} *LanguageTree:language_for_range()* LanguageTree:language_for_range({self}, {range}) Gets the appropriate language that contains {range}. Parameters: ~ • {range} (table) `{ start_line, start_col, end_line, end_col }` • {self} Return: ~ LanguageTree Managing {range} *LanguageTree:named_node_for_range()* LanguageTree:named_node_for_range({self}, {range}, {opts}) Gets the smallest named node that contains {range}. Parameters: ~ • {range} (table) `{ start_line, start_col, end_line, end_col }` • {opts} (table|nil) Optional keyword arguments: • ignore_injections boolean Ignore injected languages (default true) • {self} Return: ~ userdata|nil Found |tsnode| LanguageTree:parse({self}) *LanguageTree:parse()* Parses all defined regions using a treesitter parser for the language this tree represents. This will run the injection query for this language to determine if any child languages should be created. Parameters: ~ • {self} Return: ~ userdata[] Table of parsed |tstree| (table) Change list LanguageTree:register_cbs({self}, {cbs}) *LanguageTree:register_cbs()* Registers callbacks for the |LanguageTree|. Parameters: ~ • {cbs} (table) An |nvim_buf_attach()|-like table argument with the following handlers: • `on_bytes` : see |nvim_buf_attach()|, but this will be called after the parsers callback. • `on_changedtree` : a callback that will be called every time the tree has syntactical changes. It will only be passed one argument, which is a table of the ranges (as node ranges) that changed. • `on_child_added` : emitted when a child is added to the tree. • `on_child_removed` : emitted when a child is removed from the tree. • {self} LanguageTree:source({self}) *LanguageTree:source()* Returns the source content of the language tree (bufnr or string). Parameters: ~ • {self} *LanguageTree:tree_for_range()* LanguageTree:tree_for_range({self}, {range}, {opts}) Gets the tree that contains {range}. Parameters: ~ • {range} (table) `{ start_line, start_col, end_line, end_col }` • {opts} (table|nil) Optional keyword arguments: • ignore_injections boolean Ignore injected languages (default true) • {self} Return: ~ userdata|nil Contained |tstree| LanguageTree:trees({self}) *LanguageTree:trees()* Returns all trees this language tree contains. Does not include child languages. Parameters: ~ • {self} new({source}, {lang}, {opts}) *vim.treesitter.languagetree.new()* A |LanguageTree| holds the treesitter parser for a given language {lang} used to parse a buffer. As the buffer may contain injected languages, the LanguageTree needs to store parsers for these child languages as well (which in turn may contain child languages themselves, hence the name). Parameters: ~ • {source} (number|string) Buffer or a string of text to parse • {lang} (string) Root language this tree represents • {opts} (table|nil) Optional keyword arguments: • injections table Mapping language to injection query strings. This is useful for overriding the built-in runtime file searching for the injection language query per language. Return: ~ LanguageTree |LanguageTree| parser object vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: