commit 9f5b309d824a7b8a7496fbd23b54d96798a4f2c2
parent 98f8224c1948fd8440f13f84f19a0adb78171fe4
Author: Yi Ming <ofseed@foxmail.com>
Date: Sun, 17 Aug 2025 11:54:48 +0800
feat(lua): conversion between vim and lsp position/range
Diffstat:
5 files changed, 251 insertions(+), 6 deletions(-)
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
@@ -3986,13 +3986,54 @@ comparisons and conversions between various types of positions.
as format conversions.
Fields: ~
- • {row} (`integer`) 0-based byte index.
- • {col} (`integer`) 0-based byte index.
- • {buf}? (`integer`) Optional buffer handle.
+ • {row} (`integer`) 0-based byte index.
+ • {col} (`integer`) 0-based byte index.
+ • {buf}? (`integer`) Optional buffer handle.
+
+ When specified, it indicates that this position belongs to a
+ specific buffer. This field is required when performing
+ position conversions.
+ • {to_lsp} (`fun(pos: vim.Pos, position_encoding: lsp.PositionEncodingKind)`)
+ See |Pos:to_lsp()|.
+ • {lsp} (`fun(buf: integer, pos: lsp.Position, position_encoding: lsp.PositionEncodingKind)`)
+ See |Pos:lsp()|.
+
+
+Pos:lsp({buf}, {pos}, {position_encoding}) *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
+ }
+
+ -- `buf` is mandatory, as LSP positions are always associated with a buffer.
+ local pos = vim.pos.lsp(buf, lsp_pos, 'utf-16')
+<
+
+ Parameters: ~
+ • {buf} (`integer`)
+ • {pos} (`lsp.Position`)
+ • {position_encoding} (`lsp.PositionEncodingKind`)
+
+Pos:to_lsp({pos}, {position_encoding}) *Pos:to_lsp()*
+ Converts |vim.Pos| to `lsp.Position`.
+
+ Example: >lua
+ -- `buf` is required for conversion to LSP position.
+ local buf = vim.api.nvim_get_current_buf()
+ local pos = vim.pos(3, 5, { buf = buf })
+
+ -- Convert to LSP position, you can call it in a method style.
+ local lsp_pos = pos:lsp('utf-16')
+<
+
+ Parameters: ~
+ • {pos} (`vim.Pos`) See |vim.Pos|.
+ • {position_encoding} (`lsp.PositionEncodingKind`)
- When specified, it indicates that this position belongs to a
- specific buffer. This field is required when performing
- position conversions.
==============================================================================
Lua module: vim.range *vim.range*
@@ -4044,6 +4085,10 @@ ranges). conversions between various types of ranges is also provided.
|Range:has()|.
• {intersect} (`fun(r1: vim.Range, r2: vim.Range): vim.Range?`) See
|Range:intersect()|.
+ • {to_lsp} (`fun(range: vim.Range, position_encoding: lsp.PositionEncodingKind)`)
+ See |Range:to_lsp()|.
+ • {lsp} (`fun(buf: integer, range: lsp.Range, position_encoding: lsp.PositionEncodingKind)`)
+ See |Range:lsp()|.
Range:has({outer}, {inner}) *Range:has()*
@@ -4067,6 +4112,41 @@ Range:intersect({r1}, {r2}) *Range:intersect()*
(`vim.Range?`) range that is present inside both `r1` and `r2`. `nil`
if such range does not exist. See |vim.Range|.
+Range:lsp({buf}, {range}, {position_encoding}) *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 }
+ }
+
+ -- `buf` is mandatory, as LSP ranges are always associated with a buffer.
+ local range = vim.range.lsp(buf, lsp_range, 'utf-16')
+<
+
+ Parameters: ~
+ • {buf} (`integer`)
+ • {range} (`lsp.Range`)
+ • {position_encoding} (`lsp.PositionEncodingKind`)
+
+Range:to_lsp({range}, {position_encoding}) *Range:to_lsp()*
+ Converts |vim.Range| to `lsp.Range`.
+
+ 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 })
+
+ -- Convert to LSP range, you can call it in a method style.
+ local lsp_range = range:to_lsp('utf-16')
+<
+
+ Parameters: ~
+ • {range} (`vim.Range`) See |vim.Range|.
+ • {position_encoding} (`lsp.PositionEncodingKind`)
+
==============================================================================
Lua module: vim.re *vim.re*
diff --git a/runtime/lua/vim/pos.lua b/runtime/lua/vim/pos.lua
@@ -11,6 +11,7 @@
--- Built on |vim.Pos| objects, this module offers operations
--- that support comparisons and conversions between various types of positions.
+local api = vim.api
local validate = vim.validate
--- Represents a well-defined position.
@@ -110,6 +111,73 @@ function Pos.__eq(...)
return cmp_pos(...) == 0
end
+--- TODO(ofseed): Make it work for unloaded buffers. Check get_line() in vim.lsp.util.
+---@param buf integer
+---@param row integer
+local function get_line(buf, row)
+ return api.nvim_buf_get_lines(buf, row, row + 1, true)[1]
+end
+
+--- Converts |vim.Pos| to `lsp.Position`.
+---
+--- Example:
+--- ```lua
+--- -- `buf` is required for conversion to LSP position.
+--- local buf = vim.api.nvim_get_current_buf()
+--- local pos = vim.pos(3, 5, { buf = buf })
+---
+--- -- Convert to LSP position, you can call it in a method style.
+--- local lsp_pos = pos:lsp('utf-16')
+--- ```
+---@param pos vim.Pos
+---@param position_encoding lsp.PositionEncodingKind
+function Pos.to_lsp(pos, position_encoding)
+ validate('pos', pos, 'table')
+ validate('position_encoding', position_encoding, 'string')
+
+ local buf = assert(pos.buf, 'position is not a buffer position')
+ local row, col = pos.row, pos.col
+ -- When on the first character,
+ -- we can ignore the difference between byte and character.
+ if col > 0 then
+ col = vim.str_utfindex(get_line(buf, row), position_encoding, col, false)
+ end
+
+ ---@type lsp.Position
+ return { line = row, character = col }
+end
+
+--- 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
+--- }
+---
+--- -- `buf` is mandatory, as LSP positions are always associated with a buffer.
+--- local pos = vim.pos.lsp(buf, lsp_pos, 'utf-16')
+--- ```
+---@param buf integer
+---@param pos lsp.Position
+---@param position_encoding lsp.PositionEncodingKind
+function Pos.lsp(buf, pos, position_encoding)
+ validate('buf', buf, 'number')
+ validate('pos', pos, 'table')
+ validate('position_encoding', position_encoding, 'string')
+
+ local row, col = pos.line, pos.character
+ -- When on the first character,
+ -- we can ignore the difference between byte and character.
+ if col > 0 then
+ col = vim.str_byteindex(get_line(buf, row), position_encoding, col)
+ end
+
+ return Pos.new(row, col, { buf = buf })
+end
+
-- Overload `Range.new` to allow calling this module as a function.
setmetatable(Pos, {
__call = function(_, ...)
diff --git a/runtime/lua/vim/range.lua b/runtime/lua/vim/range.lua
@@ -129,6 +129,59 @@ function Range.intersect(r1, r2)
return Range.new(rs.start, re.end_)
end
+--- Converts |vim.Range| to `lsp.Range`.
+---
+--- 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 })
+---
+--- -- 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
+function Range.to_lsp(range, position_encoding)
+ validate('range', range, 'table')
+ validate('position_encoding', position_encoding, 'string', true)
+
+ ---@type lsp.Range
+ return {
+ ['start'] = range.start:to_lsp(position_encoding),
+ ['end'] = range.end_:to_lsp(position_encoding),
+ }
+end
+
+--- 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 }
+--- }
+---
+--- -- `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
+---@param range lsp.Range
+---@param position_encoding lsp.PositionEncodingKind
+function Range.lsp(buf, range, position_encoding)
+ validate('buf', buf, 'number')
+ validate('range', range, 'table')
+ validate('position_encoding', position_encoding, 'string')
+
+ -- 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)
+ local end_ = vim.pos.lsp(buf, range['end'], position_encoding)
+
+ return Range.new(start, end_)
+end
+
-- Overload `Range.new` to allow calling this module as a function.
setmetatable(Range, {
__call = function(_, ...)
diff --git a/test/functional/lua/pos_spec.lua b/test/functional/lua/pos_spec.lua
@@ -5,6 +5,7 @@ local eq = t.eq
local clear = n.clear
local exec_lua = n.exec_lua
+local insert = n.insert
describe('vim.pos', function()
before_each(clear)
@@ -67,4 +68,24 @@ describe('vim.pos', function()
end)
)
end)
+
+ it('supports conversion between vim.Pos and lsp.Position', function()
+ local buf = exec_lua(function()
+ return vim.api.nvim_get_current_buf()
+ end)
+ insert('Neovim 是 Vim 的分支，专注于扩展性和可用性。')
+ local lsp_pos = exec_lua(function()
+ local pos = vim.pos(0, 36, { buf = buf })
+ return pos:to_lsp('utf-16')
+ end)
+ eq({ line = 0, character = 20 }, lsp_pos)
+ local pos = exec_lua(function()
+ return vim.pos.lsp(buf, lsp_pos, 'utf-16')
+ end)
+ eq({
+ buf = buf,
+ row = 0,
+ col = 36,
+ }, pos)
+ end)
end)
diff --git a/test/functional/lua/range_spec.lua b/test/functional/lua/range_spec.lua
@@ -5,6 +5,7 @@ local eq = t.eq
local clear = n.clear
local exec_lua = n.exec_lua
+local insert = n.insert
describe('vim.range', function()
before_each(clear)
@@ -60,4 +61,26 @@ describe('vim.range', function()
end)
eq(success, false)
end)
+
+ it('supports conversion between vim.Range and lsp.Range', function()
+ local buf = exec_lua(function()
+ return vim.api.nvim_get_current_buf()
+ end)
+ insert('Neovim 是 Vim 的分支，专注于扩展性和可用性。')
+ local lsp_range = exec_lua(function()
+ local range = vim.range(0, 10, 0, 36, { buf = buf })
+ return range:to_lsp('utf-16')
+ end)
+ eq({
+ ['start'] = { line = 0, character = 8 },
+ ['end'] = { line = 0, character = 20 },
+ }, lsp_range)
+ local range = exec_lua(function()
+ return vim.range.lsp(buf, lsp_range, 'utf-16')
+ end)
+ eq({
+ start = { row = 0, col = 10, buf = buf },
+ end_ = { row = 0, col = 36, buf = buf },
+ }, range)
+ end)
end)
