feat(pos): create a cursor position by using the current of a window

Problem:
`vim.pos.cursor(vim.api.nvim_get_current_buf(win), vim.api.nvim_win_get_cursor(win))`
is too verbose to create a cursor position of a window,
but it is a common use case.

Solution:
Overload `vim.pos.cursor()`, so that it accepts `win` as an argument when `pos` is omitted.

runtime/doc/lua.txt

@@ -4503,15 +4503,24 @@ by |vim.Pos| objects.
 cursor({buf}, {pos})                                        *vim.pos.cursor()*
     Creates a new |vim.Pos| from cursor position (see |api-indexing|).
 
+    If {pos} is omitted, the first argument is treated as {win} instead of
+    {buf}, and the current cursor position of {win} is used.
+
     Example: >lua
+        local buf = vim.api.nvim_win_get_buf(0)
         local cursor_pos = vim.api.nvim_win_get_cursor(0)
-        local pos = vim.pos.cursor(0, cursor_pos)
+        local pos = vim.pos.cursor(buf, cursor_pos)
+        -- This is equivalent:
+        local pos = vim.pos.cursor(0)
 <
 
     Parameters: ~
       • {buf}  (`integer`)
       • {pos}  (`[integer, integer]`) (lnum, col) tuple
 
+    Overloads: ~
+      • `fun(win: integer): vim.Pos`
+
     Return: ~
         (`vim.Pos`) See |vim.Pos|.
 

runtime/lua/vim/lsp/buf.lua

@@ -51,7 +51,7 @@ local function ctx_is_valid(ctx)
     return false
   end
 
-  local cur_pos = vim.pos.cursor(bufnr, api.nvim_win_get_cursor(0))
+  local cur_pos = vim.pos.cursor(0)
   local pos = vim.pos.lsp(bufnr, p, enc)
   return cur_pos == pos
 end
@@ -222,7 +222,7 @@ local function get_locations(method, context, opts)
     )
   end
 
-  local pos = opts.pos or vim.pos.cursor(0, api.nvim_win_get_cursor(0))
+  local pos = opts.pos or vim.pos.cursor(0)
   local buf = pos.buf
 
   local clients = lsp.get_clients({ method = method, bufnr = buf })

runtime/lua/vim/lsp/codelens.lua

@@ -490,7 +490,7 @@ function M.run(opts)
 
   local winid = api.nvim_get_current_win()
   local bufnr = api.nvim_win_get_buf(winid)
-  local pos = vim.pos.cursor(bufnr, api.nvim_win_get_cursor(winid))
+  local pos = vim.pos.cursor(winid)
   local params = {
     textDocument = vim.lsp.util.make_text_document_params(bufnr),
   }

runtime/lua/vim/lsp/util.lua

@@ -1810,10 +1810,9 @@ end
 ---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentPositionParams
 function M.make_position_params(win, position_encoding)
   win = win or 0
-  local buf = api.nvim_win_get_buf(win)
   return {
-    textDocument = M.make_text_document_params(buf),
-    position = vim.pos.cursor(buf, api.nvim_win_get_cursor(win)):to_lsp(position_encoding),
+    textDocument = M.make_text_document_params(api.nvim_win_get_buf(win)),
+    position = vim.pos.cursor(win):to_lsp(position_encoding),
   }
 end
 

runtime/lua/vim/pos.lua

@@ -165,20 +165,38 @@ end
 
 --- Creates a new |vim.Pos| from cursor position (see |api-indexing|).
 ---
+--- If {pos} is omitted, the first argument is treated as {win} instead of {buf},
+--- and the current cursor position of {win} is used.
+---
 --- Example:
 --- ```lua
+--- local buf = vim.api.nvim_win_get_buf(0)
 --- local cursor_pos = vim.api.nvim_win_get_cursor(0)
---- local pos = vim.pos.cursor(0, cursor_pos)
+--- local pos = vim.pos.cursor(buf, cursor_pos)
+--- -- This is equivalent:
+--- local pos = vim.pos.cursor(0)
 --- ```
 ---@param buf integer
 ---@param pos [integer, integer] (lnum, col) tuple
 ---@return vim.Pos
+---@overload fun(win: integer): vim.Pos
 function M.cursor(buf, pos)
-  validate('buf', buf, 'number')
-  validate('pos', pos, 'table')
+  validate('pos', pos, 'table', true)
 
-  if buf == 0 then
-    buf = api.nvim_get_current_buf()
+  if pos then
+    validate('buf', buf, 'number')
+    if buf == 0 then
+      buf = api.nvim_get_current_buf()
+    end
+  else
+    local win = buf
+    validate('win', win, 'number')
+    if win == 0 then
+      win = api.nvim_get_current_win()
+    end
+
+    buf = api.nvim_win_get_buf(win)
+    pos = api.nvim_win_get_cursor(win)
   end
 
   return M.new(buf, util.from_mark(pos[1], pos[2]))

test/functional/lua/pos_spec.lua

@@ -30,6 +30,15 @@ describe('vim.pos', function()
     eq(buf, pos[3])
   end)
 
+  it('creates a position from the window cursor', function()
+    local pos, buf = exec_lua(function()
+      vim.api.nvim_buf_set_lines(0, 0, -1, true, { 'first', 'second' })
+      vim.api.nvim_win_set_cursor(0, { 2, 3 })
+      return vim.pos.cursor(0), vim.api.nvim_get_current_buf()
+    end)
+    eq({ 1, 3, buf }, pos)
+  end)
+
   it('comparisons by overloaded operators', function()
     local buf = exec_lua(function()
       return vim.api.nvim_create_buf(false, true)