From 44180c355377cdfe2ca20f688702d71934124ece Mon Sep 17 00:00:00 2001 From: ElPiloto Date: Wed, 4 Nov 2020 17:13:00 +0000 Subject: doc: Supplement documentation for treesitter. - Describe query components (capture, match, pattern). Not well-described in tree-sitter documentation. - Describe Query() object. Not actually described anywhere in documenation. --- runtime/doc/treesitter.txt | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt index 072f2cd074..8bedc0153e 100644 --- a/runtime/doc/treesitter.txt +++ b/runtime/doc/treesitter.txt @@ -164,11 +164,28 @@ Tree-sitter queries are supported, with some limitations. Currently, the only supported match predicate is `eq?` (both comparing a capture against a string and two captures against each other). +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. + vim.treesitter.parse_query({lang}, {query}) *vim.treesitter.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| 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 information about + the {query}. + - `captures` contains the list of unique capture names defined in + {query}. + -` info.captures` also points to `captures`. + - `info.patterns` contains information about predicates. + + query:iter_captures({node}, {bufnr}, {start_row}, {end_row}) *query:iter_captures()* Iterate over all captures from all matches inside {node}. -- cgit From d1bed9677852cc610c64391df348a642851efda9 Mon Sep 17 00:00:00 2001 From: ElPiloto Date: Wed, 4 Nov 2020 19:55:12 +0000 Subject: doc: Fix treesitter doc PR. --- runtime/doc/treesitter.txt | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt index 8bedc0153e..9f0d529b9a 100644 --- a/runtime/doc/treesitter.txt +++ b/runtime/doc/treesitter.txt @@ -164,11 +164,11 @@ Tree-sitter queries are supported, with some limitations. Currently, the only supported match predicate is `eq?` (both comparing a capture against a string and two captures against each other). -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 +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 +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. vim.treesitter.parse_query({lang}, {query}) @@ -176,10 +176,10 @@ vim.treesitter.parse_query({lang}, {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| 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 information about - the {query}. + Returns a |lua-treesitter-query| 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 information about the {query}. - `captures` contains the list of unique capture names defined in {query}. -` info.captures` also points to `captures`. -- cgit From 9162cc5417f7d4a4063633e7e4b83b941c8da7cf Mon Sep 17 00:00:00 2001 From: Luis Piloto Date: Thu, 5 Nov 2020 09:14:33 +0000 Subject: Update runtime/doc/treesitter.txt Co-authored-by: Thomas Vigouroux --- runtime/doc/treesitter.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt index 9f0d529b9a..58cd535e98 100644 --- a/runtime/doc/treesitter.txt +++ b/runtime/doc/treesitter.txt @@ -176,7 +176,7 @@ vim.treesitter.parse_query({lang}, {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 |lua-treesitter-query| Query object which can be used to + 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 information about the {query}. -- cgit