feat(lsp): add filter to vim.lsp.get_active_clients()

Allow get_active_clients() to filter on client name, id, or buffer. This
(soft) deprecates lsp.buf_get_clients().

runtime/doc/deprecated.txt

@@ -106,11 +106,13 @@ internally and are no longer exposed as part of the API. Instead, use
 *vim.lsp.diagnostic.set_underline()*
 *vim.lsp.diagnostic.set_virtual_text()*
 
-LSP Utility Functions ~
+LSP Functions ~
 
 *vim.lsp.util.diagnostics_to_items()*	Use |vim.diagnostic.toqflist()| instead.
 *vim.lsp.util.set_qflist()*		Use |setqflist()| instead.
 *vim.lsp.util.set_loclist()*		Use |setloclist()| instead.
+*vim.lsp.buf_get_clients()*		Use |vim.lsp.get_active_clients()| with
+                                        {buffer = bufnr} instead.
 
 Lua ~
 *vim.register_keystroke_callback()* Use |vim.on_key()| instead.

runtime/doc/lsp.txt

@@ -531,14 +531,6 @@ buf_detach_client({bufnr}, {client_id})          *vim.lsp.buf_detach_client()*
                     {bufnr}      (number) Buffer handle, or 0 for current
                     {client_id}  (number) Client id
 
-buf_get_clients({bufnr})                           *vim.lsp.buf_get_clients()*
-                Gets a map of client_id:client pairs for the given buffer,
-                where each value is a |vim.lsp.client| object.
-
-                Parameters: ~
-                    {bufnr}  (optional, number): Buffer handle, or 0 for
-                             current
-
 buf_is_attached({bufnr}, {client_id})              *vim.lsp.buf_is_attached()*
                 Checks if a buffer is attached for a particular client.
 
@@ -729,11 +721,22 @@ formatexpr({opts})                                      *vim.lsp.formatexpr()*
                             • timeout_ms (default 500ms). The timeout period
                               for the formatting request.
 
-get_active_clients()                            *vim.lsp.get_active_clients()*
-                Gets all active clients.
+get_active_clients({filter})                    *vim.lsp.get_active_clients()*
+                Get active clients.
+
+                Parameters: ~
+                    {filter}  (table|nil) A table with key-value pairs used to
+                              filter the returned clients. The available keys
+                              are:
+                              • id (number): Only return clients with the
+                                given id
+                              • bufnr (number): Only return clients attached
+                                to this buffer
+                              • name (string): Only return clients with the
+                                given name
 
                 Return: ~
-                    Table of |vim.lsp.client| objects
+                    (table) List of |vim.lsp.client| objects
 
                                           *vim.lsp.get_buffers_by_client_id()*
 get_buffers_by_client_id({client_id})

runtime/lua/vim/lsp.lua

@@ -1463,11 +1463,29 @@ function lsp.stop_client(client_id, force)
   end
 end
 
---- Gets all active clients.
+--- Get active clients.
 ---
----@returns Table of |vim.lsp.client| objects
-function lsp.get_active_clients()
-  return vim.tbl_values(active_clients)
+---@param filter (table|nil) A table with key-value pairs used to filter the
+---              returned clients. The available keys are:
+---               - id (number): Only return clients with the given id
+---               - bufnr (number): Only return clients attached to this buffer
+---               - name (string): Only return clients with the given name
+---@returns (table) List of |vim.lsp.client| objects
+function lsp.get_active_clients(filter)
+  validate({ filter = { filter, 't', true } })
+
+  filter = filter or {}
+
+  local clients = {}
+
+  local t = filter.bufnr and (all_buffer_active_clients[resolve_bufnr(filter.bufnr)] or {}) or active_clients
+  for client_id in pairs(t) do
+    local client = active_clients[client_id]
+    if (filter.id == nil or client.id == filter.id) and (filter.name == nil or client.name == filter.name) then
+      clients[#clients + 1] = client
+    end
+  end
+  return clients
 end
 
 function lsp._vim_exit_handler()
@@ -1842,12 +1860,13 @@ end
 --- is a |vim.lsp.client| object.
 ---
 ---@param bufnr (optional, number): Buffer handle, or 0 for current
+---@returns (table) Table of (client_id, client) pairs
+---@deprecated Use |vim.lsp.get_active_clients()| instead.
 function lsp.buf_get_clients(bufnr)
-  bufnr = resolve_bufnr(bufnr)
   local result = {}
-  for_each_buffer_client(bufnr, function(client, client_id)
-    result[client_id] = client
-  end)
+  for _, client in ipairs(lsp.get_active_clients({ bufnr = resolve_bufnr(bufnr) })) do
+    result[client.id] = client
+  end
   return result
 end