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, 52 insertions, 5 deletions

diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 78100d5277..5632a1ad78 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -412,6 +412,31 @@ For the format of the response message, see:
 For the format of the notification message, see:
     https://microsoft.github.io/language-server-protocol/specifications/specification-current/#notificationMessage
 
+                                                                *on-list-handler*
+
+`on_list` receives a table with:
+
+ - `items` table[], structured like |setqflist-what|
+ - `title` string, title for the list.
+ - `context` table|nil. `ctx` from |lsp-handler|
+
+This table can be used with vim.fn.setqflist or vim.fn.setloclist. E.g.:
+
+  local function on_list(options)
+    vim.fn.setqflist({}, ' ', options)
+    vim.api.nvim_command('cfirst')
+  end
+
+  vim.lsp.buf.definition{on_list=on_list}
+  vim.lsp.buf.references(nil, {on_list=on_list})
+
+If you prefer loclist do something like this:
+
+  local function on_list(options)
+    vim.fn.setloclist(0, {}, ' ', options)
+    vim.api.nvim_command('lopen')
+  end
+
 ================================================================================
 LSP HIGHLIGHT                                                    *lsp-highlight*
 
@@ -1114,6 +1139,8 @@ declaration({options})                             *vim.lsp.buf.declaration()*
                     {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|
 
 definition({options})                               *vim.lsp.buf.definition()*
                 Jumps to the definition of the symbol under the cursor.
@@ -1122,6 +1149,8 @@ definition({options})                               *vim.lsp.buf.definition()*
                     {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|
 
 document_highlight()                        *vim.lsp.buf.document_highlight()*
                 Send request to the server to resolve document highlights for
@@ -1139,10 +1168,15 @@ document_highlight()                        *vim.lsp.buf.document_highlight()*
                 to see the actual highlights. |LspReferenceText|
                 |LspReferenceRead| |LspReferenceWrite|
 
-document_symbol()                              *vim.lsp.buf.document_symbol()*
+document_symbol({options})                     *vim.lsp.buf.document_symbol()*
                 Lists all symbols in the current buffer in the quickfix
                 window.
 
+                Parameters: ~
+                    {options}  (table|nil) additional options
+                               • on_list: (function) handler for list results.
+                                 See |on-list-handler|
+
 execute_command({command_params})              *vim.lsp.buf.execute_command()*
                 Executes an LSP server command.
 
@@ -1251,10 +1285,15 @@ hover()                                                  *vim.lsp.buf.hover()*
                 in a floating window. Calling the function twice will jump
                 into the floating window.
 
-implementation()                                *vim.lsp.buf.implementation()*
+implementation({options})                       *vim.lsp.buf.implementation()*
                 Lists all the implementations for the symbol under the cursor
                 in the quickfix window.
 
+                Parameters: ~
+                    {options}  (table|nil) additional options
+                               • on_list: (function) handler for list results.
+                                 See |on-list-handler|
+
 incoming_calls()                                *vim.lsp.buf.incoming_calls()*
                 Lists all the call sites of the symbol under the cursor in the
                 |quickfix| window. If the symbol can resolve to multiple
@@ -1300,12 +1339,15 @@ range_formatting({options}, {start_pos}, {end_pos})
                                  position. Defaults to the end of the last
                                  visual selection.
 
-references({context})                               *vim.lsp.buf.references()*
+references({context}, {options})                    *vim.lsp.buf.references()*
                 Lists all the references to the symbol under the cursor in the
                 quickfix window.
 
                 Parameters: ~
                     {context}  (table) Context for the request
+                    {options}  (table|nil) additional options
+                               • on_list: (function) handler for list results.
+                                 See |on-list-handler|
 
                 See also: ~
                     https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_references
@@ -1351,8 +1393,10 @@ type_definition({options})                     *vim.lsp.buf.type_definition()*
                     {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|
 
-workspace_symbol({query})                     *vim.lsp.buf.workspace_symbol()*
+workspace_symbol({query}, {options})          *vim.lsp.buf.workspace_symbol()*
                 Lists all symbols in the current workspace in the quickfix
                 window.
 
@@ -1362,7 +1406,10 @@ workspace_symbol({query})                     *vim.lsp.buf.workspace_symbol()*
                 done.
 
                 Parameters: ~
-                    {query}  (string, optional)
+                    {query}    (string, optional)
+                    {options}  (table|nil) additional options
+                               • on_list: (function) handler for list results.
+                                 See |on-list-handler|
 
 
 ==============================================================================