feat(vim.pos): accept buf=0 for current buf #39414

runtime/doc/lua.txt

@@ -4270,8 +4270,8 @@ by |vim.Pos| objects.
     To create a new |vim.Pos| object, call `vim.pos()`.
 
     Example: >lua
-        local pos1 = vim.pos(vim.api.nvim_get_current_buf(), 3, 5)
-        local pos2 = vim.pos(vim.api.nvim_get_current_buf(), 4, 0)
+        local pos1 = vim.pos(0, 3, 5)
+        local pos2 = vim.pos(0, 4, 0)
 
         -- Operators are overloaded for comparing two `vim.Pos` objects.
         if pos1 < pos2 then
@@ -4311,13 +4311,12 @@ lsp({buf}, {pos}, {position_encoding})                         *vim.pos.lsp()*
     Creates a new |vim.Pos| from `lsp.Position`.
 
     Example: >lua
-        local buf = vim.api.nvim_get_current_buf()
         local lsp_pos = {
           line = 3,
           character = 5
         }
 
-        local pos = vim.pos.lsp(buf, lsp_pos, 'utf-16')
+        local pos = vim.pos.lsp(0, lsp_pos, 'utf-16')
 <
 
     Parameters: ~
@@ -4349,8 +4348,7 @@ to_lsp({pos}, {position_encoding})                          *vim.pos.to_lsp()*
     Converts |vim.Pos| to `lsp.Position`.
 
     Example: >lua
-        local buf = vim.api.nvim_get_current_buf()
-        local pos = vim.pos(buf, 3, 5)
+        local pos = vim.pos(0, 3, 5)
 
         -- Convert to LSP position, you can call it in a method style.
         local lsp_pos = pos:to_lsp('utf-16')
@@ -4382,13 +4380,13 @@ Provides operations to compare, calculate, and convert ranges represented by
     format conversions.
 
     Example: >lua
-        local pos1 = vim.pos(vim.api.nvim_get_current_buf(), 3, 5)
-        local pos2 = vim.pos(vim.api.nvim_get_current_buf(), 4, 0)
+        local pos1 = vim.pos(0, 3, 5)
+        local pos2 = vim.pos(0, 4, 0)
 
         -- Create a range from two positions.
         local range1 = vim.range(pos1, pos2)
         -- Or create a range from four integers representing start and end positions.
-        local range2 = vim.range(vim.api.nvim_get_current_buf(), 3, 5, 4, 0)
+        local range2 = vim.range(0, 3, 5, 4, 0)
 
         -- Because `vim.Range` is end exclusive, `range1` and `range2` both represent
         -- a range starting at the row 3, column 5 and ending at where the row 3 ends
@@ -4412,12 +4410,11 @@ cursor({buf}, {start_pos}, {end_pos})                     *vim.range.cursor()*
     Creates a new |vim.Range| from mark-like range (see |api-indexing|).
 
     Example: >lua
-        local buf = vim.api.nvim_get_current_buf()
         local start = vim.api.nvim_win_get_cursor(0)
         -- move the cursor
         local end_ = vim.api.nvim_win_get_cursor(0)
 
-        local range = vim.range.cursor(buf, start, end_)
+        local range = vim.range.cursor(0, start, end_)
 <
 
     Parameters: ~
@@ -4430,9 +4427,7 @@ extmark({buf}, {start_row}, {start_col}, {end_row}, {end_col})
     Creates a new |vim.Range| from extmark range (see |api-indexing|).
 
     Example: >lua
-        local buf = vim.api.nvim_get_current_buf()
-
-        local range = vim.range.extmark(buf, 3, 5, 4, 0)
+        local range = vim.range.extmark(0, 3, 5, 4, 0)
 <
 
     Parameters: ~
@@ -4477,13 +4472,12 @@ lsp({buf}, {range}, {position_encoding})                     *vim.range.lsp()*
     Creates a new |vim.Range| from `lsp.Range`.
 
     Example: >lua
-        local buf = vim.api.nvim_get_current_buf()
         local lsp_range = {
           ['start'] = { line = 3, character = 5 },
           ['end'] = { line = 4, character = 0 }
         }
 
-        local range = vim.range.lsp(buf, lsp_range, 'utf-16')
+        local range = vim.range.lsp(0, lsp_range, 'utf-16')
 <
 
     Parameters: ~
@@ -4495,8 +4489,7 @@ to_cursor({range})                                     *vim.range.to_cursor()*
     Converts |vim.Range| to mark-like range (see |api-indexing|).
 
     Example: >lua
-        local buf = vim.api.nvim_get_current_buf()
-        local range = vim.range(buf, 3, 5, 4, 0)
+        local range = vim.range(0, 3, 5, 4, 0)
 
         -- Convert to cursor range, you can call it in a method style.
         local cursor_range = range:to_cursor()
@@ -4509,8 +4502,7 @@ to_extmark({range})                                   *vim.range.to_extmark()*
     Converts |vim.Range| to extmark range (see |api-indexing|).
 
     Example: >lua
-        local buf = vim.api.nvim_get_current_buf()
-        local range = vim.range(buf, 3, 5, 4, 0)
+        local range = vim.range(0, 3, 5, 4, 0)
 
         -- Convert to extmark range, you can call it in a method style.
         local extmark_range = range:to_extmark()
@@ -4523,8 +4515,7 @@ to_lsp({range}, {position_encoding})                      *vim.range.to_lsp()*
     Converts |vim.Range| to `lsp.Range`.
 
     Example: >lua
-        local buf = vim.api.nvim_get_current_buf()
-        local range = vim.range(buf, 3, 5, 4, 0)
+        local range = vim.range(0, 3, 5, 4, 0)
 
         -- Convert to LSP range, you can call it in a method style.
         local lsp_range = range:to_lsp('utf-16')

runtime/lua/vim/pos.lua

@@ -16,8 +16,8 @@ local validate = vim.validate
 ---
 --- Example:
 --- ```lua
---- local pos1 = vim.pos(vim.api.nvim_get_current_buf(), 3, 5)
---- local pos2 = vim.pos(vim.api.nvim_get_current_buf(), 4, 0)
+--- local pos1 = vim.pos(0, 3, 5)
+--- local pos2 = vim.pos(0, 4, 0)
 ---
 --- -- Operators are overloaded for comparing two `vim.Pos` objects.
 --- if pos1 < pos2 then
@@ -65,6 +65,10 @@ function M.new(buf, row, col)
   validate('row', row, 'number')
   validate('col', col, 'number')
 
+  if buf == 0 then
+    buf = api.nvim_get_current_buf()
+  end
+
   ---@type vim.Pos
   local self = setmetatable({
     row,
@@ -123,8 +127,7 @@ end
 ---
 --- Example:
 --- ```lua
---- local buf = vim.api.nvim_get_current_buf()
---- local pos = vim.pos(buf, 3, 5)
+--- local pos = vim.pos(0, 3, 5)
 ---
 --- -- Convert to LSP position, you can call it in a method style.
 --- local lsp_pos = pos:to_lsp('utf-16')
@@ -150,13 +153,12 @@ end
 ---
 --- Example:
 --- ```lua
---- local buf = vim.api.nvim_get_current_buf()
 --- local lsp_pos = {
 ---   line = 3,
 ---   character = 5
 --- }
 ---
---- local pos = vim.pos.lsp(buf, lsp_pos, 'utf-16')
+--- local pos = vim.pos.lsp(0, lsp_pos, 'utf-16')
 --- ```
 ---@param buf integer
 ---@param pos lsp.Position
@@ -166,6 +168,10 @@ function M.lsp(buf, pos, position_encoding)
   validate('pos', pos, 'table')
   validate('position_encoding', position_encoding, 'string')
 
+  if buf == 0 then
+    buf = api.nvim_get_current_buf()
+  end
+
   local row, col = pos.line, pos.character
   -- When on the first character,
   -- we can ignore the difference between byte and character.
@@ -213,6 +219,10 @@ end
 ---@param row integer
 ---@param col integer
 function M.extmark(buf, row, col)
+  if buf == 0 then
+    buf = api.nvim_get_current_buf()
+  end
+
   return M.new(buf, row, col)
 end
 

runtime/lua/vim/range.lua

@@ -18,13 +18,13 @@ local api = vim.api
 ---
 --- Example:
 --- ```lua
---- local pos1 = vim.pos(vim.api.nvim_get_current_buf(), 3, 5)
---- local pos2 = vim.pos(vim.api.nvim_get_current_buf(), 4, 0)
+--- local pos1 = vim.pos(0, 3, 5)
+--- local pos2 = vim.pos(0, 4, 0)
 ---
 --- -- Create a range from two positions.
 --- local range1 = vim.range(pos1, pos2)
 --- -- Or create a range from four integers representing start and end positions.
---- local range2 = vim.range(vim.api.nvim_get_current_buf(), 3, 5, 4, 0)
+--- local range2 = vim.range(0, 3, 5, 4, 0)
 ---
 --- -- Because `vim.Range` is end exclusive, `range1` and `range2` both represent
 --- -- a range starting at the row 3, column 5 and ending at where the row 3 ends
@@ -94,6 +94,10 @@ function M.new(...)
     error('invalid parameters')
   end
 
+  if buf == 0 then
+    buf = api.nvim_get_current_buf()
+  end
+
   ---@type vim.Range
   local self = setmetatable({
     start_row,
@@ -253,8 +257,7 @@ end
 ---
 --- Example:
 --- ```lua
---- local buf = vim.api.nvim_get_current_buf()
---- local range = vim.range(buf, 3, 5, 4, 0)
+--- local range = vim.range(0, 3, 5, 4, 0)
 ---
 --- -- Convert to LSP range, you can call it in a method style.
 --- local lsp_range = range:to_lsp('utf-16')
@@ -277,13 +280,12 @@ end
 ---
 --- Example:
 --- ```lua
---- local buf = vim.api.nvim_get_current_buf()
 --- local lsp_range = {
 ---   ['start'] = { line = 3, character = 5 },
 ---   ['end'] = { line = 4, character = 0 }
 --- }
 ---
---- local range = vim.range.lsp(buf, lsp_range, 'utf-16')
+--- local range = vim.range.lsp(0, lsp_range, 'utf-16')
 --- ```
 ---@param buf integer
 ---@param range lsp.Range
@@ -293,6 +295,10 @@ function M.lsp(buf, range, position_encoding)
   validate('range', range, 'table')
   validate('position_encoding', position_encoding, 'string')
 
+  if buf == 0 then
+    buf = api.nvim_get_current_buf()
+  end
+
   -- TODO(ofseed): avoid using `Pos:lsp()` here,
   -- as they need reading files separately if buffer is unloaded.
   local start = vim.pos.lsp(buf, range['start'], position_encoding)
@@ -305,8 +311,7 @@ end
 ---
 --- Example:
 --- ```lua
---- local buf = vim.api.nvim_get_current_buf()
---- local range = vim.range(buf, 3, 5, 4, 0)
+--- local range = vim.range(0, 3, 5, 4, 0)
 ---
 --- -- Convert to extmark range, you can call it in a method style.
 --- local extmark_range = range:to_extmark()
@@ -324,9 +329,7 @@ end
 ---
 --- Example:
 --- ```lua
---- local buf = vim.api.nvim_get_current_buf()
----
---- local range = vim.range.extmark(buf, 3, 5, 4, 0)
+--- local range = vim.range.extmark(0, 3, 5, 4, 0)
 --- ```
 ---@param buf integer
 ---@param start_row integer
@@ -340,6 +343,10 @@ function M.extmark(buf, start_row, start_col, end_row, end_col)
   validate('end_row', end_row, 'number')
   validate('end_col', end_col, 'number')
 
+  if buf == 0 then
+    buf = api.nvim_get_current_buf()
+  end
+
   local start = vim.pos.extmark(buf, start_row, start_col)
   local end_ = vim.pos.extmark(buf, end_row, end_col)
 
@@ -350,8 +357,7 @@ end
 ---
 --- Example:
 --- ```lua
---- local buf = vim.api.nvim_get_current_buf()
---- local range = vim.range(buf, 3, 5, 4, 0)
+--- local range = vim.range(0, 3, 5, 4, 0)
 ---
 --- -- Convert to cursor range, you can call it in a method style.
 --- local cursor_range = range:to_cursor()
@@ -369,12 +375,11 @@ end
 ---
 --- Example:
 --- ```lua
---- local buf = vim.api.nvim_get_current_buf()
 --- local start = vim.api.nvim_win_get_cursor(0)
 --- -- move the cursor
 --- local end_ = vim.api.nvim_win_get_cursor(0)
 ---
---- local range = vim.range.cursor(buf, start, end_)
+--- local range = vim.range.cursor(0, start, end_)
 --- ```
 ---@param buf integer
 ---@param start_pos [integer, integer]
@@ -384,6 +389,10 @@ function M.cursor(buf, start_pos, end_pos)
   validate('range', start_pos, 'table')
   validate('range', end_pos, 'table')
 
+  if buf == 0 then
+    buf = api.nvim_get_current_buf()
+  end
+
   local start = vim.pos.cursor(buf, start_pos)
   local end_ = vim.pos.cursor(buf, end_pos)
 

test/functional/lua/pos_spec.lua

@@ -20,6 +20,15 @@ describe('vim.pos', function()
     eq(buf, pos[3])
   end)
 
+  it('creates a position with buf=0', function()
+    local pos, buf = exec_lua(function()
+      return vim.pos(0, 3, 5), vim.api.nvim_get_current_buf()
+    end)
+    eq(3, pos[1])
+    eq(5, pos[2])
+    eq(buf, pos[3])
+  end)
+
   it('comparisons by overloaded operators', function()
     local buf = exec_lua(function()
       return vim.api.nvim_create_buf(false, true)

test/functional/lua/range_spec.lua

@@ -22,6 +22,17 @@ describe('vim.range', function()
     eq(buf, range[5])
   end)
 
+  it('creates a range with buf=0', function()
+    local range, buf = exec_lua(function()
+      return vim.range(0, 3, 5, 4, 6), vim.api.nvim_get_current_buf()
+    end)
+    eq(3, range[1])
+    eq(5, range[2])
+    eq(4, range[3])
+    eq(6, range[4])
+    eq(buf, range[5])
+  end)
+
   it('creates a range from two positions', function()
     local range, buf1 = exec_lua(function()
       local buf = vim.api.nvim_create_buf(false, true)