feat(pos): vim.pos.cursor() without args returns curwin pos #40975

runtime/doc/lua.txt

@@ -4582,7 +4582,8 @@ 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.
+    {buf}, and the current cursor position of {win} is used. If {win} is also
+    omitted, it defaults to the current window.
 
     Example: >lua
         local buf = vim.api.nvim_win_get_buf(0)
@@ -4597,7 +4598,7 @@ cursor({buf}, {pos})                                        *vim.pos.cursor()*
       • {pos}  (`[integer, integer]`) (lnum, col) tuple
 
     Overloads: ~
-      • `fun(win: integer): vim.Pos`
+      • `fun(win?: integer): vim.Pos`
 
     Return: ~
         (`vim.Pos`) See |vim.Pos|.

runtime/doc/news.txt

@@ -332,6 +332,8 @@ LUA
   but returns `nil` on error.
 • |vim.pos| can now convert between positions and buffer offsets.
 • |vim.pos| and |vim.range| can now convert between mark positions.
+• |vim.pos.cursor()| without arguments returns the cursor position of the
+  current window.
 • |vim.ui.input()| now allows setting input scope.
 • |vim.log| provides a logging interface.
 • |vim.pack.get()| output includes revision of a pending update.

runtime/lua/vim/pos.lua

@@ -166,7 +166,8 @@ 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.
+--- and the current cursor position of {win} is used. If {win} is also omitted,
+--- it defaults to the current window.
 ---
 --- Example:
 --- ```lua
@@ -179,7 +180,7 @@ end
 ---@param buf integer
 ---@param pos [integer, integer] (lnum, col) tuple
 ---@return vim.Pos
----@overload fun(win: integer): vim.Pos
+---@overload fun(win?: integer): vim.Pos
 function M.cursor(buf, pos)
   validate('pos', pos, 'table', true)
 
@@ -190,8 +191,8 @@ function M.cursor(buf, pos)
     end
   else
     local win = buf
-    validate('win', win, 'number')
-    if win == 0 then
+    validate('win', win, 'number', true)
+    if win == 0 or win == nil then
       win = api.nvim_get_current_win()
     end
 

test/functional/lua/pos_spec.lua

@@ -32,12 +32,13 @@ describe('vim.pos', function()
   end)
 
   it('creates a position from the window cursor', function()
-    local pos, buf = exec_lua(function()
+    local pos, pos_default, 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()
+      return vim.pos.cursor(0), vim.pos.cursor(), vim.api.nvim_get_current_buf()
     end)
     eq({ 1, 3, buf }, pos)
+    eq({ 1, 3, buf }, pos_default)
   end)
 
   it('comparisons by overloaded operators', function()