From 01be30f638151a5654b5bc899080c49a63c2d9eb Mon Sep 17 00:00:00 2001 From: Luis Calle <53507599+TheLeoP@users.noreply.github.com> Date: Mon, 6 Apr 2026 10:51:36 -0500 Subject: feat(vim.pos)!: require `buf` param on vim.pos, vim.range #38665 Problem: `buf` is optional even though its needed to perform conversions and the ordering of `(buf, row, col)` is not consistent. Solution: make `buf` mandatory on `vim.range` and `vim.pos` and enforce the `buf, row, col` ordering --- runtime/lua/vim/range.lua | 88 ++++++++++++++++++++--------------------------- 1 file changed, 38 insertions(+), 50 deletions(-) (limited to 'runtime/lua/vim/range.lua') diff --git a/runtime/lua/vim/range.lua b/runtime/lua/vim/range.lua index 5613d3d789..8ffe880690 100644 --- a/runtime/lua/vim/range.lua +++ b/runtime/lua/vim/range.lua @@ -41,16 +41,12 @@ local api = vim.api ---@field start_col integer 0-based byte index. ---@field end_row integer 0-based byte index. ---@field end_col integer 0-based byte index. ---- ---- Optional buffer handle. ---- ---- When specified, it indicates that this range belongs to a specific buffer. ---- This field is required when performing range conversions. ----@field buf? integer +---@field buf integer Optional buffer handle. ---@field private [1] integer underlying representation of start_row ---@field private [2] integer underlying representation of start_col ---@field private [3] integer underlying representation of end_row ---@field private [4] integer underlying representation of end_col +---@field private [5] integer underlying representation of buf local Range = {} ---@private @@ -74,7 +70,7 @@ end ---@package ---@overload fun(self: vim.Range, start: vim.Pos, end_: vim.Pos): vim.Range ----@overload fun(self: vim.Range, start_row: integer, start_col: integer, end_row: integer, end_col: integer, opts?: vim.Pos.Optional): vim.Range +---@overload fun(self: vim.Range, buf: integer, start_row: integer, start_col: integer, end_row: integer, end_col: integer): vim.Range function Range.new(...) ---@type integer, integer, integer, integer, integer|nil local start_row, start_col, end_row, end_col, buf @@ -91,11 +87,9 @@ function Range.new(...) end start_row, start_col, end_row, end_col, buf = start.row, start.col, end_.row, end_.col, start.buf - elseif nargs == 4 or nargs == 5 then - local opts - ---@type integer, integer, integer, integer, vim.Pos.Optional|nil - start_row, start_col, end_row, end_col, opts = ... - buf = opts and opts.buf + elseif nargs == 5 then + ---@type integer, integer, integer, integer, integer + buf, start_row, start_col, end_row, end_col = ... else error('invalid parameters') end @@ -147,7 +141,7 @@ end ---@param col integer ---@param buf integer ---@return integer, integer -local function to_inclusive_pos(row, col, buf) +local function to_inclusive_pos(buf, row, col) if col > 0 then col = col - 1 elseif col == 0 and row > 0 then @@ -163,7 +157,7 @@ end ---@param r2 vim.Range function Range.__lt(r1, r2) local r1_inclusive_end_row, r1_inclusive_end_col = - to_inclusive_pos(r1.end_row, r1.end_col, r1.buf) + to_inclusive_pos(r1.buf, r1.end_row, r1.end_col) return cmp_pos(r1_inclusive_end_row, r1_inclusive_end_col, r2.start_row, r2.start_col) == -1 end @@ -172,7 +166,7 @@ end ---@param r2 vim.Range function Range.__le(r1, r2) local r1_inclusive_end_row, r1_inclusive_end_col = - to_inclusive_pos(r1.end_row, r1.end_col, r1.buf) + to_inclusive_pos(r1.buf, r1.end_row, r1.end_col) return cmp_pos(r1_inclusive_end_row, r1_inclusive_end_col, r2.start_row, r2.start_col) ~= 1 end @@ -189,7 +183,7 @@ end ---@return boolean `true` if the given range is empty function Range:is_empty() local inclusive_end_row, inclusive_end_col = - to_inclusive_pos(self.end_row, self.end_col, self.buf) + to_inclusive_pos(self.buf, self.end_row, self.end_col) return cmp_pos(self.start_row, self.start_col, inclusive_end_row, inclusive_end_col) ~= -1 end @@ -208,9 +202,9 @@ function Range.has(outer, inner) ---@cast inner -vim.Pos local outer_inclusive_end_row, outer_inclusive_end_col = - to_inclusive_pos(outer.end_row, outer.end_col, outer.buf) + to_inclusive_pos(outer.buf, outer.end_row, outer.end_col) local inner_inclusive_end_row, inner_inclusive_end_col = - to_inclusive_pos(inner.end_row, inner.end_col, inner.buf) + to_inclusive_pos(inner.buf, inner.end_row, inner.end_col) return cmp_pos(outer.start_row, outer.start_col, inner.start_row, inner.start_col) ~= 1 and cmp_pos(outer.end_row, outer.end_col, inner.end_row, inner.end_col) ~= -1 @@ -234,9 +228,9 @@ end --- `nil` if such range does not exist. function Range.intersect(r1, r2) local r1_inclusive_end_row, r1_inclusive_end_col = - to_inclusive_pos(r1.end_row, r1.end_col, r1.buf) + to_inclusive_pos(r1.buf, r1.end_row, r1.end_col) local r2_inclusive_end_row, r2_inclusive_end_col = - to_inclusive_pos(r2.end_row, r2.end_col, r2.buf) + to_inclusive_pos(r2.buf, r2.end_row, r2.end_col) if cmp_pos(r1_inclusive_end_row, r1_inclusive_end_col, r2.start_row, r2.start_col) ~= 1 @@ -254,9 +248,8 @@ end --- --- Example: --- ```lua ---- -- `buf` is required for conversion to LSP range. --- local buf = vim.api.nvim_get_current_buf() ---- local range = vim.range(3, 5, 4, 0, { buf = buf }) +--- local range = vim.range(buf, 3, 5, 4, 0) --- --- -- Convert to LSP range, you can call it in a method style. --- local lsp_range = range:to_lsp('utf-16') @@ -270,10 +263,8 @@ function Range.to_lsp(range, position_encoding) ---@type lsp.Range return { - ['start'] = vim - .pos(range.start_row, range.start_col, { buf = range.buf }) - :to_lsp(position_encoding), - ['end'] = vim.pos(range.end_row, range.end_col, { buf = range.buf }):to_lsp(position_encoding), + ['start'] = vim.pos(range.buf, range.start_row, range.start_col):to_lsp(position_encoding), + ['end'] = vim.pos(range.buf, range.end_row, range.end_col):to_lsp(position_encoding), } end @@ -287,7 +278,6 @@ end --- ['end'] = { line = 4, character = 0 } --- } --- ---- -- `buf` is mandatory, as LSP ranges are always associated with a buffer. --- local range = vim.range.lsp(buf, lsp_range, 'utf-16') --- ``` ---@param buf integer @@ -310,9 +300,8 @@ end --- --- Example: --- ```lua ---- -- `buf` is required for conversion to extmark range. --- local buf = vim.api.nvim_get_current_buf() ---- local range = vim.range(3, 5, 4, 0, { buf = buf }) +--- local range = vim.range(buf, 3, 5, 4, 0) --- --- -- Convert to extmark range, you can call it in a method style. --- local extmark_range = range:to_extmark() @@ -321,8 +310,8 @@ end function Range.to_extmark(range) validate('range', range, 'table') - local srow, scol = vim.pos(range.start_row, range.start_col, { buf = range.buf }):to_extmark() - local erow, ecol = vim.pos(range.end_row, range.end_col, { buf = range.buf }):to_extmark() + local srow, scol = vim.pos(range.buf, range.start_row, range.start_col):to_extmark() + local erow, ecol = vim.pos(range.buf, range.end_row, range.end_col):to_extmark() return srow, scol, erow, ecol end @@ -332,21 +321,22 @@ end --- ```lua --- local buf = vim.api.nvim_get_current_buf() --- ---- local range = vim.range.extmark(3, 5, 4, 0, { buf = buf }) +--- local range = vim.range.extmark(buf, 3, 5, 4, 0) --- ``` +---@param buf integer ---@param start_row integer ---@param start_col integer ---@param end_row integer ---@param end_col integer ----@param opts vim.Pos.Optional|nil -function Range.extmark(start_row, start_col, end_row, end_col, opts) - validate('range', start_row, 'number') - validate('range', start_col, 'number') - validate('range', end_row, 'number') - validate('range', end_col, 'number') +function Range.extmark(buf, start_row, start_col, end_row, end_col) + validate('buf', buf, 'number') + validate('start_row', start_row, 'number') + validate('start_col', start_col, 'number') + validate('end_row', end_row, 'number') + validate('end_col', end_col, 'number') - local start = vim.pos.extmark(start_row, start_col, opts) - local end_ = vim.pos.extmark(end_row, end_col, opts) + local start = vim.pos.extmark(buf, start_row, start_col) + local end_ = vim.pos.extmark(buf, end_row, end_col) return Range.new(start, end_) end @@ -355,9 +345,8 @@ end --- --- Example: --- ```lua ---- -- `buf` is required for conversion to extmark range. --- local buf = vim.api.nvim_get_current_buf() ---- local range = vim.range(3, 5, 4, 0, { buf = buf }) +--- local range = vim.range(buf, 3, 5, 4, 0) --- --- -- Convert to cursor range, you can call it in a method style. --- local cursor_range = range:to_cursor() @@ -366,8 +355,8 @@ end function Range.to_cursor(range) validate('range', range, 'table') - local srow, scol = vim.pos(range.start_row, range.start_col, { buf = range.buf }):to_cursor() - local erow, ecol = vim.pos(range.end_row, range.end_col, { buf = range.buf }):to_cursor() + local srow, scol = vim.pos(range.buf, range.start_row, range.start_col):to_cursor() + local erow, ecol = vim.pos(range.buf, range.end_row, range.end_col):to_cursor() return srow, scol, erow, ecol end @@ -380,19 +369,18 @@ end --- -- move the cursor --- local end_ = vim.api.nvim_win_get_cursor(0) --- ---- local range = vim.range.cursor(start, end_, { buf = buf }) +--- local range = vim.range.cursor(buf, start, end_) --- ``` ---@param buf integer ---@param start_pos [integer, integer] ---@param end_pos [integer, integer] ----@param opts vim.Pos.Optional|nil -function Range.cursor(buf, start_pos, end_pos, opts) +function Range.cursor(buf, start_pos, end_pos) validate('buf', buf, 'number') validate('range', start_pos, 'table') validate('range', end_pos, 'table') - local start = vim.pos.cursor(start_pos, opts) - local end_ = vim.pos.cursor(end_pos, opts) + local start = vim.pos.cursor(buf, start_pos) + local end_ = vim.pos.cursor(buf, end_pos) return Range.new(start, end_) end @@ -404,6 +392,6 @@ setmetatable(Range, { end, }) ---@cast Range +fun(start: vim.Pos, end_: vim.Pos): vim.Range ----@cast Range +fun(start_row: integer, start_col: integer, end_row: integer, end_col: integer, opts?: vim.Pos.Optional): vim.Range +---@cast Range +fun(buf: integer, start_row: integer, start_col: integer, end_row: integer, end_col: integer): vim.Range return Range -- cgit