lsp: add preview_location util function (#12368)

* add preview_location

* add doc stub

* doc style; return bufnr&winnr of preview

* doc: function may return nil

Co-authored-by: Hirokazu Hata <h.hata.ai.t@gmail.com>

* doc: fixup

Co-authored-by: Hirokazu Hata <h.hata.ai.t@gmail.com>

runtime/doc/lsp.txt

@@ -1053,6 +1053,9 @@ highlight_region({ft}, {start}, {finish})
 jump_to_location({location})                 *vim.lsp.util.jump_to_location()*
                 TODO: Documentation
 
+preview_location({location})                 *vim.lsp.util.preview_location()*
+                TODO: Documentation
+
 locations_to_items({locations})            *vim.lsp.util.locations_to_items()*
                 TODO: Documentation
 

runtime/lua/vim/lsp/util.lua

@@ -481,6 +481,28 @@ function M.jump_to_location(location)
   return true
 end
 
+--- Preview a location in a floating windows
+---
+--- behavior depends on type of location:
+---   - for Location, range is shown (e.g., function definition)
+---   - for LocationLink, targetRange is shown (e.g., body of function definition)
+---
+--@param location a single Location or LocationLink
+--@return bufnr,winnr buffer and window number of floating window or nil
+function M.preview_location(location)
+  -- location may be LocationLink or Location (more useful for the former)
+  local uri = location.targetUri or location.uri
+  if uri == nil then return end
+  local bufnr = vim.uri_to_bufnr(uri)
+  if not api.nvim_buf_is_loaded(bufnr) then
+    vim.fn.bufload(bufnr)
+  end
+  local range = location.targetRange or location.range
+  local contents = api.nvim_buf_get_lines(bufnr, range.start.line, range["end"].line+1, false)
+  local filetype = api.nvim_buf_get_option(bufnr, 'filetype')
+  return M.open_floating_preview(contents, filetype)
+end
+
 local function find_window_by_var(name, value)
   for _, win in ipairs(api.nvim_list_wins()) do
     if npcall(api.nvim_win_get_var, win, name) == value then