diff options
Diffstat (limited to 'runtime/lua/vim')
| -rw-r--r-- | runtime/lua/vim/_meta/json.lua | 14 | ||||
| -rw-r--r-- | runtime/lua/vim/fs.lua | 10 | ||||
| -rw-r--r-- | runtime/lua/vim/treesitter/query.lua | 51 |
3 files changed, 46 insertions, 29 deletions
diff --git a/runtime/lua/vim/_meta/json.lua b/runtime/lua/vim/_meta/json.lua index 1a7e87db9c..0d59de5fa6 100644 --- a/runtime/lua/vim/_meta/json.lua +++ b/runtime/lua/vim/_meta/json.lua @@ -25,18 +25,18 @@ vim.json = {} --- ---@param str string Stringified JSON data. ---@param opts? table<string,any> Options table with keys: ---- - luanil: (table) Table with keys: ---- * object: (boolean) When true, converts `null` in JSON objects ---- to Lua `nil` instead of |vim.NIL|. ---- * array: (boolean) When true, converts `null` in JSON arrays ---- to Lua `nil` instead of |vim.NIL|. +--- - luanil: (table) Table with keys: +--- - object: (boolean) When true, converts `null` in JSON objects +--- to Lua `nil` instead of |vim.NIL|. +--- - array: (boolean) When true, converts `null` in JSON arrays +--- to Lua `nil` instead of |vim.NIL|. ---@return any function vim.json.decode(str, opts) end --- Encodes (or "packs") Lua object {obj} as JSON in a Lua string. ---@param obj any ---@param opts? table<string,any> Options table with keys: ---- - escape_slash: (boolean) (default false) When true, escapes `/` ---- character in JSON strings +--- - escape_slash: (boolean) (default false) Escape slash +--- characters "/" in string values. ---@return string function vim.json.encode(obj, opts) end diff --git a/runtime/lua/vim/fs.lua b/runtime/lua/vim/fs.lua index 1b774d5cab..d042df96e5 100644 --- a/runtime/lua/vim/fs.lua +++ b/runtime/lua/vim/fs.lua @@ -105,9 +105,13 @@ function M.basename(file) return file:match('/$') and '' or (file:match('[^/]*$')) end ---- Concatenates partial paths into one path. Slashes are normalized (redundant slashes are removed, and on Windows backslashes are replaced with forward-slashes) ---- (e.g., `"foo/"` and `"/bar"` get joined to `"foo/bar"`) ---- (windows: e.g `"a\foo\"` and `"\bar"` are joined to `"a/foo/bar"`) +--- Concatenates partial paths (one absolute or relative path followed by zero or more relative +--- paths). Slashes are normalized: redundant slashes are removed, and (on Windows) backslashes are +--- replaced with forward-slashes. +--- +--- Examples: +--- - "foo/", "/bar" => "foo/bar" +--- - Windows: "a\foo\", "\bar" => "a/foo/bar" --- ---@since 12 ---@param ... string diff --git a/runtime/lua/vim/treesitter/query.lua b/runtime/lua/vim/treesitter/query.lua index dbe3d54c2f..f9c497337f 100644 --- a/runtime/lua/vim/treesitter/query.lua +++ b/runtime/lua/vim/treesitter/query.lua @@ -1,3 +1,6 @@ +--- @brief This Lua |treesitter-query| interface allows you to create queries and use them to parse +--- text. See |vim.treesitter.query.parse()| for a working example. + local api = vim.api local language = require('vim.treesitter.language') local memoize = vim.func._memoize @@ -8,9 +11,9 @@ local M = {} ---Parsed query, see |vim.treesitter.query.parse()| --- ---@class vim.treesitter.Query ----@field lang string name of the language for this parser +---@field lang string parser language name ---@field captures string[] list of (unique) capture names defined in query ----@field info vim.treesitter.QueryInfo contains information used in the query (e.g. captures, predicates, directives) +---@field info vim.treesitter.QueryInfo query context (e.g. captures, predicates, directives) ---@field query TSQuery userdata query object local Query = {} Query.__index = Query @@ -228,20 +231,28 @@ M.get = memoize('concat-2', function(lang, query_name) return M.parse(lang, query_string) end) ---- 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 the `iter_captures` and `iter_matches` methods. +--- Parses a {query} string and returns a `Query` object (|lua-treesitter-query|), which can be used +--- to search the tree for the query patterns (via |Query:iter_captures()|, |Query:iter_matches()|), +--- or inspect the query via these fields: +--- - `captures`: a list of unique capture names defined in the query (alias: `info.captures`). +--- - `info.patterns`: information about predicates. --- ---- 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. +--- Example (select the code then run `:'<,'>lua` to try it): +--- ```lua +--- local query = vim.treesitter.query.parse('vimdoc', [[ +--- ; query +--- ((h1) @str +--- (#trim! @str 1 1 1 1)) +--- ]]) +--- local tree = vim.treesitter.get_parser():parse()[1] +--- for id, node, metadata in query:iter_captures(tree:root(), 0) do +--- -- Print the node name and source text. +--- vim.print({node:type(), vim.treesitter.get_node_text(node, vim.api.nvim_get_current_buf())}) +--- end +--- ``` --- ---@param lang string Language to use for the query ----@param query string Query in s-expr syntax +---@param query string Query text, in s-expr syntax --- ---@return vim.treesitter.Query : Parsed query --- @@ -847,20 +858,22 @@ local function match_id_hash(_, match) return (match:info()) end ---- Iterate over all captures from all matches inside {node} +--- Iterates over all captures from all matches in {node}. --- ---- {source} is needed if the query contains predicates; then the caller +--- {source} is required 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} and {stop} 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 {stop} row values are used from the given node. --- ---- The iterator returns four values: a numeric id identifying the capture, ---- the captured node, metadata from any directives processing the match, ---- and the match itself. ---- The following example shows how to get captures by name: +--- The iterator returns four values: +--- 1. the numeric id identifying the capture +--- 2. the captured node +--- 3. metadata from any directives processing the match +--- 4. the match itself --- +--- Example: how to get captures by name: --- ```lua --- for id, node, metadata, match in query:iter_captures(tree:root(), bufnr, first, last) do --- local name = query.captures[id] -- name of the capture in the query |