diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index bb73ef6733..258cd71996 100644 --- 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 index 7bc57eaa20..648be60e81 100644 --- 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 index 8302c74337..7fdb170874 100644 --- 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 index cb22d100b9..176c6489b0 100644 --- 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 index fea8aa3e85..662cc3a5e6 100644 --- 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)