mirror of
https://github.com/neovim/neovim.git
synced 2026-04-19 14:00:49 +00:00
docs: vim.range, vim.pos #38869
Problem:
`vim.Range` and `vim.Pos` have signature mismatches on the docs of some functions.
Solution:
Split the "module" functions from the "class" functions (just like it's done in other modules like `vim.version`) and regenerate the docs.
(cherry picked from commit c530fd8e75)
This commit is contained in:
Luis Calle
committed by
github-actions[bot]
github-actions[bot]
parent
11a4a0077c
commit
f529bc74f9
@@ -6,6 +6,8 @@
|
||||
--- Provides operations to compare, calculate, and convert ranges represented by |vim.Range|
|
||||
--- objects.
|
||||
|
||||
local M = {}
|
||||
|
||||
local validate = vim.validate
|
||||
local api = vim.api
|
||||
|
||||
@@ -49,7 +51,6 @@ local api = vim.api
|
||||
---@field private [5] integer underlying representation of buf
|
||||
local Range = {}
|
||||
|
||||
---@private
|
||||
---@param pos vim.Range
|
||||
---@param key any
|
||||
function Range.__index(pos, key)
|
||||
@@ -152,7 +153,6 @@ local function to_inclusive_pos(buf, row, col)
|
||||
return row, col
|
||||
end
|
||||
|
||||
---@private
|
||||
---@param r1 vim.Range
|
||||
---@param r2 vim.Range
|
||||
function Range.__lt(r1, r2)
|
||||
@@ -161,7 +161,6 @@ function Range.__lt(r1, r2)
|
||||
return cmp_pos(r1_inclusive_end_row, r1_inclusive_end_col, r2.start_row, r2.start_col) == -1
|
||||
end
|
||||
|
||||
---@private
|
||||
---@param r1 vim.Range
|
||||
---@param r2 vim.Range
|
||||
function Range.__le(r1, r2)
|
||||
@@ -170,7 +169,6 @@ function Range.__le(r1, r2)
|
||||
return cmp_pos(r1_inclusive_end_row, r1_inclusive_end_col, r2.start_row, r2.start_col) ~= 1
|
||||
end
|
||||
|
||||
---@private
|
||||
---@param r1 vim.Range
|
||||
---@param r2 vim.Range
|
||||
function Range.__eq(r1, r2)
|
||||
@@ -188,29 +186,28 @@ function Range:is_empty()
|
||||
return cmp_pos(self.start_row, self.start_col, inclusive_end_row, inclusive_end_col) ~= -1
|
||||
end
|
||||
|
||||
--- Checks whether {outer} range contains {inner} range or position.
|
||||
--- Checks whether range contains {inner} range or position.
|
||||
---
|
||||
---@param outer vim.Range
|
||||
---@param inner vim.Range|vim.Pos
|
||||
---@return boolean `true` if {outer} range fully contains {inner} range or position.
|
||||
function Range.has(outer, inner)
|
||||
if getmetatable(inner) == vim.pos then
|
||||
---@return boolean `true` if range fully contains {inner} range or position.
|
||||
function Range:has(inner)
|
||||
if getmetatable(inner) == vim.pos._Pos then
|
||||
---@cast inner -vim.Range
|
||||
return cmp_pos(outer.start_row, outer.start_col, inner.row, inner.col) ~= 1
|
||||
and cmp_pos(outer.end_row, outer.end_col, inner.row, inner.col) ~= -1
|
||||
return cmp_pos(self.start_row, self.start_col, inner.row, inner.col) ~= 1
|
||||
and cmp_pos(self.end_row, self.end_col, inner.row, inner.col) ~= -1
|
||||
end
|
||||
---@cast inner -vim.Pos
|
||||
|
||||
local outer_inclusive_end_row, outer_inclusive_end_col =
|
||||
to_inclusive_pos(outer.buf, outer.end_row, outer.end_col)
|
||||
to_inclusive_pos(self.buf, self.end_row, self.end_col)
|
||||
local inner_inclusive_end_row, inner_inclusive_end_col =
|
||||
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
|
||||
return cmp_pos(self.start_row, self.start_col, inner.start_row, inner.start_col) ~= 1
|
||||
and cmp_pos(self.end_row, self.end_col, inner.end_row, inner.end_col) ~= -1
|
||||
-- accounts for empty ranges at the start/end of `outer` that per Neovim API and LSP logic
|
||||
-- insert the text outside `outer`
|
||||
and cmp_pos(outer.start_row, outer.start_col, inner_inclusive_end_row, inner_inclusive_end_col) == -1
|
||||
and cmp_pos(self.start_row, self.start_col, inner_inclusive_end_row, inner_inclusive_end_col) == -1
|
||||
and cmp_pos(
|
||||
outer_inclusive_end_row,
|
||||
outer_inclusive_end_col,
|
||||
@@ -220,27 +217,26 @@ function Range.has(outer, inner)
|
||||
== 1
|
||||
end
|
||||
|
||||
--- Computes the common range shared by the given ranges.
|
||||
--- Computes the common range shared by range and {r2}
|
||||
---
|
||||
---@param r1 vim.Range First range to intersect.
|
||||
---@param r2 vim.Range Second range to intersect
|
||||
---@return vim.Range? range that is present inside both `r1` and `r2`.
|
||||
---@return vim.Range? range that is present inside both range and `r2`.
|
||||
--- `nil` if such range does not exist.
|
||||
function Range.intersect(r1, r2)
|
||||
function Range:intersect(r2)
|
||||
local r1_inclusive_end_row, r1_inclusive_end_col =
|
||||
to_inclusive_pos(r1.buf, r1.end_row, r1.end_col)
|
||||
to_inclusive_pos(self.buf, self.end_row, self.end_col)
|
||||
local r2_inclusive_end_row, r2_inclusive_end_col =
|
||||
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
|
||||
or cmp_pos(r1.start_row, r1.start_col, r2_inclusive_end_row, r2_inclusive_end_col) ~= -1
|
||||
or cmp_pos(self.start_row, self.start_col, r2_inclusive_end_row, r2_inclusive_end_col) ~= -1
|
||||
then
|
||||
return nil
|
||||
end
|
||||
|
||||
local rs = cmp_pos(r1.start_row, r1.start_col, r2.start_row, r2.start_col) ~= 1 and r2 or r1
|
||||
local re = cmp_pos(r1.end_row, r1.end_col, r2.end_row, r2.end_col) ~= -1 and r2 or r1
|
||||
local rs = cmp_pos(self.start_row, self.start_col, r2.start_row, r2.start_col) ~= 1 and r2 or self
|
||||
local re = cmp_pos(self.end_row, self.end_col, r2.end_row, r2.end_col) ~= -1 and r2 or self
|
||||
return Range.new(rs.start_row, rs.start_col, re.end_row, re.end_col)
|
||||
end
|
||||
|
||||
@@ -254,17 +250,15 @@ end
|
||||
--- -- Convert to LSP range, you can call it in a method style.
|
||||
--- local lsp_range = range:to_lsp('utf-16')
|
||||
--- ```
|
||||
---@param range vim.Range
|
||||
---@param position_encoding lsp.PositionEncodingKind
|
||||
---@return lsp.Range
|
||||
function Range.to_lsp(range, position_encoding)
|
||||
validate('range', range, 'table')
|
||||
function Range:to_lsp(position_encoding)
|
||||
validate('position_encoding', position_encoding, 'string', true)
|
||||
|
||||
---@type lsp.Range
|
||||
return {
|
||||
['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),
|
||||
['start'] = vim.pos(self.buf, self.start_row, self.start_col):to_lsp(position_encoding),
|
||||
['end'] = vim.pos(self.buf, self.end_row, self.end_col):to_lsp(position_encoding),
|
||||
}
|
||||
end
|
||||
|
||||
@@ -283,7 +277,8 @@ end
|
||||
---@param buf integer
|
||||
---@param range lsp.Range
|
||||
---@param position_encoding lsp.PositionEncodingKind
|
||||
function Range.lsp(buf, range, position_encoding)
|
||||
---@return vim.Range
|
||||
function M.lsp(buf, range, position_encoding)
|
||||
validate('buf', buf, 'number')
|
||||
validate('range', range, 'table')
|
||||
validate('position_encoding', position_encoding, 'string')
|
||||
@@ -306,12 +301,9 @@ end
|
||||
--- -- Convert to extmark range, you can call it in a method style.
|
||||
--- local extmark_range = range:to_extmark()
|
||||
--- ```
|
||||
---@param range vim.Range
|
||||
function Range.to_extmark(range)
|
||||
validate('range', range, 'table')
|
||||
|
||||
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()
|
||||
function Range:to_extmark()
|
||||
local srow, scol = vim.pos(self.buf, self.start_row, self.start_col):to_extmark()
|
||||
local erow, ecol = vim.pos(self.buf, self.end_row, self.end_col):to_extmark()
|
||||
return srow, scol, erow, ecol
|
||||
end
|
||||
|
||||
@@ -328,7 +320,8 @@ end
|
||||
---@param start_col integer
|
||||
---@param end_row integer
|
||||
---@param end_col integer
|
||||
function Range.extmark(buf, start_row, start_col, end_row, end_col)
|
||||
---@return vim.Range
|
||||
function M.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')
|
||||
@@ -351,12 +344,9 @@ end
|
||||
--- -- Convert to cursor range, you can call it in a method style.
|
||||
--- local cursor_range = range:to_cursor()
|
||||
--- ```
|
||||
---@param range vim.Range
|
||||
function Range.to_cursor(range)
|
||||
validate('range', range, 'table')
|
||||
|
||||
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()
|
||||
function Range:to_cursor()
|
||||
local srow, scol = vim.pos(self.buf, self.start_row, self.start_col):to_cursor()
|
||||
local erow, ecol = vim.pos(self.buf, self.end_row, self.end_col):to_cursor()
|
||||
return srow, scol, erow, ecol
|
||||
end
|
||||
|
||||
@@ -374,7 +364,8 @@ end
|
||||
---@param buf integer
|
||||
---@param start_pos [integer, integer]
|
||||
---@param end_pos [integer, integer]
|
||||
function Range.cursor(buf, start_pos, end_pos)
|
||||
---@return vim.Range
|
||||
function M.cursor(buf, start_pos, end_pos)
|
||||
validate('buf', buf, 'number')
|
||||
validate('range', start_pos, 'table')
|
||||
validate('range', end_pos, 'table')
|
||||
@@ -385,13 +376,12 @@ function Range.cursor(buf, start_pos, end_pos)
|
||||
return Range.new(start, end_)
|
||||
end
|
||||
|
||||
-- Overload `Range.new` to allow calling this module as a function.
|
||||
setmetatable(Range, {
|
||||
setmetatable(M, {
|
||||
__call = function(_, ...)
|
||||
return Range.new(...)
|
||||
end,
|
||||
})
|
||||
---@cast Range +fun(start: vim.Pos, end_: vim.Pos): vim.Range
|
||||
---@cast Range +fun(buf: integer, start_row: integer, start_col: integer, end_row: integer, end_col: integer): vim.Range
|
||||
---@cast M +fun(start: vim.Pos, end_: vim.Pos): vim.Range
|
||||
---@cast M +fun(buf: integer, start_row: integer, start_col: integer, end_row: integer, end_col: integer): vim.Range
|
||||
|
||||
return Range
|
||||
return M
|
||||
|
||||
Reference in New Issue
Block a user