feat(treesitter): add filetype -> lang API

Problem:

  vim.treesitter does not know how to map a specific filetype to a parser.

  This creates problems since in a few places (including in vim.treesitter itself), the filetype is incorrectly used in place of lang.

Solution:

  Add an API to enable this:

  - Add vim.treesitter.language.add() as a replacement for vim.treesitter.language.require_language().
    - Optional arguments are now passed via an opts table.
    - Also takes a filetype (or list of filetypes) so we can keep track of what filetypes are associated with which langs.
    - Deprecated vim.treesitter.language.require_language().
  - Add vim.treesitter.language.get_lang() which returns the associated lang for a given filetype.
  - Add vim.treesitter.language.register() to associate filetypes to a lang without loading the parser.

runtime/lua/vim/treesitter.lua

@@ -29,6 +29,8 @@ setmetatable(M, {
   end,
 })
 
+---@diagnostic disable:invisible
+
 --- Creates a new parser
 ---
 --- It is not recommended to use this; use |get_parser()| instead.
@@ -39,16 +41,15 @@ setmetatable(M, {
 ---
 ---@return LanguageTree object to use for parsing
 function M._create_parser(bufnr, lang, opts)
-  language.require_language(lang)
   if bufnr == 0 then
     bufnr = vim.api.nvim_get_current_buf()
   end
 
   vim.fn.bufload(bufnr)
 
-  local self = LanguageTree.new(bufnr, lang, opts)
+  language.add(lang, { filetype = vim.bo[bufnr].filetype })
 
-  ---@diagnostic disable:invisible
+  local self = LanguageTree.new(bufnr, lang, opts)
 
   ---@private
   local function bytes_cb(_, ...)
@@ -96,13 +97,16 @@ function M.get_parser(bufnr, lang, opts)
   if bufnr == nil or bufnr == 0 then
     bufnr = a.nvim_get_current_buf()
   end
+  if lang == nil then
+    local ft = vim.bo[bufnr].filetype
+    lang = 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))
+    -- end
+  end
 
-  if parsers[bufnr] == nil then
-    lang = lang or a.nvim_buf_get_option(bufnr, 'filetype')
-    parsers[bufnr] = M._create_parser(bufnr, lang, opts)
-  elseif lang and parsers[bufnr]:lang() ~= lang then
-    -- Only try to create a new parser if lang is provided
-    -- and it doesn't match the stored parser
+  if parsers[bufnr] == nil or parsers[bufnr]:lang() ~= lang then
     parsers[bufnr] = M._create_parser(bufnr, lang, opts)
   end
 
@@ -123,7 +127,7 @@ function M.get_string_parser(str, lang, opts)
     str = { str, 'string' },
     lang = { lang, 'string' },
   })
-  language.require_language(lang)
+  language.add(lang)
 
   return LanguageTree.new(str, lang, opts)
 end

runtime/lua/vim/treesitter/health.lua

@@ -17,7 +17,7 @@ function M.check()
 
   for _, parser in pairs(parsers) do
     local parsername = vim.fn.fnamemodify(parser, ':t:r')
-    local is_loadable, ret = pcall(ts.language.require_language, parsername)
+    local is_loadable, ret = pcall(ts.language.add, parsername)
 
     if not is_loadable or not ret then
       health.report_error(

runtime/lua/vim/treesitter/language.lua

@@ -2,19 +2,66 @@ local a = vim.api
 
 local M = {}
 
+---@type table<string,string>
+local ft_to_lang = {}
+
+---@param filetype string
+---@return string|nil
+function M.get_lang(filetype)
+  return ft_to_lang[filetype]
+end
+
+---@deprecated
+function M.require_language(lang, path, silent, symbol_name)
+  return M.add(lang, {
+    silent = silent,
+    path = path,
+    symbol_name = symbol_name,
+  })
+end
+
+---@class treesitter.RequireLangOpts
+---@field path? string
+---@field silent? boolean
+---@field filetype? string|string[]
+---@field symbol_name? string
+
 --- Asserts that a parser for the language {lang} is installed.
 ---
 --- Parsers are searched in the `parser` runtime directory, or the provided {path}
 ---
 ---@param lang string Language the parser should parse (alphanumerical and `_` only)
----@param path (string|nil) Optional path the parser is located at
----@param silent (boolean|nil) Don't throw an error if language not found
----@param symbol_name (string|nil) Internal symbol name for the language to load
+---@param opts (table|nil) Options:
+---                        - filetype (string|string[]) Filetype(s) that lang can be parsed with.
+---                          Note this is not strictly the same as lang since a single lang can
+---                          parse multiple filetypes.
+---                          Defaults to lang.
+---                        - path (string|nil) Optional path the parser is located at
+---                        - symbol_name (string|nil) Internal symbol name for the language to load
+---                        - silent (boolean|nil) Don't throw an error if language not found
 ---@return boolean If the specified language is installed
-function M.require_language(lang, path, silent, symbol_name)
+function M.add(lang, opts)
+  ---@cast opts treesitter.RequireLangOpts
+  opts = opts or {}
+  local path = opts.path
+  local silent = opts.silent
+  local filetype = opts.filetype or lang
+  local symbol_name = opts.symbol_name
+
+  vim.validate({
+    lang = { lang, 'string' },
+    path = { path, 'string', true },
+    silent = { silent, 'boolean', true },
+    symbol_name = { symbol_name, 'string', true },
+    filetype = { filetype, { 'string', 'table' }, true },
+  })
+
+  M.register(lang, filetype or lang)
+
   if vim._ts_has_language(lang) then
     return true
   end
+
   if path == nil then
     if not (lang and lang:match('[%w_]+') == lang) then
       if silent then
@@ -35,9 +82,9 @@ function M.require_language(lang, path, silent, symbol_name)
   end
 
   if silent then
-    return pcall(function()
-      vim._ts_add_language(path, lang, symbol_name)
-    end)
+    if not pcall(vim._ts_add_language, path, lang, symbol_name) then
+      return false
+    end
   else
     vim._ts_add_language(path, lang, symbol_name)
   end
@@ -45,6 +92,27 @@ function M.require_language(lang, path, silent, symbol_name)
   return true
 end
 
+--- Register a lang to be used for a filetype (or list of filetypes).
+---@param lang string Language to register
+---@param filetype string|string[] Filetype(s) to associate with lang
+function M.register(lang, filetype)
+  vim.validate({
+    lang = { lang, 'string' },
+    filetype = { filetype, { 'string', 'table' } },
+  })
+
+  local filetypes ---@type string[]
+  if type(filetype) == 'string' then
+    filetypes = { filetype }
+  else
+    filetypes = filetype
+  end
+
+  for _, f in ipairs(filetypes) do
+    ft_to_lang[f] = lang
+  end
+end
+
 --- Inspects the provided language.
 ---
 --- Inspecting provides some useful information on the language like node names, ...
@@ -52,7 +120,7 @@ end
 ---@param lang string Language
 ---@return table
 function M.inspect_language(lang)
-  M.require_language(lang)
+  M.add(lang)
   return vim._ts_inspect_language(lang)
 end
 

runtime/lua/vim/treesitter/languagetree.lua

@@ -51,7 +51,7 @@ LanguageTree.__index = LanguageTree
 ---                                query per language.
 ---@return LanguageTree parser object
 function LanguageTree.new(source, lang, opts)
-  language.require_language(lang)
+  language.add(lang)
   ---@type LanguageTreeOpts
   opts = opts or {}
 
@@ -170,7 +170,7 @@ function LanguageTree:parse()
   local seen_langs = {} ---@type table<string,boolean>
 
   for lang, injection_ranges in pairs(injections_by_lang) do
-    local has_lang = language.require_language(lang, nil, true)
+    local has_lang = language.add(lang, { silent = true })
 
     -- Child language trees should just be ignored if not found, since
     -- they can depend on the text of a node. Intermediate strings

runtime/lua/vim/treesitter/query.lua

@@ -252,7 +252,7 @@ end)
 ---
 ---@return Query Parsed query
 function M.parse_query(lang, query)
-  language.require_language(lang)
+  language.add(lang)
   local cached = query_cache[lang][query]
   if cached then
     return cached