feat(lsp): allow passing custom list handler to LSP functions that return lists (#19213)

Currently LSP allows only using loclist or quickfix list window. I
normally prefer to review all quickfix items without opening quickfix
window. This fix allows passing `on_list` option which allows full
control what to do with list.

Here is example how to use it with quick fix list:

```lua
local function on_list(options)
  vim.fn.setqflist({}, ' ', options)
  vim.api.nvim_command('cfirst')
end

local bufopts = { noremap=true, silent=true, buffer=bufnr }
vim.keymap.set('n', '<leader>ad', function() vim.lsp.buf.declaration{on_list=on_list} end, bufopts)
vim.keymap.set('n', '<leader>d', function() vim.lsp.buf.definition{on_list=on_list} end, bufopts)
vim.keymap.set('n', '<leader>ai', function() vim.lsp.buf.implementation{on_list=on_list} end, bufopts)
vim.keymap.set('n', '<leader>at', function() vim.lsp.buf.type_definition{on_list=on_list} end, bufopts)
vim.keymap.set('n', '<leader>af', function() vim.lsp.buf.references(nil, {on_list=on_list}) end, bufopts)
```

If you prefer loclist do something like this:

```lua
local function on_list(options)
  vim.fn.setloclist(0, {}, ' ', options)
  vim.api.nvim_command('lopen')
end
```

close #19182

Co-authored-by: Mathias Fußenegger <mfussenegger@users.noreply.github.com>

1 files changed, 20 insertions, 8 deletions

diff --git a/runtime/lua/vim/lsp/buf.lua b/runtime/lua/vim/lsp/buf.lua
index 50a51e897c..34ca96d1ff 100644
--- a/runtime/lua/vim/lsp/buf.lua
+++ b/runtime/lua/vim/lsp/buf.lua
@@ -61,6 +61,7 @@ end
 ---
 ---@param options table|nil additional options
 ---     - reuse_win: (boolean) Jump to existing window if buffer is already open.
+---     - on_list: (function) handler for list results. See |on-list-handler|
 function M.declaration(options)
   local params = util.make_position_params()
   request_with_options('textDocument/declaration', params, options)
@@ -70,6 +71,7 @@ end
 ---
 ---@param options table|nil additional options
 ---     - reuse_win: (boolean) Jump to existing window if buffer is already open.
+---     - on_list: (function) handler for list results. See |on-list-handler|
 function M.definition(options)
   local params = util.make_position_params()
   request_with_options('textDocument/definition', params, options)
@@ -79,6 +81,7 @@ end
 ---
 ---@param options table|nil additional options
 ---     - reuse_win: (boolean) Jump to existing window if buffer is already open.
+---     - on_list: (function) handler for list results. See |on-list-handler|
 function M.type_definition(options)
   local params = util.make_position_params()
   request_with_options('textDocument/typeDefinition', params, options)
@@ -86,9 +89,12 @@ end
 
 --- Lists all the implementations for the symbol under the cursor in the
 --- quickfix window.
-function M.implementation()
+---
+---@param options table|nil additional options
+---     - on_list: (function) handler for list results. See |on-list-handler|
+function M.implementation(options)
   local params = util.make_position_params()
-  request('textDocument/implementation', params)
+  request_with_options('textDocument/implementation', params, options)
 end
 
 --- Displays signature information about the symbol under the cursor in a
@@ -496,20 +502,24 @@ end
 ---
 ---@param context (table) Context for the request
 ---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_references
-function M.references(context)
+---@param options table|nil additional options
+---     - on_list: (function) handler for list results. See |on-list-handler|
+function M.references(context, options)
   validate({ context = { context, 't', true } })
   local params = util.make_position_params()
   params.context = context or {
     includeDeclaration = true,
   }
-  request('textDocument/references', params)
+  request_with_options('textDocument/references', params, options)
 end
 
 --- Lists all symbols in the current buffer in the quickfix window.
 ---
-function M.document_symbol()
+---@param options table|nil additional options
+---     - on_list: (function) handler for list results. See |on-list-handler|
+function M.document_symbol(options)
   local params = { textDocument = util.make_text_document_params() }
-  request('textDocument/documentSymbol', params)
+  request_with_options('textDocument/documentSymbol', params, options)
 end
 
 ---@private
@@ -648,13 +658,15 @@ end
 --- string means no filtering is done.
 ---
 ---@param query (string, optional)
-function M.workspace_symbol(query)
+---@param options table|nil additional options
+---     - on_list: (function) handler for list results. See |on-list-handler|
+function M.workspace_symbol(query, options)
   query = query or npcall(vim.fn.input, 'Query: ')
   if query == nil then
     return
   end
   local params = { query = query }
-  request('workspace/symbol', params)
+  request_with_options('workspace/symbol', params, options)
 end
 
 --- Send request to the server to resolve document highlights for the current