diff options
| -rw-r--r-- | runtime/doc/lua.txt | 40 | ||||
| -rw-r--r-- | runtime/lua/vim/treesitter.lua | 9 | ||||
| -rw-r--r-- | runtime/lua/vim/treesitter/highlighter.lua | 10 | ||||
| -rw-r--r-- | runtime/lua/vim/treesitter/language.lua | 13 | ||||
| -rw-r--r-- | runtime/lua/vim/treesitter/query.lua | 23 |
5 files changed, 70 insertions, 25 deletions
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 60c7a60d25..444e670514 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -574,6 +574,14 @@ 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. +Parser files *treesitter-parsers* + +Parsers are the heart of tree-sitter. They are libraries that tree-sitter will +search for in the `parsers` runtime directory. + +For a parser to be available for a given language, there must be a file named +`{lang}.so` within the parser directory. + Parser methods *lua-treesitter-parser* tsparser:parse() *tsparser:parse()* @@ -593,9 +601,9 @@ 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. -tsparser:set_included_ranges(ranges) *tsparser:set_included_ranges()* +tsparser:set_included_ranges({ranges}) *tsparser:set_included_ranges()* Changes the ranges the parser should consider. This is used for - language injection. `ranges` should be of the form (all zero-based): > + language injection. {ranges} should be of the form (all zero-based): > { {start_node, end_node}, ... @@ -617,15 +625,15 @@ tsnode:parent() *tsnode:parent()* tsnode:child_count() *tsnode:child_count()* Get the node's number of children. -tsnode:child(N) *tsnode:child()* - Get the node's child at the given index, where zero represents the +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(N) *tsnode:named_child()* - Get the node's named child at the given index, where zero represents +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()* @@ -661,12 +669,12 @@ tsnode:has_error() *tsnode:has_error()* tsnode:sexpr() *tsnode:sexpr()* Get an S-expression representing the node as a string. -tsnode:descendant_for_range(start_row, start_col, end_row, end_col) +tsnode:descendant_for_range({start_row}, {start_col}, {end_row}, {end_col}) *tsnode:descendant_for_range()* Get the smallest node within this node that spans the given range of (row, column) positions -tsnode:named_descendant_for_range(start_row, start_col, end_row, end_col) +tsnode:named_descendant_for_range({start_row}, {start_col}, {end_row}, {end_col}) *tsnode:named_descendant_for_range()* Get the smallest named node within this node that spans the given range of (row, column) positions @@ -677,17 +685,17 @@ 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). -vim.treesitter.parse_query(lang, query) - *vim.treesitter.parse_query(()* - Parse the query as a string. (If the query is in a file, the caller +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). -query:iter_captures(node, bufnr, start_row, end_row) +query:iter_captures({node}, {bufnr}, {start_row}, {end_row}) *query:iter_captures()* - Iterate over all captures from all matches inside a `node`. - `bufnr` is needed if the query contains predicates, then the caller + Iterate over all captures from all matches inside {node}. + {bufnr} 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. `start_row` and `end_row` can be used to limit + text of the buffer. {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) @@ -704,7 +712,7 @@ query:iter_captures(node, bufnr, start_row, end_row) ... use the info here ... end < -query:iter_matches(node, bufnr, start_row, end_row) +query:iter_matches({node}, {bufnr}, {start_row}, {end_row}) *query:iter_matches()* Iterate over all matches within a node. The arguments are the same as for |query:iter_captures()| but the iterated values are different: diff --git a/runtime/lua/vim/treesitter.lua b/runtime/lua/vim/treesitter.lua index f43c8a872d..550dee1e3f 100644 --- a/runtime/lua/vim/treesitter.lua +++ b/runtime/lua/vim/treesitter.lua @@ -10,6 +10,12 @@ local parsers = {} local Parser = {} Parser.__index = Parser +--- Parses the buffer if needed and returns a tree. +-- +-- Calling this will call the on_changedtree callbacks if the tree has changed. +-- +-- @returns An up to date tree +-- @returns If the tree changed with this call, the changed ranges function Parser:parse() if self.valid then return self.tree @@ -40,6 +46,9 @@ function Parser:_on_lines(bufnr, changed_tick, start_row, old_stop_row, stop_row end end +--- Sets the included ranges for the current parser +-- +-- @param ranges A table of nodes that will be used as the ranges the parser should include. function Parser:set_included_ranges(ranges) self._parser:set_included_ranges(ranges) -- The buffer will need to be parsed again later diff --git a/runtime/lua/vim/treesitter/highlighter.lua b/runtime/lua/vim/treesitter/highlighter.lua index b410f01092..681d2c6324 100644 --- a/runtime/lua/vim/treesitter/highlighter.lua +++ b/runtime/lua/vim/treesitter/highlighter.lua @@ -7,9 +7,6 @@ local ts_hs_ns = a.nvim_create_namespace("treesitter_hl") -- These are conventions defined by tree-sitter, though it -- needs to be user extensible also. --- TODO(bfredl): this is very much incomplete, we will need to --- go through a few tree-sitter provided queries and decide --- on translations that makes the most sense. TSHighlighter.hl_map = { ["error"] = "Error", @@ -112,11 +109,8 @@ function TSHighlighter:set_query(query) query = vim.treesitter.get_query(self.parser.lang, 'highlights') if query == nil then - a.err_writeln("No highlights.scm query found for " .. self.parser.lang) - - if query == nil then - query = vim.treesitter.parse_query(self.parser.lang, "") - end + a.nvim_err_writeln("No highlights.scm query found for " .. self.parser.lang) + query = vim.treesitter.parse_query(self.parser.lang, "") end end diff --git a/runtime/lua/vim/treesitter/language.lua b/runtime/lua/vim/treesitter/language.lua index b4817de91e..a7e36a0b89 100644 --- a/runtime/lua/vim/treesitter/language.lua +++ b/runtime/lua/vim/treesitter/language.lua @@ -2,6 +2,12 @@ local a = vim.api local M = {} +--- Asserts that the provided language is installed, and optionnaly provide a path for the parser +-- +-- Parsers are searched in the `parser` runtime directory. +-- +-- @param lang The language the parser should parse +-- @param path Optionnal path the parser is located at function M.require_language(lang, path) if vim._ts_has_language(lang) then return true @@ -11,13 +17,18 @@ function M.require_language(lang, path) local paths = a.nvim_get_runtime_file(fname, false) if #paths == 0 then -- TODO(bfredl): help tag? - error("no parser for '"..lang.."' language") + error("no parser for '"..lang.."' language, see :help treesitter-parsers") end path = paths[1] end vim._ts_add_language(path, lang) end +--- Inspects the provided language. +-- +-- Inspecting provides some useful informations on the language like node names, ... +-- +-- @param lang The language. function M.inspect_language(lang) M.require_language(lang) return vim._ts_inspect_language(lang) diff --git a/runtime/lua/vim/treesitter/query.lua b/runtime/lua/vim/treesitter/query.lua index 914c266426..d16e1c3662 100644 --- a/runtime/lua/vim/treesitter/query.lua +++ b/runtime/lua/vim/treesitter/query.lua @@ -67,6 +67,11 @@ local predicate_handlers = { end, } +--- Adds a new predicates to be used in queries +-- +-- @param name the name of the predicate, without leading # +-- @param handler the handler function to be used +-- signature will be (match, pattern, bufnr, predicate) function M.add_predicate(name, handler) if predicate_handlers[name] then a.nvim_err_writeln("It is recomended to not overwrite predicates.") @@ -93,6 +98,15 @@ function Query:match_preds(match, pattern, bufnr) return true end +--- Iterates of the captures of self on a given range. +-- +-- @param node The node under witch the search will occur +-- @param buffer The source buffer to search +-- @param start The starting line of the search +-- @param stop The stoping line of the search (end-exclusive) +-- +-- @returns The matching capture id +-- @returns The captured node function Query:iter_captures(node, bufnr, start, stop) if bufnr == 0 then bufnr = vim.api.nvim_get_current_buf() @@ -112,6 +126,15 @@ function Query:iter_captures(node, bufnr, start, stop) return iter end +--- Iterates of the matches of self on a given range. +-- +-- @param node The node under witch the search will occur +-- @param buffer The source buffer to search +-- @param start The starting line of the search +-- @param stop The stoping line of the search (end-exclusive) +-- +-- @returns The matching pattern id +-- @returns The matching match function Query:iter_matches(node, bufnr, start, stop) if bufnr == 0 then bufnr = vim.api.nvim_get_current_buf() |