diff options
Diffstat (limited to 'runtime/doc/treesitter.txt')
| -rw-r--r-- | runtime/doc/treesitter.txt | 202 |
1 files changed, 151 insertions, 51 deletions
diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt index c836ccec8c..917863eef8 100644 --- a/runtime/doc/treesitter.txt +++ b/runtime/doc/treesitter.txt @@ -24,7 +24,7 @@ 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: > +A parser can also be loaded manually using a full path: >lua vim.treesitter.require_language("python", "/path/to/python.so") < @@ -37,7 +37,7 @@ 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 > +use >lua tsparser = vim.treesitter.get_parser(bufnr, lang) < @@ -46,7 +46,7 @@ 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: > +Whenever you need to access the current syntax tree, parse the buffer: >lua tstree = tsparser:parse() < @@ -56,11 +56,11 @@ current state of the buffer. When the plugin wants to access the state after a 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 |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. +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. @@ -212,7 +212,7 @@ 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: > +nodes. For example, the `eq?` predicate can be used as follows: > ((identifier) @foo (#eq? @foo "foo")) < @@ -239,7 +239,7 @@ The following predicates are built in: `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")) + ((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 @@ -253,15 +253,15 @@ The following predicates are built in: 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 +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!| predicate sets metadata on the match or node: > +effects. For example, the `set!` directive sets metadata on the match or node: > ((identifier) @foo (#set! "type" "parameter")) < @@ -297,8 +297,8 @@ The following directives are built in: ((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 +Further directives can be added via |vim.treesitter.query.add_directive()|. +Use |vim.treesitter.query.list_directives()| to list all available directives. @@ -366,12 +366,65 @@ 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: > +instance, to highlight comments differently per language: >vim hi @comment.c guifg=Blue - hi @comment.lua @guifg=DarkBlue + 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 @@ -379,6 +432,9 @@ 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 @@ -425,7 +481,8 @@ library. ============================================================================== Lua module: vim.treesitter *lua-treesitter-core* -get_captures_at_cursor({winnr}) *get_captures_at_cursor()* + *vim.treesitter.get_captures_at_cursor()* +get_captures_at_cursor({winnr}) Returns a list of highlight capture names under the cursor Parameters: ~ @@ -434,7 +491,8 @@ get_captures_at_cursor({winnr}) *get_captures_at_cursor()* Return: ~ string[] List of capture names -get_captures_at_pos({bufnr}, {row}, {col}) *get_captures_at_pos()* + *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 @@ -450,7 +508,7 @@ get_captures_at_pos({bufnr}, {row}, {col}) *get_captures_at_pos()* table[] List of captures `{ capture = "capture name", metadata = { ... } }` -get_node_at_cursor({winnr}) *get_node_at_cursor()* +get_node_at_cursor({winnr}) *vim.treesitter.get_node_at_cursor()* Returns the smallest named node under the cursor Parameters: ~ @@ -459,7 +517,8 @@ get_node_at_cursor({winnr}) *get_node_at_cursor()* Return: ~ (string) Name of node under the cursor -get_node_at_pos({bufnr}, {row}, {col}, {opts}) *get_node_at_pos()* + *vim.treesitter.get_node_at_pos()* +get_node_at_pos({bufnr}, {row}, {col}, {opts}) Returns the smallest named node at the given position Parameters: ~ @@ -467,13 +526,14 @@ get_node_at_pos({bufnr}, {row}, {col}, {opts}) *get_node_at_pos()* • {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 |tsnode| under the cursor + userdata|nil |tsnode| under the cursor -get_node_range({node_or_range}) *get_node_range()* +get_node_range({node_or_range}) *vim.treesitter.get_node_range()* Returns the node's range or an unpacked range table Parameters: ~ @@ -482,7 +542,7 @@ get_node_range({node_or_range}) *get_node_range()* Return: ~ (table) `{ start_row, start_col, end_row, end_col }` -get_parser({bufnr}, {lang}, {opts}) *get_parser()* +get_parser({bufnr}, {lang}, {opts}) *vim.treesitter.get_parser()* Returns the parser for a specific buffer and filetype and attaches it to the buffer @@ -498,7 +558,8 @@ get_parser({bufnr}, {lang}, {opts}) *get_parser()* Return: ~ LanguageTree |LanguageTree| object to use for parsing -get_string_parser({str}, {lang}, {opts}) *get_string_parser()* + *vim.treesitter.get_string_parser()* +get_string_parser({str}, {lang}, {opts}) Returns a string parser Parameters: ~ @@ -509,7 +570,7 @@ get_string_parser({str}, {lang}, {opts}) *get_string_parser()* Return: ~ LanguageTree |LanguageTree| object to use for parsing -is_ancestor({dest}, {source}) *is_ancestor()* +is_ancestor({dest}, {source}) *vim.treesitter.is_ancestor()* Determines whether a node is the ancestor of another Parameters: ~ @@ -519,7 +580,8 @@ is_ancestor({dest}, {source}) *is_ancestor()* Return: ~ (boolean) True if {dest} is an ancestor of {source} -is_in_node_range({node}, {line}, {col}) *is_in_node_range()* + *vim.treesitter.is_in_node_range()* +is_in_node_range({node}, {line}, {col}) Determines whether (line, col) position is in node range Parameters: ~ @@ -530,7 +592,7 @@ is_in_node_range({node}, {line}, {col}) *is_in_node_range()* Return: ~ (boolean) True if the position is in node range -node_contains({node}, {range}) *node_contains()* +node_contains({node}, {range}) *vim.treesitter.node_contains()* Determines if a node contains a range Parameters: ~ @@ -540,7 +602,32 @@ node_contains({node}, {range}) *node_contains()* Return: ~ (boolean) True if the {node} contains the {range} -start({bufnr}, {lang}) *start()* +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 + <Enter> 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. @@ -549,7 +636,7 @@ start({bufnr}, {lang}) *start()* required for some plugins. In this case, add `vim.bo.syntax = 'on'` after the call to `start`. - Example: > + Example: >lua vim.api.nvim_create_autocmd( 'FileType', { pattern = 'tex', callback = function(args) @@ -565,7 +652,7 @@ start({bufnr}, {lang}) *start()* • {lang} (string|nil) Language of the parser (default: buffer filetype) -stop({bufnr}) *stop()* +stop({bufnr}) *vim.treesitter.stop()* Stops treesitter highlighting for a buffer Parameters: ~ @@ -576,7 +663,7 @@ stop({bufnr}) *stop()* ============================================================================== Lua module: vim.treesitter.language *lua-treesitter-language* -inspect_language({lang}) *inspect_language()* +inspect_language({lang}) *vim.treesitter.language.inspect_language()* Inspects the provided language. Inspecting provides some useful information on the language like node @@ -588,7 +675,7 @@ inspect_language({lang}) *inspect_language()* Return: ~ (table) - *require_language()* + *vim.treesitter.language.require_language()* require_language({lang}, {path}, {silent}, {symbol_name}) Asserts that a parser for the language {lang} is installed. @@ -610,7 +697,8 @@ require_language({lang}, {path}, {silent}, {symbol_name}) ============================================================================== Lua module: vim.treesitter.query *lua-treesitter-query* -add_directive({name}, {handler}, {force}) *add_directive()* + *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 @@ -620,18 +708,29 @@ add_directive({name}, {handler}, {force}) *add_directive()* Parameters: ~ • {name} (string) Name of the directive, without leading # - • {handler} function(match:string, pattern:string, bufnr:number, - predicate:function, metadata:table) - -add_predicate({name}, {handler}, {force}) *add_predicate()* + • {handler} function(match:table, pattern:string, bufnr:number, + predicate:string[], metadata:table) + • match: see |treesitter-query| + • node-level data are accessible via `match[capture_id]` + + • pattern: see |treesitter-query| + • predicate: list of strings containing the full directive + being called, e.g. `(node (#set! conceal "-"))` would get + the predicate `{ "#set!", "conceal", "-" }` + + *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) + • {handler} function(match:table, pattern:string, bufnr:number, + predicate:string[]) + • see |vim.treesitter.query.add_directive()| for argument + meanings -get_node_text({node}, {source}, {opts}) *get_node_text()* + *vim.treesitter.query.get_node_text()* +get_node_text({node}, {source}, {opts}) Gets the text corresponding to a given node Parameters: ~ @@ -645,7 +744,7 @@ get_node_text({node}, {source}, {opts}) *get_node_text()* Return: ~ (string[]|string) -get_query({lang}, {query_name}) *get_query()* +get_query({lang}, {query_name}) *vim.treesitter.query.get_query()* Returns the runtime query {query_name} for {lang}. Parameters: ~ @@ -655,7 +754,7 @@ get_query({lang}, {query_name}) *get_query()* Return: ~ Query Parsed query - *get_query_files()* + *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 @@ -669,19 +768,19 @@ get_query_files({lang}, {query_name}, {is_included}) string[] query_files List of files to load for given query and language -list_directives() *list_directives()* +list_directives() *vim.treesitter.query.list_directives()* Lists the currently available directives to use in queries. Return: ~ string[] List of supported directives. -list_predicates() *list_predicates()* +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}) *parse_query()* +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). @@ -714,7 +813,7 @@ Query:iter_captures({self}, {node}, {source}, {start}, {stop}) 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: > + 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 @@ -746,7 +845,7 @@ Query:iter_matches({self}, {node}, {source}, {start}, {stop}) (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: > + 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 @@ -772,7 +871,8 @@ Query:iter_matches({self}, {node}, {source}, {start}, {stop}) (table) match (table) metadata -set_query({lang}, {query_name}, {text}) *set_query()* + *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 @@ -787,7 +887,7 @@ set_query({lang}, {query_name}, {text}) *set_query()* ============================================================================== Lua module: vim.treesitter.highlighter *lua-treesitter-highlighter* -new({tree}, {opts}) *highlighter.new()* +new({tree}, {opts}) *vim.treesitter.highlighter.new()* Creates a new highlighter using Parameters: ~ @@ -958,7 +1058,7 @@ LanguageTree:trees({self}) *LanguageTree:trees()* Parameters: ~ • {self} -new({source}, {lang}, {opts}) *languagetree.new()* +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). |