feat(treesitter)!: deprecate top level indexes to modules (#22761)

The following top level Treesitter functions have been moved: - vim.treesitter.inspect_language() -> vim.treesitter.language.inspect() - vim.treesitter.get_query_files() -> vim.treesitter.query.get_files() - vim.treesitter.set_query() -> vim.treesitter.query.set() - vim.treesitter.query.set_query() -> vim.treesitter.query.set() - vim.treesitter.get_query() -> vim.treesitter.query.get() - vim.treesitter.query.get_query() -> vim.treesitter.query.get() - vim.treesitter.parse_query() -> vim.treesitter.query.parse() - vim.treesitter.query.parse_query() -> vim.treesitter.query.parse() - vim.treesitter.add_predicate() -> vim.treesitter.query.add_predicate() - vim.treesitter.add_directive() -> vim.treesitter.query.add_directive() - vim.treesitter.list_predicates() -> vim.treesitter.query.list_predicates() - vim.treesitter.list_directives() -> vim.treesitter.query.list_directives() - vim.treesitter.query.get_range() -> vim.treesitter.get_range() - vim.treesitter.query.get_node_text() -> vim.treesitter.get_node_text()
2025-12-16 03:15:39 +00:00 · 2023-03-24 14:43:14 +00:00
parent ee5008f878
commit cbbf8bd666
13 changed files with 258 additions and 177 deletions
--- a/runtime/lua/vim/treesitter.lua
+++ b/runtime/lua/vim/treesitter.lua
@@ -1,6 +1,4 @@
 local a = vim.api
-local query = require('vim.treesitter.query')
-local language = require('vim.treesitter.language')
 local LanguageTree = require('vim.treesitter.languagetree')
 local Range = require('vim.treesitter._range')

@@ -9,12 +7,9 @@ local parsers = setmetatable({}, { __mode = 'v' })

 ---@class TreesitterModule
 ---@field highlighter TSHighlighter
-local M = vim.tbl_extend('error', query, language)
-
-M.language_version = vim._ts_get_language_version()
-M.minimum_language_version = vim._ts_get_minimum_language_version()
-
-setmetatable(M, {
+---@field query TSQueryModule
+---@field language TSLanguageModule
+local M = setmetatable({}, {
  __index = function(t, k)
    ---@diagnostic disable:no-unknown
    if k == 'highlighter' then
@@ -27,9 +22,26 @@ setmetatable(M, {
      t[k] = require('vim.treesitter.query')
      return t[k]
    end
+
+    local query = require('vim.treesitter.query')
+    if query[k] then
+      vim.deprecate('vim.treesitter.' .. k .. '()', 'vim.treesitter.query.' .. k .. '()', '0.10')
+      t[k] = query[k]
+      return t[k]
+    end
+
+    local language = require('vim.treesitter.language')
+    if language[k] then
+      vim.deprecate('vim.treesitter.' .. k .. '()', 'vim.treesitter.language.' .. k .. '()', '0.10')
+      t[k] = language[k]
+      return t[k]
+    end
  end,
 })

+M.language_version = vim._ts_get_language_version()
+M.minimum_language_version = vim._ts_get_minimum_language_version()
+
 --- Creates a new parser
 ---
 --- It is not recommended to use this; use |get_parser()| instead.
@@ -47,7 +59,7 @@ function M._create_parser(bufnr, lang, opts)
  vim.fn.bufload(bufnr)

  local ft = vim.bo[bufnr].filetype
-  language.add(lang, { filetype = ft ~= '' and ft or nil })
+  M.language.add(lang, { filetype = ft ~= '' and ft or nil })

  local self = LanguageTree.new(bufnr, lang, opts)

@@ -101,7 +113,7 @@ function M.get_parser(bufnr, lang, opts)
  if lang == nil then
    local ft = vim.bo[bufnr].filetype
    if ft ~= '' then
-      lang = language.get_lang(ft) or ft
+      lang = M.language.get_lang(ft) or ft
      -- TODO(lewis6991): we should error here and not default to ft
      -- if not lang then
      --   error(string.format('filetype %s of buffer %d is not associated with any lang', ft, bufnr))
@@ -152,7 +164,7 @@ function M.get_string_parser(str, lang, opts)
    str = { str, 'string' },
    lang = { lang, 'string' },
  })
-  language.add(lang)
+  M.language.add(lang)

  return LanguageTree.new(str, lang, opts)
 end
@@ -196,6 +208,61 @@ function M.get_node_range(node_or_range)
  end
 end

+---Get the range of a |TSNode|. Can also supply {source} and {metadata}
+---to get the range with directives applied.
+---@param node TSNode
+---@param source integer|string|nil Buffer or string from which the {node} is extracted
+---@param metadata TSMetadata|nil
+---@return Range6
+function M.get_range(node, source, metadata)
+  if metadata and metadata.range then
+    assert(source)
+    return Range.add_bytes(source, metadata.range)
+  end
+  return { node:range(true) }
+end
+
+---@private
+---@param buf integer
+---@param range Range
+---@returns string
+local function buf_range_get_text(buf, range)
+  local start_row, start_col, end_row, end_col = Range.unpack4(range)
+  if end_col == 0 then
+    if start_row == end_row then
+      start_col = -1
+      start_row = start_row - 1
+    end
+    end_col = -1
+    end_row = end_row - 1
+  end
+  local lines = a.nvim_buf_get_text(buf, start_row, start_col, end_row, end_col, {})
+  return table.concat(lines, '\n')
+end
+
+--- Gets the text corresponding to a given node
+---
+---@param node TSNode
+---@param source (integer|string) Buffer or string from which the {node} is extracted
+---@param opts (table|nil) Optional parameters.
+---          - metadata (table) Metadata of a specific capture. This would be
+---            set to `metadata[capture_id]` when using |vim.treesitter.query.add_directive()|.
+---@return string
+function M.get_node_text(node, source, opts)
+  opts = opts or {}
+  local metadata = opts.metadata or {}
+
+  if metadata.text then
+    return metadata.text
+  elseif type(source) == 'number' then
+    local range = vim.treesitter.get_range(node, source, metadata)
+    return buf_range_get_text(source, range)
+  end
+
+  ---@cast source string
+  return source:sub(select(3, node:start()) + 1, select(3, node:end_()))
+end
+
 --- Determines whether (line, col) position is in node range
 ---
 ---@param node TSNode defining the range
--- a/runtime/lua/vim/treesitter/highlighter.lua
+++ b/runtime/lua/vim/treesitter/highlighter.lua
@@ -1,5 +1,5 @@
 local a = vim.api
-local query = require('vim.treesitter.query')
+local query = vim.treesitter.query

 ---@alias TSHlIter fun(): integer, TSNode, TSMetadata

@@ -45,9 +45,9 @@ function TSHighlighterQuery.new(lang, query_string)
  })

  if query_string then
-    self._query = query.parse_query(lang, query_string)
+    self._query = query.parse(lang, query_string)
  else
-    self._query = query.get_query(lang, 'highlights')
+    self._query = query.get(lang, 'highlights')
  end

  return self
--- a/runtime/lua/vim/treesitter/language.lua
+++ b/runtime/lua/vim/treesitter/language.lua
@@ -1,5 +1,6 @@
 local a = vim.api

+---@class TSLanguageModule
 local M = {}

 ---@type table<string,string>
@@ -111,9 +112,19 @@ end
 ---
 ---@param lang string Language
 ---@return table
-function M.inspect_language(lang)
+function M.inspect(lang)
  M.add(lang)
  return vim._ts_inspect_language(lang)
 end

+---@deprecated
+function M.inspect_language(...)
+  vim.deprecate(
+    'vim.treesitter.language.inspect_language()',
+    'vim.treesitter.language.inspect()',
+    '0.10'
+  )
+  return M.inspect(...)
+end
+
 return M
--- a/runtime/lua/vim/treesitter/languagetree.lua
+++ b/runtime/lua/vim/treesitter/languagetree.lua
@@ -99,8 +99,8 @@ function LanguageTree.new(source, lang, opts)
    _regions = {},
    _trees = {},
    _opts = opts,
-    _injection_query = injections[lang] and query.parse_query(lang, injections[lang])
-      or query.get_query(lang, 'injections'),
+    _injection_query = injections[lang] and query.parse(lang, injections[lang])
+      or query.get(lang, 'injections'),
    _valid = false,
    _parser = vim._create_ts_parser(lang),
    _callbacks = {
@@ -482,7 +482,7 @@ end
 ---@param metadata TSMetadata
 ---@return Range6[]
 local function get_node_ranges(node, source, metadata, include_children)
-  local range = query.get_range(node, source, metadata)
+  local range = vim.treesitter.get_range(node, source, metadata)

  if include_children then
    return { range }
@@ -562,7 +562,7 @@ function LanguageTree:_get_injection(match, metadata)

    -- Lang should override any other language tag
    if name == 'injection.language' then
-      lang = query.get_node_text(node, self._source, { metadata = metadata[id] })
+      lang = vim.treesitter.get_node_text(node, self._source, { metadata = metadata[id] })
    elseif name == 'injection.content' then
      ranges = get_node_ranges(node, self._source, metadata[id], include_children)
    end
@@ -609,11 +609,11 @@ function LanguageTree:_get_injection_deprecated(match, metadata)

    -- Lang should override any other language tag
    if name == 'language' and not lang then
-      lang = query.get_node_text(node, self._source, { metadata = metadata[id] })
+      lang = vim.treesitter.get_node_text(node, self._source, { metadata = metadata[id] })
    elseif name == 'combined' then
      combined = true
    elseif name == 'content' and #ranges == 0 then
-      ranges[#ranges + 1] = query.get_range(node, self._source, metadata[id])
+      ranges[#ranges + 1] = vim.treesitter.get_range(node, self._source, metadata[id])
      -- Ignore any tags that start with "_"
      -- Allows for other tags to be used in matches
    elseif string.sub(name, 1, 1) ~= '_' then
@@ -622,7 +622,7 @@ function LanguageTree:_get_injection_deprecated(match, metadata)
      end

      if #ranges == 0 then
-        ranges[#ranges + 1] = query.get_range(node, self._source, metadata[id])
+        ranges[#ranges + 1] = vim.treesitter.get_range(node, self._source, metadata[id])
      end
    end
  end
--- a/runtime/lua/vim/treesitter/query.lua
+++ b/runtime/lua/vim/treesitter/query.lua
@@ -1,8 +1,6 @@
 local a = vim.api
 local language = require('vim.treesitter.language')

-local Range = require('vim.treesitter._range')
-
 ---@class Query
 ---@field captures string[] List of captures used in query
 ---@field info TSQueryInfo Contains used queries, predicates, directives
@@ -14,6 +12,7 @@ Query.__index = Query
 ---@field captures table
 ---@field patterns table<string,any[][]>

+---@class TSQueryModule
 local M = {}

 ---@private
@@ -57,22 +56,14 @@ local function add_included_lang(base_langs, lang, ilang)
  return false
 end

---@private
---@param buf integer
---@param range Range
---@returns string
-local function buf_range_get_text(buf, range)
-  local start_row, start_col, end_row, end_col = Range.unpack4(range)
-  if end_col == 0 then
-    if start_row == end_row then
-      start_col = -1
-      start_row = start_row - 1
-    end
-    end_col = -1
-    end_row = end_row - 1
-  end
-  local lines = a.nvim_buf_get_text(buf, start_row, start_col, end_row, end_col, {})
-  return table.concat(lines, '\n')
+---@deprecated
+function M.get_query_files(...)
+  vim.deprecate(
+    'vim.treesitter.query.get_query_files()',
+    'vim.treesitter.query.get_files()',
+    '0.10'
+  )
+  return M.get_files(...)
 end

 --- Gets the list of files used to make up a query
@@ -81,7 +72,7 @@ end
 ---@param query_name string Name of the query to load (e.g., "highlights")
 ---@param is_included (boolean|nil) Internal parameter, most of the time left as `nil`
 ---@return string[] query_files List of files to load for given query and language
-function M.get_query_files(lang, query_name, is_included)
+function M.get_files(lang, query_name, is_included)
  local query_path = string.format('queries/%s/%s.scm', lang, query_name)
  local lang_files = dedupe_files(a.nvim_get_runtime_file(query_path, true))

@@ -153,7 +144,7 @@ function M.get_query_files(lang, query_name, is_included)

  local query_files = {}
  for _, base_lang in ipairs(base_langs) do
-    local base_files = M.get_query_files(base_lang, query_name, true)
+    local base_files = M.get_files(base_lang, query_name, true)
    vim.list_extend(query_files, base_files)
  end
  vim.list_extend(query_files, { base_query })
@@ -175,7 +166,7 @@ local function read_query_files(filenames)
  return table.concat(contents, '')
 end

-- The explicitly set queries from |vim.treesitter.query.set_query()|
+-- The explicitly set queries from |vim.treesitter.query.set()|
 ---@type table<string,table<string,Query>>
 local explicit_queries = setmetatable({}, {
  __index = function(t, k)
@@ -186,6 +177,12 @@ local explicit_queries = setmetatable({}, {
  end,
 })

+---@deprecated
+function M.set_query(...)
+  vim.deprecate('vim.treesitter.query.set_query()', 'vim.treesitter.query.set()', '0.10')
+  M.set(...)
+end
+
 --- Sets the runtime query named {query_name} for {lang}
 ---
 --- This allows users to override any runtime files and/or configuration
@@ -194,8 +191,17 @@ local explicit_queries = setmetatable({}, {
 ---@param lang string Language to use for the query
 ---@param query_name string Name of the query (e.g., "highlights")
 ---@param text string Query text (unparsed).
-function M.set_query(lang, query_name, text)
-  explicit_queries[lang][query_name] = M.parse_query(lang, text)
+function M.set(lang, query_name, text)
+  explicit_queries[lang][query_name] = M.parse(lang, text)
+end
+
+---@deprecated
+---@param lang string Language to use for the query
+---@param query_name string Name of the query (e.g. "highlights")
+---
+---@return Query|nil Parsed query
+function M.get_query(lang, query_name)
+  return M.get(lang, query_name)
 end

 --- Returns the runtime query {query_name} for {lang}.
@@ -204,16 +210,16 @@ end
 ---@param query_name string Name of the query (e.g. "highlights")
 ---
 ---@return Query|nil Parsed query
-function M.get_query(lang, query_name)
+function M.get(lang, query_name)
  if explicit_queries[lang][query_name] then
    return explicit_queries[lang][query_name]
  end

-  local query_files = M.get_query_files(lang, query_name)
+  local query_files = M.get_files(lang, query_name)
  local query_string = read_query_files(query_files)

  if #query_string > 0 then
-    return M.parse_query(lang, query_string)
+    return M.parse(lang, query_string)
  end
 end

@@ -222,6 +228,12 @@ local query_cache = vim.defaulttable(function()
  return setmetatable({}, { __mode = 'v' })
 end)

+---@deprecated
+function M.parse_query(...)
+  vim.deprecate('vim.treesitter.query.parse_query()', 'vim.treesitter.query.parse()', '0.10')
+  return M.parse(...)
+end
+
 --- Parse {query} as a string. (If the query is in a file, the caller
 --- should read the contents into a string before calling).
 ---
@@ -239,7 +251,7 @@ end)
 ---@param query string Query in s-expr syntax
 ---
 ---@return Query Parsed query
-function M.parse_query(lang, query)
+function M.parse(lang, query)
  language.add(lang)
  local cached = query_cache[lang][query]
  if cached then
@@ -254,41 +266,16 @@ function M.parse_query(lang, query)
  return self
 end

---Get the range of a |TSNode|. Can also supply {source} and {metadata}
---to get the range with directives applied.
---@param node TSNode
---@param source integer|string|nil Buffer or string from which the {node} is extracted
---@param metadata TSMetadata|nil
---@return Range6
-function M.get_range(node, source, metadata)
-  if metadata and metadata.range then
-    assert(source)
-    return Range.add_bytes(source, metadata.range)
-  end
-  return { node:range(true) }
+---@deprecated
+function M.get_range(...)
+  vim.deprecate('vim.treesitter.query.get_range()', 'vim.treesitter.get_range()', '0.10')
+  return vim.treesitter.get_range(...)
 end

--- Gets the text corresponding to a given node
---
---@param node TSNode
---@param source (integer|string) Buffer or string from which the {node} is extracted
---@param opts (table|nil) Optional parameters.
---          - metadata (table) Metadata of a specific capture. This would be
---            set to `metadata[capture_id]` when using |vim.treesitter.add_directive()|.
---@return string
-function M.get_node_text(node, source, opts)
-  opts = opts or {}
-  local metadata = opts.metadata or {}
-
-  if metadata.text then
-    return metadata.text
-  elseif type(source) == 'number' then
-    local range = M.get_range(node, source, metadata)
-    return buf_range_get_text(source, range)
-  end
-
-  ---@cast source string
-  return source:sub(select(3, node:start()) + 1, select(3, node:end_()))
+---@deprecated
+function M.get_node_text(...)
+  vim.deprecate('vim.treesitter.query.get_node_text()', 'vim.treesitter.get_node_text()', '0.10')
+  return vim.treesitter.get_node_text(...)
 end

 ---@alias TSMatch table<integer,TSNode>
@@ -304,7 +291,7 @@ local predicate_handlers = {
    if not node then
      return true
    end
-    local node_text = M.get_node_text(node, source)
+    local node_text = vim.treesitter.get_node_text(node, source)

    local str ---@type string
    if type(predicate[3]) == 'string' then
@@ -312,7 +299,7 @@ local predicate_handlers = {
      str = predicate[3]
    else
      -- (#eq? @aa @bb)
-      str = M.get_node_text(match[predicate[3]], source)
+      str = vim.treesitter.get_node_text(match[predicate[3]], source)
    end

    if node_text ~= str or str == nil then
@@ -328,7 +315,7 @@ local predicate_handlers = {
      return true
    end
    local regex = predicate[3]
-    return string.find(M.get_node_text(node, source), regex) ~= nil
+    return string.find(vim.treesitter.get_node_text(node, source), regex) ~= nil
  end,

  ['match?'] = (function()
@@ -357,7 +344,7 @@ local predicate_handlers = {
      end
      ---@diagnostic disable-next-line no-unknown
      local regex = compiled_vim_regexes[pred[3]]
-      return regex:match_str(M.get_node_text(node, source))
+      return regex:match_str(vim.treesitter.get_node_text(node, source))
    end
  end)(),

@@ -366,7 +353,7 @@ local predicate_handlers = {
    if not node then
      return true
    end
-    local node_text = M.get_node_text(node, source)
+    local node_text = vim.treesitter.get_node_text(node, source)

    for i = 3, #predicate do
      if string.find(node_text, predicate[i], 1, true) then
@@ -382,7 +369,7 @@ local predicate_handlers = {
    if not node then
      return true
    end
-    local node_text = M.get_node_text(node, source)
+    local node_text = vim.treesitter.get_node_text(node, source)

    -- Since 'predicate' will not be used by callers of this function, use it
    -- to store a string set built from the list of words to check against.
@@ -468,7 +455,7 @@ local directive_handlers = {
    assert(type(id) == 'number')

    local node = match[id]
-    local text = M.get_node_text(node, bufnr, { metadata = metadata[id] }) or ''
+    local text = vim.treesitter.get_node_text(node, bufnr, { metadata = metadata[id] }) or ''

    if not metadata[id] then
      metadata[id] = {}
@@ -486,7 +473,7 @@ local directive_handlers = {
 ---
 ---@param name string Name of the predicate, without leading #
 ---@param handler function(match:table<string,TSNode>, pattern:string, bufnr:integer, predicate:string[])
---   - see |vim.treesitter.add_directive()| for argument meanings
+---   - see |vim.treesitter.query.add_directive()| for argument meanings
 ---@param force boolean|nil
 function M.add_predicate(name, handler, force)
  if predicate_handlers[name] and not force then