diff options
Diffstat (limited to 'runtime/doc/treesitter.txt')
| -rw-r--r-- | runtime/doc/treesitter.txt | 138 |
1 files changed, 122 insertions, 16 deletions
diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt index 2c6c9e4ed8..491aea793c 100644 --- a/runtime/doc/treesitter.txt +++ b/runtime/doc/treesitter.txt @@ -187,6 +187,11 @@ Note: The predicates listed in the web page above differ from those Neovim supports. See |lua-treesitter-predicates| for a complete list of predicates supported by Neovim. +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 |ts-modeline-extends|. + 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 @@ -194,6 +199,36 @@ 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. + *ts-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}...` *ts-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` *ts-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 modeline blocks are all valid: +> + ;; inherits: foo,bar + ;; extends + + ;; extends + ;; + ;; inherits: baz +< + Treesitter Query Predicates *lua-treesitter-predicates* When writing queries for treesitter, one might use `predicates`, that is, @@ -370,17 +405,50 @@ attribute: > ============================================================================== Lua module: vim.treesitter *lua-treesitter-core* +get_captures_at_cursor({winnr}) *get_captures_at_cursor()* + Gets a list of captures under the cursor + + Parameters: ~ + {winnr} (number|nil) Window handle or 0 for current window (default) + + Return: ~ + (table) Named node under the cursor + *get_captures_at_position()* get_captures_at_position({bufnr}, {row}, {col}) Gets a list of captures for a given cursor position Parameters: ~ - {bufnr} (number) The buffer number - {row} (number) The position row - {col} (number) The position column + {bufnr} (number) Buffer number (0 for current buffer) + {row} (number) Position row + {col} (number) Position column + + Return: ~ + (table) Table of captures + +get_node_at_cursor({winnr}) *get_node_at_cursor()* + Gets the smallest named node under the cursor + + Parameters: ~ + {winnr} (number|nil) Window handle or 0 for current window (default) + + Return: ~ + (string) Named node under the cursor + + *get_node_at_position()* +get_node_at_position({bufnr}, {row}, {col}, {opts}) + Gets the smallest named node at position + + Parameters: ~ + {bufnr} (number) Buffer number (0 for current buffer) + {row} (number) Position row + {col} (number) Position column + {opts} (table) Optional keyword arguments: + • ignore_injections boolean Ignore injected languages + (default true) Return: ~ - (table) A table of captures + (table) Named node under the cursor get_node_range({node_or_range}) *get_node_range()* Get the node's range or unpack a range table @@ -389,7 +457,7 @@ get_node_range({node_or_range}) *get_node_range()* {node_or_range} (table) Return: ~ - start_row, start_col, end_row, end_col + (table) start_row, start_col, end_row, end_col get_parser({bufnr}, {lang}, {opts}) *get_parser()* Gets the parser for this bufnr / ft combination. @@ -398,12 +466,14 @@ get_parser({bufnr}, {lang}, {opts}) *get_parser()* callback Parameters: ~ - {bufnr} The buffer the parser should be tied to - {lang} The filetype of this parser - {opts} Options object to pass to the created language tree + {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: ~ - The parser + (table) Parser object get_string_parser({str}, {lang}, {opts}) *get_string_parser()* Gets a string parser @@ -417,8 +487,8 @@ is_ancestor({dest}, {source}) *is_ancestor()* Determines whether a node is the ancestor of another Parameters: ~ - {dest} (table) the possible ancestor - {source} (table) the possible descendant node + {dest} (table) Possible ancestor + {source} (table) Possible descendant node Return: ~ (boolean) True if dest is an ancestor of source @@ -427,20 +497,56 @@ is_in_node_range({node}, {line}, {col}) *is_in_node_range()* Determines whether (line, col) position is in node range Parameters: ~ - {node} Node defining the range - {line} A line (0-based) - {col} A column (0-based) + {node} (table) Node 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}) *node_contains()* Determines if a node contains a range Parameters: ~ - {node} (table) The node - {range} (table) The range + {node} (table) + {range} (table) Return: ~ (boolean) True if the node contains the range +start({bufnr}, {lang}) *start()* + Start 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: +> + + 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}) *stop()* + Stop treesitter highlighting for a buffer + + Parameters: ~ + {bufnr} (number|nil) Buffer to stop highlighting (default: current + buffer) + ============================================================================== Lua module: vim.treesitter.language *treesitter-language* |