From 041d98fe8d892a81ed659c32be5360d4f80e7d18 Mon Sep 17 00:00:00 2001
From: Christian Clason <c.clason@uni-graz.at>
Date: Sat, 14 Sep 2024 13:27:44 +0200
Subject: feat(treesitter)!: add default fallback to `ft_to_lang` lookups

Problem: Language names are only registered for filetype<->language
lookups when parsers are actually loaded; this means users cannot rely
on `vim.treesitter.language.get_lang()` or `get_filetypes()` to return
the correct value when language and filetype coincide and always need to
add explicit fallbacks.

Solution: Always return the language name as valid filetype in
`get_filetypes()`, and default to the filetype in `get_lang()`. Document
this behavior.
---
 runtime/doc/news.txt       |  6 ++++++
 runtime/doc/treesitter.txt | 12 +++++++++---
 2 files changed, 15 insertions(+), 3 deletions(-)

(limited to 'runtime/doc')

diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 11e0129f52..77345e6b19 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -98,6 +98,12 @@ TREESITTER
   backwards compatibility, an option `all=false` (only return the last
   matching node) is provided that will be removed in a future release.
 
+• |vim.treesitter.language.get_filetypes()| always includes the {language}
+  argument in addition to explicitly registered filetypes.
+
+• |vim.treesitter.language.get_lang()| falls back to the {filetype} argument
+  if no languages are explicitly registered.
+
 TUI
 
 • TODO
diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt
index da2e8db8c9..e0f7536712 100644
--- a/runtime/doc/treesitter.txt
+++ b/runtime/doc/treesitter.txt
@@ -969,14 +969,15 @@ add({lang}, {opts})                            *vim.treesitter.language.add()*
     Parameters: ~
       • {lang}  (`string`) Name of the parser (alphanumerical and `_` only)
       • {opts}  (`table?`) Options:
-                • {filetype}? (`string|string[]`, default: {lang}) Default
-                  filetype the parser should be associated with.
                 • {path}? (`string`) Optional path the parser is located at
                 • {symbol_name}? (`string`) Internal symbol name for the
                   language to load
 
 get_filetypes({lang})                *vim.treesitter.language.get_filetypes()*
-    Get the filetypes associated with the parser named {lang}.
+    Returns the filetypes for which a parser named {lang} is used.
+
+    The list includes {lang} itself plus all filetypes registered via
+    |vim.treesitter.language.register()|.
 
     Parameters: ~
       • {lang}  (`string`) Name of parser
@@ -985,6 +986,11 @@ get_filetypes({lang})                *vim.treesitter.language.get_filetypes()*
         (`string[]`) filetypes
 
 get_lang({filetype})                      *vim.treesitter.language.get_lang()*
+    Returns the language name to be used when loading a parser for {filetype}.
+
+    If no language has been explicitly registered via
+    |vim.treesitter.language.register()|, default to {filetype}. For composite
+    filetypes like `html.glimmer`, only the main filetype is returned.
 
     Parameters: ~
       • {filetype}  (`string`)
-- 
cgit