feat(lsp)!: rename vim.lsp.get_active_clients to get_clients (#24113)

8 files changed, 70 insertions, 62 deletions

diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt
index 6317789d22..81dd1e64bf 100644
--- a/runtime/doc/deprecated.txt
+++ b/runtime/doc/deprecated.txt
@@ -129,7 +129,7 @@ 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
+- *vim.lsp.buf_get_clients()*			Use |vim.lsp.get_clients()| with
 						{buffer=bufnr} instead.
 - *vim.lsp.buf.formatting()*			Use |vim.lsp.buf.format()| with
 						{async=true} instead.
@@ -139,7 +139,8 @@ LSP FUNCTIONS
 						or |vim.lsp.buf.format()| instead.
 - *vim.lsp.util.get_progress_messages()*	Use |vim.lsp.status()| or access
 						`progress` of |vim.lsp.client|
-- *vim.lsp.for_each_buffer_client()*		Use |vim.lsp.get_active_clients()|
+- *vim.lsp.get_active_clients()*		Use |vim.lsp.get_clients()|
+- *vim.lsp.for_each_buffer_client()*		Use |vim.lsp.get_clients()|
 
 TREESITTER FUNCTIONS
 - *vim.treesitter.language.require_language()*	Use |vim.treesitter.language.add()|
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 450690fe3b..ec0072e10e 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -38,7 +38,7 @@ Follow these steps to get LSP features:
     })
 <
 3. Check that the server attached to the buffer: >
-    :lua =vim.lsp.get_active_clients()
+    :lua =vim.lsp.get_clients()
 
 4. Configure keymaps and autocmds to use LSP features. See |lsp-config|.
 
@@ -105,7 +105,7 @@ calls behind capability checks:
 To learn what capabilities are available you can run the following command in
 a buffer with a started LSP client: >vim
 
-    :lua =vim.lsp.get_active_clients()[1].server_capabilities
+    :lua =vim.lsp.get_clients()[1].server_capabilities
 
 Full list of features provided by default can be found in |lsp-buf|.
 
@@ -114,7 +114,7 @@ FAQ                                                     *lsp-faq*
 
 - Q: How to force-reload LSP?
 - A: Stop all clients, then reload the buffer. >vim
-     :lua vim.lsp.stop_client(vim.lsp.get_active_clients())
+     :lua vim.lsp.stop_client(vim.lsp.get_clients())
      :edit
 
 - Q: Why isn't completion working?
@@ -690,7 +690,7 @@ buf_request_sync({bufnr}, {method}, {params}, {timeout_ms})
 
 client()                                                      *vim.lsp.client*
     LSP client object. You can get an active client object via
-    |vim.lsp.get_client_by_id()| or |vim.lsp.get_active_clients()|.
+    |vim.lsp.get_client_by_id()| or |vim.lsp.get_clients()|.
 
     • Methods:
       • request(method, params, [handler], bufnr) Sends a request to the
@@ -773,22 +773,6 @@ formatexpr({opts})                                      *vim.lsp.formatexpr()*
                 • timeout_ms (default 500ms). The timeout period for the
                   formatting request.
 
-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
-                  • method (string): Only return clients supporting the given
-                    method
-
-    Return: ~
-        lsp.Client []: List of |vim.lsp.client| objects
-
                                           *vim.lsp.get_buffers_by_client_id()*
 get_buffers_by_client_id({client_id})
     Returns list of buffers attached to client_id.
@@ -809,6 +793,22 @@ get_client_by_id({client_id})                     *vim.lsp.get_client_by_id()*
     Return: ~
         (nil|lsp.Client) client rpc object
 
+get_clients({filter})                                  *vim.lsp.get_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
+                  • method (string): Only return clients supporting the given
+                    method
+
+    Return: ~
+        lsp.Client []: List of |vim.lsp.client| objects
+
 get_log_path()                                        *vim.lsp.get_log_path()*
     Gets the path of the logfile used by the LSP client.
 
@@ -1040,7 +1040,7 @@ stop_client({client_id}, {force})                      *vim.lsp.stop_client()*
 
     You can also use the `stop()` function on a |vim.lsp.client| object. To stop all clients: >lua
 
-     vim.lsp.stop_client(vim.lsp.get_active_clients())
+     vim.lsp.stop_client(vim.lsp.get_clients())
 <
 
     By default asks the server to shutdown, unless stop was requested already
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 67726ebd9c..6294a8b505 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -204,7 +204,8 @@ release.
 
 • vim.lsp functions:
   - |vim.lsp.util.get_progress_messages()|	Use |vim.lsp.status()| instead.
-  - |vim.lsp.for_each_buffer_client()|	  	Use |vim.lsp.get_active_clients()| instead.
+  - |vim.lsp.get_active_clients()|	  	Use |vim.lsp.get_clients()| instead.
+  - |vim.lsp.for_each_buffer_client()|	  	Use |vim.lsp.get_clients()| instead.
 
 • `vim.loop` has been renamed to `vim.uv`.
 
diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua
index e9a1423d2d..97aab45f2c 100644
--- a/runtime/lua/vim/lsp.lua
+++ b/runtime/lua/vim/lsp.lua
@@ -612,7 +612,7 @@ do
   ---@private
   function changetracking.send_changes(bufnr, firstline, lastline, new_lastline)
     local groups = {} ---@type table<string,CTGroup>
-    for _, client in pairs(lsp.get_active_clients({ bufnr = bufnr })) do
+    for _, client in pairs(lsp.get_clients({ bufnr = bufnr })) do
       local group = get_group(client)
       groups[group_key(group)] = group
     end
@@ -734,7 +734,7 @@ end
 -- FIXME: DOC: Shouldn't need to use a dummy function
 --
 --- LSP client object. You can get an active client object via
---- |vim.lsp.get_client_by_id()| or |vim.lsp.get_active_clients()|.
+--- |vim.lsp.get_client_by_id()| or |vim.lsp.get_clients()|.
 ---
 --- - Methods:
 ---
@@ -880,7 +880,7 @@ function lsp.start(config, opts)
   if bufnr == nil or bufnr == 0 then
     bufnr = api.nvim_get_current_buf()
   end
-  for _, clients in ipairs({ uninitialized_clients, lsp.get_active_clients() }) do
+  for _, clients in ipairs({ uninitialized_clients, lsp.get_clients() }) do
     for _, client in pairs(clients) do
       if reuse_client(client, config) then
         lsp.buf_attach_client(bufnr, client.id)
@@ -903,7 +903,7 @@ end
 function lsp.status()
   local percentage = nil
   local messages = {}
-  for _, client in ipairs(vim.lsp.get_active_clients()) do
+  for _, client in ipairs(vim.lsp.get_clients()) do
     for progress in client.progress do
       local value = progress.value
       if type(value) == 'table' and value.kind then
@@ -1755,7 +1755,7 @@ local function text_document_did_save_handler(bufnr)
   bufnr = resolve_bufnr(bufnr)
   local uri = vim.uri_from_bufnr(bufnr)
   local text = once(buf_get_full_text)
-  for _, client in ipairs(lsp.get_active_clients({ bufnr = bufnr })) do
+  for _, client in ipairs(lsp.get_clients({ bufnr = bufnr })) do
     local name = api.nvim_buf_get_name(bufnr)
     local old_name = changetracking._get_and_set_name(client, bufnr, name)
     if old_name and name ~= old_name then
@@ -1823,7 +1823,7 @@ function lsp.buf_attach_client(bufnr, client_id)
       buffer = bufnr,
       desc = 'vim.lsp: textDocument/willSave',
       callback = function(ctx)
-        for _, client in ipairs(lsp.get_active_clients({ bufnr = ctx.buf })) do
+        for _, client in ipairs(lsp.get_clients({ bufnr = ctx.buf })) do
           local params = {
             textDocument = {
               uri = uri,
@@ -1858,7 +1858,7 @@ function lsp.buf_attach_client(bufnr, client_id)
       on_lines = text_document_did_change_handler,
       on_reload = function()
         local params = { textDocument = { uri = uri } }
-        for _, client in ipairs(lsp.get_active_clients({ bufnr = bufnr })) do
+        for _, client in ipairs(lsp.get_clients({ bufnr = bufnr })) do
           changetracking.reset_buf(client, bufnr)
           if vim.tbl_get(client.server_capabilities, 'textDocumentSync', 'openClose') then
             client.notify('textDocument/didClose', params)
@@ -1868,7 +1868,7 @@ function lsp.buf_attach_client(bufnr, client_id)
       end,
       on_detach = function()
         local params = { textDocument = { uri = uri } }
-        for _, client in ipairs(lsp.get_active_clients({ bufnr = bufnr })) do
+        for _, client in ipairs(lsp.get_clients({ bufnr = bufnr })) do
           changetracking.reset_buf(client, bufnr)
           if vim.tbl_get(client.server_capabilities, 'textDocumentSync', 'openClose') then
             client.notify('textDocument/didClose', params)
@@ -1985,7 +1985,7 @@ end
 --- You can also use the `stop()` function on a |vim.lsp.client| object.
 --- To stop all clients:
 --- <pre>lua
---- vim.lsp.stop_client(vim.lsp.get_active_clients())
+--- vim.lsp.stop_client(vim.lsp.get_clients())
 --- </pre>
 ---
 --- By default asks the server to shutdown, unless stop was requested
@@ -2006,7 +2006,7 @@ function lsp.stop_client(client_id, force)
   end
 end
 
----@class vim.lsp.get_active_clients.filter
+---@class vim.lsp.get_clients.filter
 ---@field id integer|nil Match clients by id
 ---@field bufnr integer|nil match clients attached to the given buffer
 ---@field name string|nil match clients by name
@@ -2014,7 +2014,7 @@ end
 
 --- Get active clients.
 ---
----@param filter vim.lsp.get_active_clients.filter|nil (table|nil) A table with
+---@param filter vim.lsp.get_clients.filter|nil (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
@@ -2022,7 +2022,7 @@ end
 ---               - name (string): Only return clients with the given name
 ---               - method (string): Only return clients supporting the given method
 ---@return lsp.Client[]: List of |vim.lsp.client| objects
-function lsp.get_active_clients(filter)
+function lsp.get_clients(filter)
   validate({ filter = { filter, 't', true } })
 
   filter = filter or {}
@@ -2045,6 +2045,13 @@ function lsp.get_active_clients(filter)
   return clients
 end
 
+---@private
+---@deprecated
+function lsp.get_active_clients(filter)
+  -- TODO: add vim.deprecate call after 0.10 is out for removal in 0.12
+  return lsp.get_clients(filter)
+end
+
 api.nvim_create_autocmd('VimLeavePre', {
   desc = 'vim.lsp: exit handler',
   callback = function()
@@ -2125,7 +2132,7 @@ function lsp.buf_request(bufnr, method, params, handler)
 
   bufnr = resolve_bufnr(bufnr)
   local method_supported = false
-  local clients = lsp.get_active_clients({ bufnr = bufnr })
+  local clients = lsp.get_clients({ bufnr = bufnr })
   local client_request_ids = {}
   for _, client in ipairs(clients) do
     if client.supports_method(method, { bufnr = bufnr }) then
@@ -2173,7 +2180,7 @@ function lsp.buf_request_all(bufnr, method, params, handler)
   local expected_result_count = 0
 
   local set_expected_result_count = once(function()
-    for _, client in ipairs(lsp.get_active_clients({ bufnr = bufnr })) do
+    for _, client in ipairs(lsp.get_clients({ bufnr = bufnr })) do
       if client.supports_method(method, { bufnr = bufnr }) then
         expected_result_count = expected_result_count + 1
       end
@@ -2240,7 +2247,7 @@ function lsp.buf_notify(bufnr, method, params)
     method = { method, 's' },
   })
   local resp = false
-  for _, client in ipairs(lsp.get_active_clients({ bufnr = bufnr })) do
+  for _, client in ipairs(lsp.get_clients({ bufnr = bufnr })) do
     if client.rpc.notify(method, params) then
       resp = true
     end
@@ -2367,7 +2374,7 @@ function lsp.formatexpr(opts)
     return 0
   end
   local bufnr = api.nvim_get_current_buf()
-  for _, client in pairs(lsp.get_active_clients({ bufnr = bufnr })) do
+  for _, client in pairs(lsp.get_clients({ bufnr = bufnr })) do
     if client.supports_method('textDocument/rangeFormatting') then
       local params = util.make_formatting_params()
       local end_line = vim.fn.getline(end_lnum) --[[@as string]]
@@ -2424,10 +2431,10 @@ end
 ---
 ---@param bufnr (integer|nil): Buffer handle, or 0 for current
 ---@return table result is table of (client_id, client) pairs
----@deprecated Use |vim.lsp.get_active_clients()| instead.
+---@deprecated Use |vim.lsp.get_clients()| instead.
 function lsp.buf_get_clients(bufnr)
   local result = {}
-  for _, client in ipairs(lsp.get_active_clients({ bufnr = resolve_bufnr(bufnr) })) do
+  for _, client in ipairs(lsp.get_clients({ bufnr = resolve_bufnr(bufnr) })) do
     result[client.id] = client
   end
   return result
@@ -2478,7 +2485,7 @@ end
 ---                 vim.print(client)
 ---               end)
 ---             </pre>
----@deprecated use lsp.get_active_clients({ bufnr = bufnr }) with regular loop
+---@deprecated use lsp.get_clients({ bufnr = bufnr }) with regular loop
 function lsp.for_each_buffer_client(bufnr, fn)
   return for_each_buffer_client(bufnr, fn)
 end
diff --git a/runtime/lua/vim/lsp/buf.lua b/runtime/lua/vim/lsp/buf.lua
index b238b5c221..2140d3ae37 100644
--- a/runtime/lua/vim/lsp/buf.lua
+++ b/runtime/lua/vim/lsp/buf.lua
@@ -197,7 +197,6 @@ end
 function M.format(options)
   options = options or {}
   local bufnr = options.bufnr or api.nvim_get_current_buf()
-
   local mode = api.nvim_get_mode().mode
   local range = options.range
   if not range and mode == 'v' or mode == 'V' then
@@ -205,7 +204,7 @@ function M.format(options)
   end
   local method = range and 'textDocument/rangeFormatting' or 'textDocument/formatting'
 
-  local clients = vim.lsp.get_active_clients({
+  local clients = vim.lsp.get_clients({
     id = options.id,
     bufnr = bufnr,
     name = options.name,
@@ -271,7 +270,7 @@ end
 function M.rename(new_name, options)
   options = options or {}
   local bufnr = options.bufnr or api.nvim_get_current_buf()
-  local clients = vim.lsp.get_active_clients({
+  local clients = vim.lsp.get_clients({
     bufnr = bufnr,
     name = options.name,
     -- Clients must at least support rename, prepareRename is optional
@@ -468,7 +467,7 @@ end
 ---
 function M.list_workspace_folders()
   local workspace_folders = {}
-  for _, client in pairs(vim.lsp.get_active_clients({ bufnr = 0 })) do
+  for _, client in pairs(vim.lsp.get_clients({ bufnr = 0 })) do
     for _, folder in pairs(client.workspace_folders or {}) do
       table.insert(workspace_folders, folder.name)
     end
@@ -493,7 +492,7 @@ function M.add_workspace_folder(workspace_folder)
     { { uri = vim.uri_from_fname(workspace_folder), name = workspace_folder } },
     {}
   )
-  for _, client in pairs(vim.lsp.get_active_clients({ bufnr = 0 })) do
+  for _, client in pairs(vim.lsp.get_clients({ bufnr = 0 })) do
     local found = false
     for _, folder in pairs(client.workspace_folders or {}) do
       if folder.name == workspace_folder then
@@ -526,7 +525,7 @@ function M.remove_workspace_folder(workspace_folder)
     { {} },
     { { uri = vim.uri_from_fname(workspace_folder), name = workspace_folder } }
   )
-  for _, client in pairs(vim.lsp.get_active_clients({ bufnr = 0 })) do
+  for _, client in pairs(vim.lsp.get_clients({ bufnr = 0 })) do
     for idx, folder in pairs(client.workspace_folders or {}) do
       if folder.name == workspace_folder then
         vim.lsp.buf_notify(0, 'workspace/didChangeWorkspaceFolders', params)
diff --git a/runtime/lua/vim/lsp/health.lua b/runtime/lua/vim/lsp/health.lua
index 8817bb71de..023b1c26be 100644
--- a/runtime/lua/vim/lsp/health.lua
+++ b/runtime/lua/vim/lsp/health.lua
@@ -28,7 +28,7 @@ function M.check()
   local report_fn = (log_size / 1000000 > 100 and report_warn or report_info)
   report_fn(string.format('Log size: %d KB', log_size / 1000))
 
-  local clients = vim.lsp.get_active_clients()
+  local clients = vim.lsp.get_clients()
   vim.health.start('vim.lsp: Active Clients')
   if next(clients) then
     for _, client in pairs(clients) do
diff --git a/runtime/lua/vim/lsp/util.lua b/runtime/lua/vim/lsp/util.lua
index 0da88f800e..59b9916f64 100644
--- a/runtime/lua/vim/lsp/util.lua
+++ b/runtime/lua/vim/lsp/util.lua
@@ -360,7 +360,7 @@ function M.get_progress_messages()
   local new_messages = {}
   local progress_remove = {}
 
-  for _, client in ipairs(vim.lsp.get_active_clients()) do
+  for _, client in ipairs(vim.lsp.get_clients()) do
     local groups = {}
     for progress in client.progress do
       local value = progress.value
@@ -1841,7 +1841,7 @@ function M.locations_to_items(locations, offset_encoding)
       'locations_to_items must be called with valid offset encoding',
       vim.log.levels.WARN
     )
-    offset_encoding = vim.lsp.get_active_clients({ bufnr = 0 })[1].offset_encoding
+    offset_encoding = vim.lsp.get_clients({ bufnr = 0 })[1].offset_encoding
   end
 
   local items = {}
@@ -2036,7 +2036,7 @@ function M._get_offset_encoding(bufnr)
 
   local offset_encoding
 
-  for _, client in pairs(vim.lsp.get_active_clients({ bufnr = bufnr })) do
+  for _, client in pairs(vim.lsp.get_clients({ bufnr = bufnr })) do
     if client.offset_encoding == nil then
       vim.notify_once(
         string.format(
@@ -2183,7 +2183,7 @@ function M.character_offset(buf, row, col, offset_encoding)
       'character_offset must be called with valid offset encoding',
       vim.log.levels.WARN
     )
-    offset_encoding = vim.lsp.get_active_clients({ bufnr = buf })[1].offset_encoding
+    offset_encoding = vim.lsp.get_clients({ bufnr = buf })[1].offset_encoding
   end
   -- If the col is past the EOL, use the line length.
   if col > #line then
diff --git a/test/functional/plugin/lsp_spec.lua b/test/functional/plugin/lsp_spec.lua
index 38176c8749..9a777e2742 100644
--- a/test/functional/plugin/lsp_spec.lua
+++ b/test/functional/plugin/lsp_spec.lua
@@ -82,7 +82,7 @@ describe('LSP', function()
   describe('server_name specified', function()
     it('start_client(), stop_client()', function()
       retry(nil, 4000, function()
-        eq(1, exec_lua('return #lsp.get_active_clients()'))
+        eq(1, exec_lua('return #lsp.get_clients()'))
       end)
       eq(2, exec_lua([[
         TEST_CLIENT2 = test__start_client()
@@ -93,20 +93,20 @@ describe('LSP', function()
         return TEST_CLIENT3
       ]]))
       retry(nil, 4000, function()
-        eq(3, exec_lua('return #lsp.get_active_clients()'))
+        eq(3, exec_lua('return #lsp.get_clients()'))
       end)
 
       eq(false, exec_lua('return lsp.get_client_by_id(TEST_CLIENT1) == nil'))
       eq(false, exec_lua('return lsp.get_client_by_id(TEST_CLIENT1).is_stopped()'))
       exec_lua('return lsp.get_client_by_id(TEST_CLIENT1).stop()')
       retry(nil, 4000, function()
-        eq(2, exec_lua('return #lsp.get_active_clients()'))
+        eq(2, exec_lua('return #lsp.get_clients()'))
       end)
       eq(true, exec_lua('return lsp.get_client_by_id(TEST_CLIENT1) == nil'))
 
       exec_lua('lsp.stop_client({TEST_CLIENT2, TEST_CLIENT3})')
       retry(nil, 4000, function()
-        eq(0, exec_lua('return #lsp.get_active_clients()'))
+        eq(0, exec_lua('return #lsp.get_clients()'))
       end)
     end)
 
@@ -116,12 +116,12 @@ describe('LSP', function()
         TEST_CLIENT3 = test__start_client()
       ]])
       retry(nil, 4000, function()
-        eq(3, exec_lua('return #lsp.get_active_clients()'))
+        eq(3, exec_lua('return #lsp.get_clients()'))
       end)
       -- Stop all clients.
-      exec_lua('lsp.stop_client(lsp.get_active_clients())')
+      exec_lua('lsp.stop_client(lsp.get_clients())')
       retry(nil, 4000, function()
-        eq(0, exec_lua('return #lsp.get_active_clients()'))
+        eq(0, exec_lua('return #lsp.get_clients()'))
       end)
     end)
   end)
@@ -151,7 +151,7 @@ describe('LSP', function()
   describe('basic_init test', function()
     after_each(function()
       stop()
-      exec_lua("lsp.stop_client(lsp.get_active_clients(), true)")
+      exec_lua("lsp.stop_client(lsp.get_clients(), true)")
       exec_lua("vim.api.nvim_exec_autocmds('VimLeavePre', { modeline = false })")
     end)