refactor(filetype): allow vim.filetype.match to accept buf and filename (#19114)

This is necessary in cases where filetype detection acts recursively.
For example, when matching files that end with .bak, the "root" of
the filename is matched again against the same buffer (e.g. a buffer
named "foo.c.bak" will be matched again with the filename "foo.c", using
the same underlying buffer).

1 files changed, 19 insertions, 9 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index f40b32c469..b79699c89b 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -2086,23 +2086,33 @@ match({arg})                                            *vim.filetype.match()*
     -- Using a buffer number
     vim.filetype.match({ buf = 42 })
 
-    -- Using a filename
-    vim.filetype.match({ filename = "main.lua" })
+    -- Override the filename of the given buffer
+    vim.filetype.match({ buf = 42, filename = 'foo.c' })
+
+    -- Using a filename without a buffer
+    vim.filetype.match({ filename = 'main.lua' })
 
     -- Using file contents
-    vim.filetype.match({ contents = {"#!/usr/bin/env bash"} })
+    vim.filetype.match({ contents = {'#!/usr/bin/env bash'} })
 <
 
                 Parameters: ~
                     {arg}  (table) Table specifying which matching strategy to
-                           use. It is an error to provide more than one
-                           strategy. Accepted keys are:
-                           • buf (number): Buffer number to use for matching
+                           use. Accepted keys are:
+                           • buf (number): Buffer number to use for matching.
+                             Mutually exclusive with {contents}
                            • filename (string): Filename to use for matching.
-                             Note that the file need not actually exist in the
-                             filesystem, only the name itself is used.
+                             When {buf} is given, defaults to the filename of
+                             the given buffer number. The file need not
+                             actually exist in the filesystem. When used
+                             without {buf} only the name of the file is used
+                             for filetype matching. This may result in failure
+                             to detect the filetype in cases where the
+                             filename alone is not enough to disambiguate the
+                             filetype.
                            • contents (table): An array of lines representing
-                             file contents to use for matching.
+                             file contents to use for matching. Can be used
+                             with {filename}. Mutually exclusive with {buf}.
 
                 Return: ~
                     (string|nil) If a match was found, the matched filetype.