-- Nvim-Lua stdlib: the `vim` module (:help lua-stdlib)
--
-- Lua code lives in one of three places:
-- 1. runtime/lua/vim/ (the runtime): For "nice to have" features, e.g. the
-- `inspect` and `lpeg` modules.
-- 2. runtime/lua/vim/shared.lua: pure lua functions which always
-- are available. Used in the test runner, as well as worker threads
-- and processes launched from Nvim.
-- 3. runtime/lua/vim/_editor.lua: Code which directly interacts with
-- the Nvim editor state. Only available in the main thread.
--
-- Guideline: "If in doubt, put it in the runtime".
--
-- Most functions should live directly in `vim.`, not in submodules.
-- The only "forbidden" names are those claimed by legacy `if_lua`:
-- $ vim
-- :lua for k,v in pairs(vim) do print(k) end
-- buffer
-- open
-- window
-- lastline
-- firstline
-- type
-- line
-- eval
-- dict
-- beep
-- list
-- command
--
-- Reference (#6580):
-- - https://github.com/luafun/luafun
-- - https://github.com/rxi/lume
-- - http://leafo.net/lapis/reference/utilities.html
-- - https://github.com/torch/paths
-- - https://github.com/bakpakin/Fennel (pretty print, repl)
-- - https://github.com/howl-editor/howl/tree/master/lib/howl/util
local vim = assert(vim)
-- These are for loading runtime modules lazily since they aren't available in
-- the nvim binary as specified in executor.c
for k,v in pairs {
treesitter=true;
filetype = true;
F=true;
lsp=true;
highlight=true;
diagnostic=true;
keymap=true;
ui=true;
} do vim._submodules[k] = v end
vim.log = {
levels = {
TRACE = 0;
DEBUG = 1;
INFO = 2;
WARN = 3;
ERROR = 4;
}
}
-- Internal-only until comments in #8107 are addressed.
-- Returns:
-- {errcode}, {output}
function vim._system(cmd)
local out = vim.fn.system(cmd)
local err = vim.v.shell_error
return err, out
end
-- Gets process info from the `ps` command.
-- Used by nvim_get_proc() as a fallback.
function vim._os_proc_info(pid)
if pid == nil or pid <= 0 or type(pid) ~= 'number' then
error('invalid pid')
end
local cmd = { 'ps', '-p', pid, '-o', 'comm=', }
local err, name = vim._system(cmd)
if 1 == err and vim.trim(name) == '' then
return {} -- Process not found.
elseif 0 ~= err then
error('command failed: '..vim.fn.string(cmd))
end
local _, ppid = vim._system({ 'ps', '-p', pid, '-o', 'ppid=', })
-- Remove trailing whitespace.
name = vim.trim(name):gsub('^.*/', '')
ppid = tonumber(ppid) or -1
return {
name = name,
pid = pid,
ppid = ppid,
}
end
-- Gets process children from the `pgrep` command.
-- Used by nvim_get_proc_children() as a fallback.
function vim._os_proc_children(ppid)
if ppid == nil or ppid <= 0 or type(ppid) ~= 'number' then
error('invalid ppid')
end
local cmd = { 'pgrep', '-P', ppid, }
local err, rv = vim._system(cmd)
if 1 == err and vim.trim(rv) == '' then
return {} -- Process not found.
elseif 0 ~= err then
error('command failed: '..vim.fn.string(cmd))
end
local children = {}
for s in rv:gmatch('%S+') do
local i = tonumber(s)
if i ~= nil then
table.insert(children, i)
end
end
return children
end
-- TODO(ZyX-I): Create compatibility layer.
--- Return a human-readable representation of the given object.
---
---@see https://github.com/kikito/inspect.lua
---@see https://github.com/mpeterv/vinspect
local function inspect(object, options) -- luacheck: no unused
error(object, options) -- Stub for gen_vimdoc.py
end
do
local tdots, tick, got_line1 = 0, 0, false
--- Paste handler, invoked by |nvim_paste()| when a conforming UI
--- (such as the |TUI|) pastes text into the editor.
---
--- Example: To remove ANSI color codes when pasting:
---
--- vim.paste = (function(overridden)
--- return function(lines, phase)
--- for i,line in ipairs(lines) do
--- -- Scrub ANSI color codes from paste input.
--- lines[i] = line:gsub('\27%[[0-9;mK]+', '')
--- end
--- overridden(lines, phase)
--- end
--- end)(vim.paste)
---
---
---@see |paste|
---
---@param lines |readfile()|-style list of lines to paste. |channel-lines|
---@param phase -1: "non-streaming" paste: the call contains all lines.
--- If paste is "streamed", `phase` indicates the stream state:
--- - 1: starts the paste (exactly once)
--- - 2: continues the paste (zero or more times)
--- - 3: ends the paste (exactly once)
---@returns false if client should cancel the paste.
function vim.paste(lines, phase)
local call = vim.api.nvim_call_function
local now = vim.loop.now()
local mode = call('mode', {}):sub(1,1)
if phase < 2 then -- Reset flags.
tdots, tick, got_line1 = now, 0, false
elseif mode ~= 'c' then
vim.api.nvim_command('undojoin')
end
if mode == 'c' and not got_line1 then -- cmdline-mode: paste only 1 line.
got_line1 = (#lines > 1)
vim.api.nvim_set_option('paste', true) -- For nvim_input().
local line1 = lines[1]:gsub('<', ''):gsub('[\r\n\012\027]', ' ') -- Scrub.
vim.api.nvim_input(line1)
vim.api.nvim_set_option('paste', false)
elseif mode ~= 'c' then
if phase < 2 and mode:find('^[vV\22sS\19]') then
vim.api.nvim_command([[exe "normal! \"]])
vim.api.nvim_put(lines, 'c', false, true)
elseif phase < 2 and not mode:find('^[iRt]') then
vim.api.nvim_put(lines, 'c', true, true)
-- XXX: Normal-mode: workaround bad cursor-placement after first chunk.
vim.api.nvim_command('normal! a')
elseif phase < 2 and mode == 'R' then
local nchars = 0
for _, line in ipairs(lines) do
nchars = nchars + line:len()
end
local row, col = unpack(vim.api.nvim_win_get_cursor(0))
local bufline = vim.api.nvim_buf_get_lines(0, row-1, row, true)[1]
local firstline = lines[1]
firstline = bufline:sub(1, col)..firstline
lines[1] = firstline
lines[#lines] = lines[#lines]..bufline:sub(col + nchars + 1, bufline:len())
vim.api.nvim_buf_set_lines(0, row-1, row, false, lines)
else
vim.api.nvim_put(lines, 'c', false, true)
end
end
if phase ~= -1 and (now - tdots >= 100) then
local dots = ('.'):rep(tick % 4)
tdots = now
tick = tick + 1
-- Use :echo because Lua print('') is a no-op, and we want to clear the
-- message when there are zero dots.
vim.api.nvim_command(('echo "%s"'):format(dots))
end
if phase == -1 or phase == 3 then
vim.api.nvim_command('redraw'..(tick > 1 and '|echo ""' or ''))
end
return true -- Paste will not continue if not returning `true`.
end
end
--- Defers callback `cb` until the Nvim API is safe to call.
---
---@see |lua-loop-callbacks|
---@see |vim.schedule()|
---@see |vim.in_fast_event()|
function vim.schedule_wrap(cb)
return (function (...)
local args = vim.F.pack_len(...)
vim.schedule(function() cb(vim.F.unpack_len(args)) end)
end)
end
-- vim.fn.{func}(...)
vim.fn = setmetatable({}, {
__index = function(t, key)
local _fn
if vim.api[key] ~= nil then
_fn = function()
error(string.format("Tried to call API function with vim.fn: use vim.api.%s instead", key))
end
else
_fn = function(...)
return vim.call(key, ...)
end
end
t[key] = _fn
return _fn
end
})
vim.funcref = function(viml_func_name)
return vim.fn[viml_func_name]
end
-- An easier alias for commands.
vim.cmd = function(command)
return vim.api.nvim_exec(command, false)
end
-- These are the vim.env/v/g/o/bo/wo variable magic accessors.
do
local validate = vim.validate
--@private
local function make_dict_accessor(scope, handle)
validate {
scope = {scope, 's'};
}
local mt = {}
function mt:__newindex(k, v)
return vim._setvar(scope, handle or 0, k, v)
end
function mt:__index(k)
if handle == nil and type(k) == 'number' then
return make_dict_accessor(scope, k)
end
return vim._getvar(scope, handle or 0, k)
end
return setmetatable({}, mt)
end
vim.g = make_dict_accessor('g', false)
vim.v = make_dict_accessor('v', false)
vim.b = make_dict_accessor('b')
vim.w = make_dict_accessor('w')
vim.t = make_dict_accessor('t')
end
--- Get a table of lines with start, end columns for a region marked by two points
---
---@param bufnr number of buffer
---@param pos1 (line, column) tuple marking beginning of region
---@param pos2 (line, column) tuple marking end of region
---@param regtype type of selection (:help setreg)
---@param inclusive boolean indicating whether the selection is end-inclusive
---@return region lua table of the form {linenr = {startcol,endcol}}
function vim.region(bufnr, pos1, pos2, regtype, inclusive)
if not vim.api.nvim_buf_is_loaded(bufnr) then
vim.fn.bufload(bufnr)
end
-- check that region falls within current buffer
local buf_line_count = vim.api.nvim_buf_line_count(bufnr)
pos1[1] = math.min(pos1[1], buf_line_count - 1)
pos2[1] = math.min(pos2[1], buf_line_count - 1)
-- in case of block selection, columns need to be adjusted for non-ASCII characters
-- TODO: handle double-width characters
local bufline
if regtype:byte() == 22 then
bufline = vim.api.nvim_buf_get_lines(bufnr, pos1[1], pos1[1] + 1, true)[1]
pos1[2] = vim.str_utfindex(bufline, pos1[2])
end
local region = {}
for l = pos1[1], pos2[1] do
local c1, c2
if regtype:byte() == 22 then -- block selection: take width from regtype
c1 = pos1[2]
c2 = c1 + regtype:sub(2)
-- and adjust for non-ASCII characters
bufline = vim.api.nvim_buf_get_lines(bufnr, l, l + 1, true)[1]
if c1 < #bufline then
c1 = vim.str_byteindex(bufline, c1)
end
if c2 < #bufline then
c2 = vim.str_byteindex(bufline, c2)
end
else
c1 = (l == pos1[1]) and (pos1[2]) or 0
c2 = (l == pos2[1]) and (pos2[2] + (inclusive and 1 or 0)) or -1
end
table.insert(region, l, {c1, c2})
end
return region
end
--- Defers calling `fn` until `timeout` ms passes.
---
--- Use to do a one-shot timer that calls `fn`
--- Note: The {fn} is |schedule_wrap|ped automatically, so API functions are
--- safe to call.
---@param fn Callback to call once `timeout` expires
---@param timeout Number of milliseconds to wait before calling `fn`
---@return timer luv timer object
function vim.defer_fn(fn, timeout)
vim.validate { fn = { fn, 'c', true}; }
local timer = vim.loop.new_timer()
timer:start(timeout, 0, vim.schedule_wrap(function()
timer:stop()
timer:close()
fn()
end))
return timer
end
--- Display a notification to the user.
---
--- This function can be overridden by plugins to display notifications using a
--- custom provider (such as the system notification provider). By default,
--- writes to |:messages|.
---
---@param msg string Content of the notification to show to the user.
---@param level number|nil One of the values from |vim.log.levels|.
---@param opts table|nil Optional parameters. Unused by default.
function vim.notify(msg, level, opts) -- luacheck: no unused args
if level == vim.log.levels.ERROR then
vim.api.nvim_err_writeln(msg)
elseif level == vim.log.levels.WARN then
vim.api.nvim_echo({{msg, 'WarningMsg'}}, true, {})
else
vim.api.nvim_echo({{msg}}, true, {})
end
end
do
local notified = {}
--- Display a notification only one time.
---
--- Like |vim.notify()|, but subsequent calls with the same message will not
--- display a notification.
---
---@param msg string Content of the notification to show to the user.
---@param level number|nil One of the values from |vim.log.levels|.
---@param opts table|nil Optional parameters. Unused by default.
function vim.notify_once(msg, level, opts) -- luacheck: no unused args
if not notified[msg] then
vim.notify(msg, level, opts)
notified[msg] = true
end
end
end
---@private
function vim.register_keystroke_callback()
error('vim.register_keystroke_callback is deprecated, instead use: vim.on_key')
end
local on_key_cbs = {}
--- Adds Lua function {fn} with namespace id {ns_id} as a listener to every,
--- yes every, input key.
---
--- The Nvim command-line option |-w| is related but does not support callbacks
--- and cannot be toggled dynamically.
---
---@param fn function: Callback function. It should take one string argument.
--- On each key press, Nvim passes the key char to fn(). |i_CTRL-V|
--- If {fn} is nil, it removes the callback for the associated {ns_id}
---@param ns_id number? Namespace ID. If nil or 0, generates and returns a new
--- |nvim_create_namespace()| id.
---
---@return number Namespace id associated with {fn}. Or count of all callbacks
---if on_key() is called without arguments.
---
---@note {fn} will be removed if an error occurs while calling.
---@note {fn} will not be cleared by |nvim_buf_clear_namespace()|
---@note {fn} will receive the keys after mappings have been evaluated
function vim.on_key(fn, ns_id)
if fn == nil and ns_id == nil then
return #on_key_cbs
end
vim.validate {
fn = { fn, 'c', true},
ns_id = { ns_id, 'n', true }
}
if ns_id == nil or ns_id == 0 then
ns_id = vim.api.nvim_create_namespace('')
end
on_key_cbs[ns_id] = fn
return ns_id
end
--- Executes the on_key callbacks.
---@private
function vim._on_key(char)
local failed_ns_ids = {}
local failed_messages = {}
for k, v in pairs(on_key_cbs) do
local ok, err_msg = pcall(v, char)
if not ok then
vim.on_key(nil, k)
table.insert(failed_ns_ids, k)
table.insert(failed_messages, err_msg)
end
end
if failed_ns_ids[1] then
error(string.format(
"Error executing 'on_key' with ns_ids '%s'\n Messages: %s",
table.concat(failed_ns_ids, ", "),
table.concat(failed_messages, "\n")))
end
end
--- Generate a list of possible completions for the string.
--- String starts with ^ and then has the pattern.
---
--- 1. Can we get it to just return things in the global namespace with that name prefix
--- 2. Can we get it to return things from global namespace even with `print(` in front.
function vim._expand_pat(pat, env)
env = env or _G
pat = string.sub(pat, 2, #pat)
if pat == '' then
local result = vim.tbl_keys(env)
table.sort(result)
return result, 0
end
-- TODO: We can handle spaces in [] ONLY.
-- We should probably do that at some point, just for cooler completion.
-- TODO: We can suggest the variable names to go in []
-- This would be difficult as well.
-- Probably just need to do a smarter match than just `:match`
-- Get the last part of the pattern
local last_part = pat:match("[%w.:_%[%]'\"]+$")
if not last_part then return {}, 0 end
local parts, search_index = vim._expand_pat_get_parts(last_part)
local match_part = string.sub(last_part, search_index, #last_part)
local prefix_match_pat = string.sub(pat, 1, #pat - #match_part) or ''
local final_env = env
for _, part in ipairs(parts) do
if type(final_env) ~= 'table' then
return {}, 0
end
local key
-- Normally, we just have a string
-- Just attempt to get the string directly from the environment
if type(part) == "string" then
key = part
else
-- However, sometimes you want to use a variable, and complete on it
-- With this, you have the power.
-- MY_VAR = "api"
-- vim[MY_VAR]
-- -> _G[MY_VAR] -> "api"
local result_key = part[1]
if not result_key then
return {}, 0
end
local result = rawget(env, result_key)
if result == nil then
return {}, 0
end
key = result
end
local field = rawget(final_env, key)
if field == nil then
local mt = getmetatable(final_env)
if mt and type(mt.__index) == "table" then
field = rawget(mt.__index, key)
elseif final_env == vim and vim._submodules[key] then
field = vim[key]
end
end
final_env = field
if not final_env then
return {}, 0
end
end
local keys = {}
---@private
local function insert_keys(obj)
for k,_ in pairs(obj) do
if type(k) == "string" and string.sub(k,1,string.len(match_part)) == match_part then
table.insert(keys,k)
end
end
end
if type(final_env) == "table" then
insert_keys(final_env)
end
local mt = getmetatable(final_env)
if mt and type(mt.__index) == "table" then
insert_keys(mt.__index)
end
if final_env == vim then
insert_keys(vim._submodules)
end
table.sort(keys)
return keys, #prefix_match_pat
end
vim._expand_pat_get_parts = function(lua_string)
local parts = {}
local accumulator, search_index = '', 1
local in_brackets, bracket_end = false, -1
local string_char = nil
for idx = 1, #lua_string do
local s = lua_string:sub(idx, idx)
if not in_brackets and (s == "." or s == ":") then
table.insert(parts, accumulator)
accumulator = ''
search_index = idx + 1
elseif s == "[" then
in_brackets = true
table.insert(parts, accumulator)
accumulator = ''
search_index = idx + 1
elseif in_brackets then
if idx == bracket_end then
in_brackets = false
search_index = idx + 1
if string_char == "VAR" then
table.insert(parts, { accumulator })
accumulator = ''
string_char = nil
end
elseif not string_char then
bracket_end = string.find(lua_string, ']', idx, true)
if s == '"' or s == "'" then
string_char = s
elseif s ~= ' ' then
string_char = "VAR"
accumulator = s
end
elseif string_char then
if string_char ~= s then
accumulator = accumulator .. s
else
table.insert(parts, accumulator)
accumulator = ''
string_char = nil
end
end
else
accumulator = accumulator .. s
end
end
parts = vim.tbl_filter(function(val) return #val > 0 end, parts)
return parts, search_index
end
---Prints given arguments in human-readable format.
---Example:
---
--- -- Print highlight group Normal and store it's contents in a variable.
--- local hl_normal = vim.pretty_print(vim.api.nvim_get_hl_by_name("Normal", true))
---
---@see |vim.inspect()|
---@return given arguments.
function vim.pretty_print(...)
local objects = {}
for i = 1, select('#', ...) do
local v = select(i, ...)
table.insert(objects, vim.inspect(v))
end
print(table.concat(objects, ' '))
return ...
end
require('vim._meta')
return vim