vim

Waits up to time milliseconds, until callback returns true (success). Executes callback immediately, then on user events, internal events, and approximately every interval milliseconds (default 200). Returns true plus any remaining callback results on success.

Nvim processes other events while waiting. Cannot be called during an |api-fast| event.

Examples:

-- Wait for 100 ms, allowing other events to process.
vim.wait(100)

-- Wait up to 1000 ms or until `vim.g.foo` is true, at intervals of ~500 ms.
vim.wait(1000, function() return vim.g.foo end, 500)

-- Wait indefinitely until `vim.g.foo` is true, and get the callback results.
local ok, rv1, rv2, rv3 = vim.wait(math.huge, function()
  return vim.g.foo, 'a', 42, { ok = { 'yes' } }
end)

-- Schedule a function to set a value in 100ms. This would wait 10s if blocked, but actually
-- only waits 100ms because `vim.wait` processes other events while waiting.
vim.defer_fn(function() vim.g.timer_result = true end, 100)
if vim.wait(10000, function() return vim.g.timer_result end) then
  print('Only waiting a little bit of time!')
end

-- Yield via vim.wait() to allow CTRL-C to interrupt Lua code.
while true do
  -- ...work...
  local _, code = vim.wait(0, nil, 0)
  if code == -2 then -- CTRL-C.
    break
  end
end

Gets process info from the ps command. Used by nvimgetproc() as a fallback.

Gets process children from the pgrep command. Used by nvimgetproc_children() as a fallback.

Paste handler, invoked by |nvim_paste()|.

Note: This is provided only as a "hook", don't call it directly; call |nvim_paste()| instead, which arranges redo (dot-repeat) and invokes vim.paste.

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
    return overridden(lines, phase)
  end
end)(vim.paste)

Returns a function which calls {fn} via |vim.schedule()|.

The returned function passes all arguments to {fn}.

Example:

function notify_readable(_err, readable)
  vim.notify("readable? " .. tostring(readable))
end
vim.uv.fs_access(vim.fn.stdpath("config"), "R", vim.schedule_wrap(notify_readable))

Defers calling {fn} until {timeout} ms passes.

Use to do a one-shot timer that calls {fn}. Note: The {fn} is |schedule|d automatically, so API functions are safe to call.

Displays 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|.

Displays a notification only one time.

Like |vim.notify()|, but subsequent calls with the same message will not display a notification.

Registers function {fn} with [namespace] {ns_id} as a listener to every, yes EVERY, input key.

To parse [key-chord]s, see |vim.keycode()|. Example:

local keychords = vim.keycode(vim.fn.keytrans(key), true)

The |-w| command-line option is related but does not support callbacks and cannot be toggled dynamically.

Convert UTF-32, UTF-16 or UTF-8 {index} to byte index. If {strict_indexing} is false then an out of range index will return byte length instead of throwing an error.

Invalid UTF-8 and NUL is treated like in |vim.str_utfindex()|. An {index} in the middle of a UTF-16 sequence is rounded upwards to the end of that sequence.

Convert byte index to UTF-32, UTF-16 or UTF-8 indices. If {index} is not supplied, the length of the string is used. All indices are zero-based.

If {strict_indexing} is false then an out of range index will return string length instead of throwing an error. Invalid UTF-8 bytes, and embedded surrogates are counted as one code point each. An {index} in the middle of a UTF-8 sequence is rounded upwards to the end of that sequence.

Generates a list of possible completions for the str String 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.

Omnifunc for completing Lua values from the runtime Lua interpreter, similar to the builtin completion for the :lua command.

Activate using vim.bo.omnifunc = vim.lua_omnifunc in a Lua buffer.

"Pretty prints" the given arguments and returns them unmodified.

Example:

local hl_normal = vim.print(vim.api.nvim_get_hl(0, { name = 'Normal' }))

Converts keys from [key-notation] to the internal encoding. Optionally returns structured key-chord info as retval 2.

Inverse of [keytrans()], which converts the internal encoding back to [key-notation].

Examples:

local k = vim.keycode
vim.g.mapleader = k'<bs>'

-- Split a key sequence into chords, e.g. to inspect modifiers.
local _, chords = vim.keycode('<C-w>v', true)
assert(chords[1].key == 'w' and chords[1].mod[1] == 'C')

-- keytrans() is the inverse: internal encoding => key-notation.
assert(vim.fn.keytrans(vim.keycode('<C-a>')) == '<C-A>')

Shows a deprecation message to the user.

Returns a deep copy of the given object. Non-table objects are copied as in a typical Lua assignment, whereas table objects are copied recursively. Functions are naively copied, so functions in the copied table point to the same functions as those in the input table. Userdata and threads are not copied and will throw an error.

Note: noref=true is much more performant on tables with unique table fields, while noref=false is more performant on tables that reuse table fields.

Returns a shallow copy of orig.

Non-table values are returned as-is. Table keys and values are copied by reference, and the original metatable is preserved. Use |vim.deepcopy()| for a recursive copy.

Gets an |iterator| that splits a string at each instance of a separator, in "lazy" fashion (as opposed to |vim.split()| which is "eager").

Example:

for s in vim.gsplit(':aa::b:', ':', {plain=true}) do
  print(s)
end

If you want to also inspect the separator itself (instead of discarding it), use |string.gmatch()|. Example:

for word, num in ('foo111bar222'):gmatch('([^0-9]*)(%d*)') do
  print(('word: %s num: %s'):format(word, num))
end

Splits a string at each instance of a separator and returns the result as a table (unlike |vim.gsplit()|).

Examples:

split(":aa::b:", ":")                   --> {'','aa','','b',''}
split("axaby", "ab?")                   --> {'','x','y'}
split("x*yz*o", "*", {plain=true})      --> {'x','yz','o'}
split("|x|y|z|", "|", {trimempty=true}) --> {'x', 'y', 'z'}

Return a list of all keys used in a table. However, the order of the return table of keys is not guaranteed.

Return a list of all values used in a table. However, the order of the return table of values is not guaranteed.

Applies function fn to all values of table t, in pairs() iteration order (which is not guaranteed to be stable, even when the data doesn't change).

Filter a table using a predicate function

Checks if a table contains a given value, specified either directly or via a predicate that is checked for each value.

Example:

vim.tbl_contains({ 'a', { 'b', 'c' } }, function(v)
  return vim.deep_equal(v, { 'b', 'c' })
end, { predicate = true })
-- true

Checks if a list-like table (integer keys without gaps) contains value.

Checks if a table is empty.

Merges two or more tables.

Merges two or more tables recursively.

Only |lua-dict| tables are merged recursively; |lua-list| tables are treated as opaque values (overwritten instead of merged). That is convenient for merging default/user configurations where lists typically should not be merged together.

Example:

-- Set `config.settings.…` without worrying about whether intermediate dicts exist.
local config = { settings = { tailwindCSS = { foo = 'bar' } } }
local merged = vim.tbl_deep_extend('force',
  config,
  { settings = { tailwindCSS = { experimental = { configFile = '/my/config.json' } } } }
)
vim.print(merged)

Deep compare values for equality

Tables are compared recursively unless they both provide the eq metamethod. All other types are compared using the equality == operator. Cyclic tables are supported.

Gets a (nested) value from table o given by a sequence of keys ..., or nil if not found.

Note: To set deeply nested keys, see |vim.tbldeepextend()|.

Example:

local o = { a = { b = true } }
-- Get `o.a.b`.
vim.print(vim.tbl_get(o, 'a', 'b')) -- true
o.a = {}
vim.print(vim.tbl_get(o, 'a', 'b')) -- nil

Extends a list-like table with the values of another list-like table.

NOTE: This mutates dst!

Enumerates key-value pairs of a table, ordered by key.

Tests if t is an "array": a table indexed only by integers (potentially non-contiguous).

If the indexes start from 1 and are contiguous then the array is also a list. |vim.islist()|

Empty table {} is an array, unless it was created by |vim.empty_dict()| or returned as a dict-like |API| or Vimscript result, for example from |rpcrequest()| or |vim.fn|.

Tests if t is a "list": a table indexed only by contiguous integers starting from 1 (what |lua-length| calls a "regular array").

Empty table {} is a list, unless it was created by |vim.empty_dict()| or returned as a dict-like |API| or Vimscript result, for example from |rpcrequest()| or |vim.fn|.

Tests if t is nil or |vim.NIL|.

Counts the number of non-nil values in table t.

vim.tbl_count({ a=1, b=2 })  --> 2
vim.tbl_count({ 1, 2 })      --> 2

Creates a copy of a table containing only elements from start to end (inclusive)

Efficiently insert items into the middle of a list.

Calling table.insert() in a loop will re-index the tail of the table on every iteration, instead this function will re-index the table exactly once.

Based on https://stackoverflow.com/questions/12394841/safely-remove-items-from-an-array-table-while-iterating/53038524#53038524

Efficiently remove items from middle of a list.

Calling table.remove() in a loop will re-index the tail of the table on every iteration, instead this function will re-index the table exactly once.

Based on https://stackoverflow.com/questions/12394841/safely-remove-items-from-an-array-table-while-iterating/53038524#53038524

Trim whitespace (Lua pattern "%s") from both sides of a string.

Escapes magic chars in |lua-pattern|s.

Tests if s starts with prefix.

Tests if s ends with suffix.

Validate function arguments.

This function has two valid forms:

1. vim.validate(name, value, validator[, optional][, message])

Validates that argument {name} with value {value} satisfies {validator}. If {optional} is given and is true, then {value} may be nil. If {message} is given, then it is used as the expected type in the error message.

Example:

      function vim.startswith(s, prefix)
        vim.validate('s', s, 'string')
        vim.validate('prefix', prefix, 'string')
        -- ...
      end

1. vim.validate(spec) (DEPRECATED) where spec is of type

table<string,[value:any, validator: vim.validate.Validator, optional_or_msg? : boolean|string]>)

Validates a argument specification. Specs are evaluated in alphanumeric order, until the first failure.

Examples:

vim.validate('arg1', {'foo'}, 'table')
   --> NOP (success)
vim.validate('arg2', 'foo', 'string')
   --> NOP (success)

vim.validate('arg1', 1, 'table')
   --> error('arg1: expected table, got number')

vim.validate('arg1', 3, function(a) return (a % 2) == 0 end, 'even number')
   --> error('arg1: expected even number, got 3')

-- If multiple types are valid they can be given as a list:
vim.validate('arg1', {'foo'}, {'table', 'string'})
vim.validate('arg2', 'foo', {'table', 'string'})
-- NOP (success)
vim.validate('arg1', 1, {'string', 'table'})
-- error('arg1: expected string|table, got number')

Returns true if object f can be called as a function.

Creates a table whose missing keys are provided by {createfn} (like Python's "defaultdict").

If {createfn} is nil it defaults to defaulttable() itself, so accessing nested keys creates nested tables:

local a = vim.defaulttable()
a.b.c = 1

Create a ring buffer limited to a maximal number of items. Once the buffer is full, adding a new entry overrides the oldest entry.

local ringbuf = vim.ringbuf(4)
ringbuf:push("a")
ringbuf:push("b")
ringbuf:push("c")
ringbuf:push("d")
ringbuf:push("e")    -- overrides "a"
print(ringbuf:pop()) -- returns "b"
print(ringbuf:pop()) -- returns "c"

-- Can be used as iterator. Pops remaining items:
for val in ringbuf do
  print(val)
end

Returns a Ringbuf instance with the following methods:

• |Ringbuf:push()|
• |Ringbuf:pop()|
• |Ringbuf:peek()|
• |Ringbuf:clear()|

Creates a module alias/shim that lazy-loads a target module.

Unlike vim.defaulttable() this also:

• implements __call
• calls vim.deprecate()

Executes function f with the given context spec: after execution, the original state indicated by the spec is restored.

Notes:

• Context { buf = buf } has no guarantees about current window when

inside context.

• Context { buf = buf, win = win } is yet not allowed, but this seems

to be an implementation detail.

• There should be no way to revert currently set context.sandbox = true

(like with nested vim._with() calls). Otherwise it kind of breaks the whole purpose of sandbox execution.

• Saving and restoring option contexts (bo, go, o, wo) trigger

OptionSet events. This is an implementation issue because not doing it seems to mean using either 'eventignore' option or extra nesting with { noautocmd = true } (which itself is a wrapper for 'eventignore'). As { go = { eventignore = '...' } } is a valid context which should be properly set and restored, this is not a good approach. Not triggering OptionSet seems to be a good idea, though. So probably only moving context save and restore to lower level might resolve this.

Coerces {x} to an integer, like tonumber(), but rejects fractional values.

Returns nil if {x} cannot be converted with tonumber(), or if the resulting number is not integral.

Coerces {x} to an integer and errors if conversion fails.

This is the throwing counterpart to |vim._tointeger()| and should be used when non-integer input is a programming error.

Returns the first argument which is not nil.

If all arguments are nil, returns nil.

Example:

local a = nil
local b = nil
local c = 42
local d = true
assert(vim.nonnil(a, b, c, d) == 42)

Calls the function fn in protected mode like |pcall()|, but returns nil on error.

Runs a system command or throws an error if {cmd} cannot be run.

The command runs directly (not in 'shell') so shell builtins such as "echo" in cmd.exe, cmdlets in powershell, or "help" in bash, will not work unless you actually invoke a shell: vim.system({'bash', '-c', 'help'}).

Examples:

local on_exit = function(obj)
  print(obj.code)
  print(obj.signal)
  print(obj.stdout)
  print(obj.stderr)
end

-- Runs asynchronously:
vim.system({'echo', 'hello'}, { text = true }, on_exit)

-- Runs synchronously:
local obj = vim.system({'echo', 'hello'}, { text = true }):wait()
-- { code = 0, signal = 0, stdout = 'hello\n', stderr = '' }

See |uv.spawn()| for more details. Note: unlike |uv.spawn()|, vim.system throws an error if {cmd} cannot be run.

<Docs described in |vim.empty_dict()| >

Get all the items at a given buffer position.

Can also be pretty-printed with :Inspect!. :Inspect!

Show all the items at a given buffer position.

Can also be shown with :Inspect. :Inspect

See also |:marks| to list all extmarks.

Example: To bind this function to the vim-scriptease inspired zS in Normal mode:

vim.keymap.set('n', 'zS', vim.show_pos)

Returns true if the code is executing as part of a "fast" event handler, where most of the API is disabled. These are low-level events (e.g. |lua-loop-callbacks|) which can be invoked whenever Nvim polls for input. When this is false most API functions are callable (but may be subject to other restrictions such as |textlock|).

Creates a special empty table (marked with a metatable), which Nvim converts to an empty dictionary when translating Lua values to Vimscript or API types. Nvim by default converts an empty table {} without this metatable to an list/array.

Note: If numeric keys are present in the table, Nvim ignores the metatable marker and converts the dict to a list/array anyway.

Sends {event} to {channel} via |RPC| and returns immediately. If {channel} is 0, the event is broadcast to all channels.

This function also works in a fast callback |lua-loop-callbacks|.

Invokes |RPC| method on channel and blocks until a response is received.

Note: Msgpack NIL values in the response are represented as |vim.NIL|.

Example: see [nvimexeclua()]

Compares strings case-insensitively.

Gets a list of the starting byte positions of each UTF-8 codepoint in the given string.

Embedded NUL bytes are treated as terminating the string.

Gets the distance (in bytes) from the starting byte of the codepoint (character) that {index} points to.

The result can be added to {index} to get the starting byte of a character.

Examples:

-- The character 'æ' is stored as the bytes '\xc3\xa6' (using UTF-8)

-- Returns 0 because the index is pointing at the first byte of a character
vim.str_utf_start('æ', 1)

-- Returns -1 because the index is pointing at the second byte of a character
vim.str_utf_start('æ', 2)

Gets the distance (in bytes) from the last byte of the codepoint (character) that {index} points to.

Examples:

-- The character 'æ' is stored as the bytes '\xc3\xa6' (using UTF-8)

-- Returns 0 because the index is pointing at the last byte of a character
vim.str_utf_end('æ', 2)

-- Returns 1 because the index is pointing at the penultimate byte of a character
vim.str_utf_end('æ', 1)

The result is a String, which is the text {str} converted from encoding {from} to encoding {to}. When the conversion fails nil is returned. When some characters could not be converted they are replaced with "?". The encoding names are whatever the iconv() library function can accept, see ":Man 3 iconv".

Schedules {fn} to be invoked soon by the main event-loop. Useful to avoid |textlock| or other temporary restrictions.

Subscribe to |ui-events|, similar to |nvimuiattach()| but receive events in a Lua callback. Used to implement screen elements like popupmenu or message handling in Lua.

{callback} receives event name plus additional parameters. See |ui-popupmenu| and the sections below for event format for respective events.

Callbacks for msg_show events originating from internal messages (as opposed to events from commands or API calls) are executed in |api-fast| context; showing the message needs to be scheduled.

Excessive errors inside the callback will result in forced detachment.

WARNING: This api is considered experimental. Usability will vary for different screen elements. In particular ext_messages behavior is subject to further changes and usability improvements. This is expected to be used to handle messages when setting 'cmdheight' to zero (which is likewise experimental).

Example (stub for a |ui-popupmenu| implementation):

ns = vim.api.nvim_create_namespace('my_fancy_pum')

vim.ui_attach(ns, {ext_popupmenu=true}, function(event, ...)
  if event == 'popupmenu_show' then
    local items, selected, row, col, grid = ...
    print('display pum ', #items)
  elseif event == 'popupmenu_select' then
    local selected = ...
    print('selected', selected)
  elseif event == 'popupmenu_hide' then
    print('FIN')
  end
end)

Detach a callback previously attached with |vim.ui_attach()| for the given namespace {ns}.

Invokes |vim-function| or |user-function| {func} with arguments {...}. See also |vim.fn|. Equivalent to:

vim.fn[func]({...})

Parses the Vim regex re and returns a regex object. Regexes are "magic" and case-sensitive by default, regardless of 'magic' and 'ignorecase'. They can be controlled with flags, see |/magic| and |/ignorecase|.

There are things which have special rules in vim.initpackages for legacy reasons (uri) or for performance (_inspector). most new things should go into a submodule namespace ( vim.foobar.do_thing() )

Gets a human-readable representation of the given object.

vim.fn.{func}(...)

Executes Vimscript (|Ex-command|s).

Can be indexed with a command name to get a function, thus you can write vim.cmd.echo(…) instead of vim.cmd{cmd='echo',…}.

Examples:

-- Single command:
vim.cmd('echo 42')
-- Multiline script:
vim.cmd([[
  augroup my.group
    autocmd!
    autocmd FileType c setlocal cindent
  augroup END
]])

-- Ex command :echo "foo". Note: string literals must be double-quoted.
vim.cmd('echo "foo"')
vim.cmd { cmd = 'echo', args = { '"foo"' } }
vim.cmd.echo({ args = { '"foo"' } })
vim.cmd.echo('"foo"')

-- Ex command :write! myfile.txt
vim.cmd('write! myfile.txt')
vim.cmd { cmd = 'write', args = { 'myfile.txt' }, bang = true }
vim.cmd.write { args = { 'myfile.txt' }, bang = true }
vim.cmd.write { 'myfile.txt', bang = true }

-- Ex command :vertical resize +2
vim.cmd.resize({ '+2', mods = { vertical = true } })

-- Pass arg literally, without needing to escape special chars:
vim.cmd.edit({ '%foo"|bar#baz"', magic = { file = false, bar = false } })

Deprecated. Remove at Nvim 2.0

Gets or sets environment variables in the current editor process. See |expand-env| and |:let-environment| for the Vimscript behavior. Invalid or unset key returns nil.

Example:

vim.env.FOO = 'bar'
print(vim.env.TERM)

Gets or sets |options|. Works like :set, so buffer/window-scoped options target the current buffer/window. Invalid key is an error.

Example:

vim.o.cmdheight = 4
print(vim.o.columns)
print(vim.o.foo)     -- error: invalid key

Gets or sets global |options|. Like :setglobal. Invalid key is an error.

Note: unlike |vim.o|, this accesses the global option value and thus is mostly useful with |global-local| options.

Example:

vim.go.cmdheight = 4
print(vim.go.columns)
print(vim.go.bar)     -- error: invalid key

Gets or sets buffer-scoped |options| on buffer {bufnr} (or "current buffer" if 0 or omitted). Like :setlocal. Invalid {bufnr} or key is an error.

Example:

local bufnr = vim.api.nvim_get_current_buf()
vim.bo[bufnr].buflisted = true    -- same as vim.bo.buflisted = true
print(vim.bo.comments)
print(vim.bo.baz)                 -- error: invalid key

Gets or sets window-scoped |options| on window {winid} (or "current window" if 0 or omitted) and buffer {bufnr} (0 for current buffer). Like :setlocal if setting a |global-local| option or if {bufnr} is specified, like :set otherwise. Invalid {winid}, {bufnr}, or key is an error.

Note: only bufnr=0 (current window-buffer) is supported, currently.

Example:

local winid = vim.api.nvim_get_current_win()
vim.wo[winid].number = true    -- same as vim.wo.number = true
print(vim.wo.foldmarker)
print(vim.wo.quux)             -- error: invalid key
vim.wo[winid][0].spell = false -- like ':setlocal nospell'

Use max 32-bit signed int value to avoid overflow on 32-bit systems. #31633

require('vim.iter') carries the richer EmmyLua generic surface. Force LuaLS onto the fallback module shape above so make luals stays clean.