Lua engine lua Lua

INTRODUCTION lua-intro

:lua vim.print(package.loaded)

nvim -l foo.lua [args...]

if jit then
  -- code for luajit
else
  -- code for plain lua 5.1
end

-- Start a profiling session:
require('jit.p').start('ri1', '/tmp/profile')

-- Perform arbitrary tasks (use plugins, scripts, etc.) ...

-- Stop the session. Profile is written to /tmp/profile.
require('jit.p').stop()

:lua vim.cmd.edit(package.searchpath('jit.p', package.path))

LUA CONCEPTS AND IDIOMS lua-concepts

---@return any|nil    # result on success, nil on failure.
---@return nil|string # nil on success, error message on failure.

local value = assert(fn())

local foo = function(a, b)
    print("A: ", a)
    print("B: ", b)
end

foo(1, 2)
-- ==== Result ====
-- A: 1
-- B: 2

foo(1)
-- ==== Result ====
-- A: 1
-- B: nil

local func_with_opts = function(opts)
    local will_do_foo = opts.foo
    local filename = opts.filename
    -- ...
end

func_with_opts { foo = true, filename = "hello.world" }

print(string.match("foo123bar123", "%d+"))
-- 123
print(string.match("foo123bar123", "[^%d]+"))
-- foo
print(string.match("foo123bar123", "[abc]+"))
-- ba
print(string.match("foo.bar", "%.bar"))
-- .bar

IMPORTING LUA MODULES lua-module-load

:echo nvim_list_runtime_paths()

foo/lua/mod.lua
foo/lua/mod/init.lua
bar/lua/mod.lua
bar/lua/mod/init.lua
foo/lua/mod.so
foo/lua/mod.dll
bar/lua/mod.so
bar/lua/mod.dll

debug.getinfo(1, 'S').source:gsub('^@', '')

COMMANDS lua-commands

:lua vim.api.nvim_command('echo "Hello, Nvim!"')

:lua print(_VERSION)

:lua =jit.version

print(string.format(
    'unix time: %s', os.time()))

function! CurrentLineInfo()
lua << EOF
local linenr = vim.api.nvim_win_get_cursor(0)[1]
local curline = vim.api.nvim_buf_get_lines(0, linenr - 1, linenr, false)[1]
print(string.format('Line [%d] has %d bytes', linenr, #curline))
EOF
endfunction

:luado return string.format("%s\t%d", line:reverse(), #line)

:lua require"lpeg"
:lua -- balanced parenthesis grammar:
:lua bp = lpeg.P{ "(" * ((1 - lpeg.S"()") + lpeg.V(1))^0 * ")" }
:luado if bp:match(line) then return "=>\t" .. line end

:luafile script.lua
:luafile %

luaeval() lua-eval

local chunkheader = "local _A = select(1, ...) return "
function luaeval (expstr, arg)
    local chunk = assert(loadstring(chunkheader .. expstr, "luaeval"))
    return chunk(arg) -- return typval
end

:echo luaeval('_A[1] + _A[2]', [40, 2])
" 42
:echo luaeval('string.match(_A, "[a-z]+")', 'XYXfoo123')
" foo

:echo luaeval('math.pi')
:function Rand(x,y) " random uniform between x and y
:  return luaeval('(_A.y-_A.x)*math.random()+_A.x', {'x':a:x,'y':a:y})
:  endfunction
:echo Rand(1,10)

Vimscript v:lua interface v:lua-call

call v:lua.func(arg1, arg2)

return func(...)

call v:lua.somemod.func(args)

return somemod.func(...)

call v:lua.require'mypack'.func(arg1, arg2)
call v:lua.require'mypack.submod'.func(arg1, arg2)

function mymod.omnifunc(findstart, base)
  if findstart == 1 then
    return 0
  else
    return {'stuff', 'steam', 'strange things'}
  end
end
-- Note: The module ("mymod") must be a Lua global, or use require() as
-- shown above to access it from a package.
vim.bo[buf].omnifunc = 'v:lua.mymod.omnifunc'

:eval arg1->v:lua.somemod.func(arg2)

let g:Myvar = v:lua.myfunc        " Error
call SomeFunc(v:lua.mycallback)   " Error
let g:foo = v:lua                 " Error
let g:foo = v:['lua']             " Error

Lua standard modules lua-stdlib

:lua vim.print(vim)

{
  _os_proc_children = <function 1>,
  _os_proc_info = <function 2>,
  ...
  api = {
    nvim__id = <function 5>,
    nvim__id_array = <function 6>,
    ...
  },
  deepcopy = <function 106>,
  gsplit = <function 107>,
  ...
}

:help vim.deepcopy()

VIM.UV lua-loop vim.uv

local timer = vim.uv.new_timer()
timer:start(1000, 0, function()
  vim.api.nvim_command('echomsg "test"')
end)

local timer = vim.uv.new_timer()
timer:start(1000, 0, vim.schedule_wrap(function()
  vim.api.nvim_command('echomsg "test"')
end))

sysctl fs.inotify.max_user_watches=494462

VIM vim.builtin

print(tostring(vim.api.nvim_get_current_line()))

{
  [vim.type_idx] = vim.types.float,
  [vim.val_idx] = 1.0,
}

-- 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 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)

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)

LUA-VIMSCRIPT BRIDGE lua-vimscript

local list = { 1, 2, 3 }
vim.fn.remove(list, 0)
vim.print(list)  --> "{ 1, 2, 3 }"

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

vim.fn['some#function']({...})

vim.g.foo = 5     -- Set the g:foo Vimscript variable.
print(vim.g.foo)  -- Get and print the g:foo Vimscript variable.
vim.g.foo = nil   -- Delete (:unlet) the Vimscript variable.
vim.b[2].foo = 6  -- Set b:foo for buffer 2

vim.g.my_dict.field1 = 'value'  -- Does not work

local my_dict = vim.g.my_dict   --
my_dict.field1 = 'value'        -- Instead do
vim.g.my_dict = my_dict         --

set wildignore=*.o,*.a,__pycache__

vim.o.wildignore = '*.o,*.a,__pycache__'

vim.opt.wildignore = { '*.o', '*.a', '__pycache__' }

vim.opt.wildignore:append { "*.pyc", "node_modules" }

vim.opt.wildignore:prepend { "new_first_value" }

vim.opt.wildignore:remove { "node_modules" }

set listchars=space:_,tab:>~

vim.o.listchars = 'space:_,tab:>~'

vim.opt.listchars = { space = '_', tab = '>~' }

echo wildignore

print(vim.o.wildignore)

vim.print(vim.opt.wildignore:get())

vim.opt.formatoptions:append('j')
vim.opt.formatoptions = vim.opt.formatoptions + 'j'

vim.cmd [[set wildignore=*.pyc,*.o]]

vim.print(vim.opt.wildignore:get())
-- { "*.pyc", "*.o", }

for _, ignore_pattern in ipairs(vim.opt.wildignore:get()) do
    print("Will ignore:", ignore_pattern)
end
-- Will ignore: *.pyc
-- Will ignore: *.o

vim.cmd [[set listchars=space:_,tab:>~]]

vim.print(vim.opt.listchars:get())
--  { space = "_", tab = ">~", }

for char, representation in pairs(vim.opt.listchars:get()) do
    print(char, "=>", representation)
end

vim.cmd [[set formatoptions=njtcroql]]

vim.print(vim.opt.formatoptions:get())
-- { n = true, j = true, c = true, ... }

local format_opts = vim.opt.formatoptions:get()
if format_opts.j then
    print("J is enabled!")
end

vim.opt.wildignore:prepend('*.o')
vim.opt.wildignore = vim.opt.wildignore ^ '*.o'

vim.opt.wildignore:remove('*.pyc')
vim.opt.wildignore = vim.opt.wildignore - '*.pyc'

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

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

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

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

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'

Lua module: vim lua-vim

-- 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 } })

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

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

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

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>')

local t = { 1, 2, 2, 3, 3, 3 }
local first = vim.list.bisect(t, 3)
-- `first` is `val`'s first index if found,
-- useful for existence checks.
print(t[first]) -- 3

local last = vim.list.bisect(t, 3, { bound = 'upper' })
-- Note that `last` is 7, not 6,
-- this is suitable for insertion.

table.insert(t, last, 4)
-- t is now { 1, 2, 2, 3, 3, 3, 4 }

-- You can use lower bound and upper bound together
-- to obtain the range of occurrences of `val`.

-- 3 is in [first, last)
for i = first, last - 1 do
  print(t[i]) -- { 3, 3, 3 }
end

local t = {1, 2, 2, 3, 1}
vim.list.unique(t)
-- t is now {1, 2, 3}

local t = { {id=1}, {id=2}, {id=1} }
vim.list.unique(t, 'id')
-- t is now { {id=1}, {id=2} }

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

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

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)

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

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

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))

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'}

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

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

-- 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)

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

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')

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

Lua module: vim.inspector vim.inspector

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

Lua module: vim.base64 vim.base64

Lua module: vim.filetype vim.filetype

vim.filetype.add({
  extension = {
    foo = 'fooscript',
    bar = function(path, bufnr)
      if some_condition() then
        return 'barscript', function(bufnr)
          -- Set a buffer variable
          vim.b[bufnr].barscript_version = 2
        end
      end
      return 'bar'
    end,
  },
  filename = {
    ['.foorc'] = 'toml',
    ['/etc/foo/config'] = 'toml',
  },
  pattern = {
    ['.*/etc/foo/.*'] = 'fooscript',
    -- Using an optional priority
    ['.*/etc/foo/.*%.conf'] = { 'dosini', { priority = 10 } },
    -- A pattern containing an environment variable
    ['${XDG_CONFIG_HOME}/foo/git'] = 'git',
    ['.*README.(%a+)'] = function(path, bufnr, ext)
      if ext == 'md' then
        return 'markdown'
      elseif ext == 'rst' then
        return 'rst'
      end
    end,
  },
})

vim.filetype.add {
  pattern = {
    ['.*'] = {
      function(path, bufnr)
        local content = vim.api.nvim_buf_get_lines(bufnr, 0, 1, false)[1] or ''
        if vim.regex([[^#!.*\\<mine\\>]]):match_str(content) ~= nil then
          return 'mine'
        elseif vim.regex([[\\<drawing\\>]]):match_str(content) ~= nil then
          return 'drawing'
        end
      end,
      { priority = -math.huge },
    },
  },
}

vim.filetype.get_option('vim', 'commentstring')

-- Using a buffer number
vim.filetype.match({ buf = 42 })

-- Override the filename of the given buffer
vim.filetype.match({ buf = 42, filename = 'foo.c' })

-- Using a filename without a buffer
vim.filetype.match({ filename = 'main.lua' })

-- Using file contents
vim.filetype.match({ contents = {'#!/usr/bin/env bash'} })

Lua module: vim.fs vim.fs

vim.fn.filecopy('foo.txt', 'bar.txt')

if vim.uv.fs_stat(file) then
  vim.print('file exists')
end

vim.print(vim.fn.readblob('.git/config'))

vim.fn.writefile('foo\0bar', 'data.bin', 'b')

for name, type, err in vim.fs.dir(path, { err = true }) do
  if err then
    -- Failed to scan directory {name} (may be the root {path} itself).
  end
end

vim.fs.ext('archive.tar.gz') -- 'gz'
vim.fs.ext('~/.git') -- ''
vim.fs.ext('plugin/myplug.lua') -- 'lua'

-- List all test directories under the runtime directory.
local dirs = vim.fs.find(
  { 'test', 'tst', 'testdir' },
  { limit = math.huge, type = 'directory', path = './runtime/' }
)

-- Get all "lib/*.cpp" and "lib/*.hpp" files, using Lua patterns.
-- Or use `vim.glob.to_lpeg(…):match(…)` for glob/wildcard matching.
local files = vim.fs.find(function(name, path)
  return name:match('.*%.[ch]pp$') and path:match('[/\\]lib$')
end, { limit = math.huge, type = 'file' })

[[C:\Users\jdoe]]                         --> "C:/Users/jdoe"
"~/src/neovim"                            --> "/home/jdoe/src/neovim"
"$XDG_CONFIG_HOME/nvim/init.vim"          --> "/Users/jdoe/.config/nvim/init.vim"
"~/src/nvim/api/../tui/./tui.c"           --> "/home/jdoe/src/nvim/tui/tui.c"
"./foo/bar"                               --> "foo/bar"
"foo/../../../bar"                        --> "../../bar"
"/home/jdoe/../../../bar"                 --> "/bar"
"C:foo/../../baz"                         --> "C:../baz"
"C:/foo/../../baz"                        --> "C:/baz"
[[\\?\UNC\server\share\foo\..\..\..\bar]] --> "//?/UNC/server/share/bar"

local root_dir
for dir in vim.fs.parents(vim.api.nvim_buf_get_name(0)) do
  if vim.fn.isdirectory(dir .. '/.git') == 1 then
    root_dir = dir
    break
  end
end

if root_dir then
  print('Found git repository at', root_dir)
end

vim.fs.relpath('/var', '/var/lib') -- 'lib'
vim.fs.relpath('/var', '/usr/bin') -- nil

vim.fs.rm(vim.uv.fs_realpath('symlink-dir'), { recursive = true })

-- Find the root of a Python project, starting from file 'main.py'
vim.fs.root(vim.fs.joinpath(vim.env.PWD, 'main.py'), {'pyproject.toml', 'setup.py' })

-- Find the root of a git repository
vim.fs.root(0, '.git')

-- Find the parent directory containing any file with a .csproj extension
vim.fs.root(0, function(name, path)
  return vim.fs.ext(name) == 'csproj'
end)

-- Find the first ancestor directory containing EITHER "stylua.toml" or ".luarc.json"; if
-- not found, find the first ancestor containing ".git":
vim.fs.root(0, { { 'stylua.toml', '.luarc.json' }, '.git' })

vim.print(vim.fs.slug('/tmp/test/foo.md'))           --> "tmp-test-foo.md-{hash}"
vim.print(vim.fs.slug('C:/src/project/main.c'))      --> "C--src-project-main.c-{hash}"
vim.print(vim.fs.slug(vim.fn.expand('~/file.txt')))  --> "~-file.txt-{hash}"
vim.print(vim.fs.slug('---'))                        --> "=special-{hash}"
vim.print(vim.fs.slug('term://foo/bar//123:bash'))   --> "=uri-term-foo-bar-123-bash-{hash}"
vim.print(vim.fs.slug(('/a/very/long/path'):rep(10) .. '/file.txt', { maxlen = 60 }))
   --> "a-very-long-~~~-path-a-very-long-path-file.txt-{hash}"

Lua module: vim.glob vim.glob

Lua module: vim.hl vim.hl

autocmd TextYankPost * silent! lua vim.hl.hl_op {higroup='Visual', timeout=300}
autocmd TextPutPost  * silent! lua vim.hl.hl_op {higroup='Visual', timeout=300}

Lua module: vim.iter vim.iter

local it = vim.iter({ 1, 2, 3, 4, 5 })
it:map(function(v)
  return v * 3
end)
it:rev()
it:skip(2)
it:totable()
-- { 9, 6, 3 }

-- ipairs() is a function iterator which returns both the index (i) and the value (v)
vim.iter(ipairs({ 1, 2, 3, 4, 5 })):map(function(i, v)
  if i > 2 then return v end
end):totable()
-- { 3, 4, 5 }

local it = vim.iter(vim.gsplit('1,2,3,4,5', ','))
it:map(function(s) return tonumber(s) end)
for i, d in it:enumerate() do
  print(string.format("Column %d is %d", i, d))
end
-- Column 1 is 1
-- Column 2 is 2
-- Column 3 is 3
-- Column 4 is 4
-- Column 5 is 5

vim.iter({ a = 1, b = 2, c = 3, z = 26 }):any(function(k, v)
  return k == 'z'
end)
-- true

local rb = vim.ringbuf(3)
rb:push("a")
rb:push("b")
vim.iter(rb):totable()
-- { "a", "b" }

vim.iter(ipairs(t))

vim.iter(t):enumerate()

local it = vim.iter(vim.gsplit('abc', '')):enumerate()
it:next()
-- 1	'a'
it:next()
-- 2	'b'
it:next()
-- 3	'c'

local bufs = vim.iter(vim.api.nvim_list_bufs()):filter(vim.api.nvim_buf_is_loaded)

local it = vim.iter({ 3, 6, 9, 12 })
it:find(12)
-- 12

local it = vim.iter({ 3, 6, 9, 12 })
it:find(20)
-- nil

local it = vim.iter({ 3, 6, 9, 12 })
it:find(function(v) return v % 4 == 0 end)
-- 12

-- Create a new table with only even values
vim.iter({ a = 1, b = 2, c = 3, d = 4 })
  :filter(function(k, v) return v % 2 == 0 end)
  :fold({}, function(acc, k, v)
    acc[k] = v
    return acc
  end) --> { b = 2, d = 4 }

-- Get the "maximum" item of an iterable.
vim.iter({ -99, -4, 3, 42, 0, 0, 7 })
  :fold({}, function(acc, v)
    acc.max = math.max(v, acc.max or v)
    return acc
  end) --> { max = 42 }

local it = vim.iter(vim.gsplit('abcdefg', ''))
it:last()
-- 'g'

local it = vim.iter({ 3, 6, 9, 12, 15 })
it:last()
-- 15

local it = vim.iter({ 1, 2, 3, 4 }):map(function(v)
  if v % 2 == 0 then
    return v * 3
  end
end)
it:totable()
-- { 6, 12 }

local it = vim.iter(string.gmatch('1 2 3', '%d+')):map(tonumber)
it:next()
-- 1
it:next()
-- 2
it:next()
-- 3

local it = vim.iter({ 3, 6, 9, 12 })
it:nth(2)
-- 6
it:nth(2)
-- 12

local it2 = vim.iter({ 3, 6, 9, 12 })
it2:nth(-2)
-- 9
it2:nth(-2)
-- 3

local it = vim.iter({ 3, 6, 9, 12 })
it:peek()
-- 3
it:peek()
-- 3
it:next()
-- 3

local it = vim.iter({ 3, 6, 9, 12 }):skip(2)
it:next()
-- 9

local function pred(x) return x < 10 end
local it2 = vim.iter({ 3, 6, 9, 12 }):skip(pred)
it2:next()
-- 12

local it = vim.iter({ 1, 2, 3, 4 }):take(2)
it:next()
-- 1
it:next()
-- 2
it:next()
-- nil

local function pred(x) return x < 2 end
local it2 = vim.iter({ 1, 2, 3, 4 }):take(pred)
it2:next()
-- 1
it2:next()
-- nil

vim.iter(string.gmatch('100 20 50', '%d+')):map(tonumber):totable()
-- { 100, 20, 50 }

vim.iter({ 1, 2, 3 }):map(function(v) return v, 2 * v end):totable()
-- { { 1, 2 }, { 2, 4 }, { 3, 6 } }

vim.iter({ a = 1, b = 2, c = 3 }):filter(function(k, v) return v % 2 ~= 0 end):totable()
-- { { 'a', 1 }, { 'c', 3 } }

vim.iter({ 1, 2, 2, 3, 2 }):unique():totable()
-- { 1, 2, 3 }

vim.iter({ {id=1}, {id=2}, {id=1} })
  :unique(function(x)
    return x.id
  end)
  :totable()
-- { {id=1}, {id=2} }

vim.iter({ 1, { 2 }, { { 3 } } }):flatten():totable()
-- { 1, 2, { 3 } }

vim.iter({1, { { a = 2 } }, { 3 } }):flatten():totable()
-- { 1, { a = 2 }, 3 }

vim.iter({ 1, { { a = 2 } }, { 3 } }):flatten(math.huge):totable()
-- error: attempt to flatten a dict-like table

local it = vim.iter({1, 2, 3, 4})
it:pop()
-- 4
it:pop()
-- 3

local it = vim.iter({ 3, 6, 9, 12 }):rev()
it:totable()
-- { 12, 9, 6, 3 }

local it = vim.iter({ 1, 2, 3, 2, 1 }):enumerate()
it:rfind(1)
-- 5	1
it:rfind(1)
-- 1	1

local it = vim.iter({1, 2, 3, 4})
it:rpeek()
-- 4
it:rpeek()
-- 4
it:pop()
-- 4

local it = vim.iter({ 1, 2, 3, 4, 5 }):rskip(2)
it:next()
-- 1
it:pop()
-- 3

Lua module: vim.json vim.json

vim.print(vim.json.decode('{"bar":[],"foo":{},"zub":null}'))
-- { bar = {}, foo = vim.empty_dict(), zub = vim.NIL }

function _G.fmt_json()
  local indent = vim.bo.expandtab and (' '):rep(vim.o.shiftwidth) or '\t'
  local lines = vim.api.nvim_buf_get_lines(0, vim.v.lnum - 1, vim.v.lnum + vim.v.count - 1, true)
  local o = vim.json.decode(table.concat(lines, '\n'))
  local stringified = vim.json.encode(o, { indent = indent, sort_keys = true })
  lines = vim.split(stringified, '\n')
  vim.api.nvim_buf_set_lines(0, vim.v.lnum - 1, vim.v.count, true, lines)
end
vim.o.formatexpr = 'v:lua.fmt_json()'

Lua module: vim.keymap vim.keymap

vim.keymap.del('n', 'lhs')
vim.keymap.del({'n', 'i', 'v'}, '<leader>w', { buf = 5 })

-- Map "x" to a Lua function:
vim.keymap.set('n', 'x', function() print('real lua function') end)
-- Map "<leader>x" to multiple modes for the current buffer:
vim.keymap.set({'n', 'v'}, '<leader>x', vim.lsp.buf.references, { buf = 0 })
-- Map <Tab> to an expression (|:map-<expr>|):
vim.keymap.set('i', '<Tab>', function()
  return vim.fn.pumvisible() == 1 and '<C-n>' or '<Tab>'
end, { expr = true })
-- Map "[%%" to a <Plug> mapping:
vim.keymap.set('n', '[%%', '<Plug>(MatchitNormalMultiBackward)')

-- Use `getregionpos(getpos('v'))` to get the "current visual selection":
vim.keymap.set('x', 'M', function()
  local region = vim.fn.getregionpos(vim.fn.getpos('v'), vim.fn.getpos('.'), {
    type = 'v',
    exclusive = false,
    eol = false,
    bounds = true,
  })
  local line1 = region[1][1][2]
  local line2 = region[1][2][2]
  vim.print({ line1, line2 })
end)

vim.keymap.set({ 'n', 'i' }, { 'a', 'b' }, '<cmd>echom localtime()<cr>')
-- ... is the same as:
vim.keymap.set('n', 'a', '<cmd>echom localtime()<cr>')
vim.keymap.set('i', 'a', '<cmd>echom localtime()<cr>')
vim.keymap.set('n', 'b', '<cmd>echom localtime()<cr>')
vim.keymap.set('i', 'b', '<cmd>echom localtime()<cr>')

Lua module: vim.loader vim.loader

Lua module: vim.log vim.log

local log = vim.log.new({ name = 'my-plugin', })
-- By default, logs will be written to {name}.log under `stdpath('log')`.

log.error('request failed', 'timeout')
-- This will write a line like the following to the log file:
--   [ERROR][2024-01-01 12:00:00] source.lua:123    request failed    timeout

-- Set the log level to `INFO`, otherwise the `info()` call below would be ignored,
-- since the default level is `WARN`.
vim.log.set_level(log, vim.log.levels.INFO)
log.info('starting', { buf = vim.api.nvim_get_current_buf() })
-- This will write a line like the following to the log file:
--   [INFO][2024-01-01 12:01:00] source.lua:124    starting    { buf = 1 }

Lua module: vim.lpeg vim.lpeg

local pattern = lpeg.R('az') ^ 1 * -1
assert(pattern:match('hello') == 6)
assert(lpeg.match(pattern, 'hello') == 6)
assert(pattern:match('1 hello') == nil)

local function split (s, sep)
  sep = lpeg.P(sep)
  local elem = lpeg.C((1 - sep) ^ 0)
  local p = elem * (sep * elem) ^ 0
  return lpeg.match(p, s)
end
local a, b, c = split('a,b,c', ',')
assert(a == 'a')
assert(b == 'b')
assert(c == 'c')

local number = lpeg.R('09') ^ 1 / tonumber
local list = number * (',' * number) ^ 0
local function add(acc, newvalue) return acc + newvalue end
local sum = lpeg.Cf(list, add)
assert(sum:match('10,30,43') == 83)

local I = lpeg.Cp()
local function anywhere(p) return lpeg.P({I * p * I + 1 * lpeg.V(1)}) end
local match_start, match_end = anywhere('world'):match('hello world!')
assert(match_start == 7)
assert(match_end == 12)

local function gsub (s, patt, repl)
  patt = lpeg.P(patt)
  patt = lpeg.Cs((patt / repl + 1) ^ 0)
  return lpeg.match(patt, s)
end
assert(gsub('Hello, xxx!', 'xxx', 'World') == 'Hello, World!')

lpeg.locale(lpeg)
local space = lpeg.space ^ 0
local name = lpeg.C(lpeg.alpha ^ 1) * space
local sep = lpeg.S(',;') * space
local pair = lpeg.Cg(name * '=' * space * name) * sep ^ -1
local list = lpeg.Cf(lpeg.Ct('') * pair ^ 0, rawset)
local t = list:match('a=b, c = hi; next = pi')
assert(t.a == 'b')
assert(t.c == 'hi')
assert(t.next == 'pi')
local locale = lpeg.locale()
assert(type(locale.digit) == 'userdata')

local pattern = lpeg.R('az') ^ 1 * -1
assert(pattern:match('hello') == 6)
assert(lpeg.match(pattern, 'hello') == 6)
assert(pattern:match('1 hello') == nil)

local pattern = lpeg.R('az') ^ 1 * -1
assert(pattern:match('hello') == 6)

local b = lpeg.P({'(' * ((1 - lpeg.S '()') + lpeg.V(1)) ^ 0 * ')'})
assert(b:match('((string))') == 11)
assert(b:match('(') == nil)

Lua module: vim.mpack vim.mpack

Lua module: vim.net vim.net

-- Write response body to file.
vim.net.request('https://neovim.io/charter/', {
  outpath = 'vision.html',
})

-- Process the response.
vim.net.request(
  'https://api.github.com/repos/neovim/neovim',
  {},
  function (err, res)
    if err then return end
    local stars = vim.json.decode(res.body).stargazers_count
    vim.print(('Neovim currently has %d stars'):format(stars))
  end
)

-- Write to both file and current buffer, but cancel it.
local job = vim.net.request('https://neovim.io/charter/', {
  outpath = 'vision.html',
  outbuf = 0,
})
job:close()

-- Await the response in a task (|lua-async|). Closing the task cancels the request.
vim.async.run(function()
  local err, res = vim.async.await(3, vim.net.request, 'https://neovim.io/charter/', {})
end)

-- Add custom headers in the request.
vim.net.request('https://neovim.io/charter/', {
  headers = { Authorization = 'Bearer XYZ' },
})

-- POST request with body.
vim.net.request('POST', 'https://example.com/api', {
  body = '{"key": "value"}',
  headers = {['Content-Type'] = 'application/json' }
})

Lua module: vim.pos vim.pos

local pos1 = vim.pos(0, 3, 5)
local pos2 = vim.pos(0, 4, 0)

-- Operators are overloaded for comparing two `vim.Pos` objects.
if pos1 < pos2 then
  print("pos1 comes before pos2")
end

if pos1 ~= pos2 then
  print("pos1 and pos2 are different positions")
end

local buf = vim.api.nvim_win_get_buf(0)
local cursor_pos = vim.api.nvim_win_get_cursor(0)
local pos = vim.pos.cursor(buf, cursor_pos)
-- This is equivalent:
local pos = vim.pos.cursor(0)

local pos = vim.pos.extmark(0, 3, 5)

local lsp_pos = {
  line = 3,
  character = 5
}

local pos = vim.pos.lsp(0, lsp_pos, 'utf-16')

local mark_info = vim.api.nvim_get_mark('M')
local lnum, col, buf, name = unpack(mark_info)

if lnum == 0 and col == 0 and buf == 0 then
  return -- mark 'M' is not set.
end

local pos = vim.pos.mark(buf, lnum, col)

local offset = vim.api.nvim_buf_get_offset(0, vim.api.nvim_buf_line_count(0))
local pos = vim.pos.offset(0, offset)

local pos = vim.pos(0, 3, 5)

-- Convert to cursor position, you can call it in a method style.
local cursor_pos = pos:to_cursor()
vim.api.nvim_win_set_cursor(0, cursor_pos)

local pos = vim.pos(0, 3, 5)

-- Convert to extmark position, you can call it in a method style.
local extmark_pos = pos:to_extmark()

local pos = vim.pos(0, 3, 5)

-- Convert to LSP position, you can call it in a method style.
local lsp_pos = pos:to_lsp('utf-16')

local pos = vim.pos(0, 3, 5)

-- Convert to mark position, you can call it in a method style.
local lnum, col = pos:to_mark()
vim.api.nvim_buf_set_mark(0, 'M', lnum, col)

local p1 = vim.pos(0, 3, 5)
local p2 = vim.pos(0, 4, 0)

-- Convert to buffer offset, you can call it in a method style.
local offset1 = p1:to_offset()
local offset2 = p2:to_offset()
-- Can be used to calculate the distance between two locations.
local distance = offset2 - offset1

Lua module: vim.range vim.range

local pos1 = vim.pos(0, 3, 5)
local pos2 = vim.pos(0, 4, 0)

-- Create a range from two positions.
local range1 = vim.range(pos1, pos2)
-- Or create a range from four integers representing start and end positions.
local range2 = vim.range(0, 3, 5, 4, 0)

-- Because `vim.Range` is end exclusive, `range1` and `range2` both represent
-- a range starting at the row 3, column 5 and ending at where the row 3 ends
-- (including the newline at the end of line 3).

-- Operators are overloaded for comparing two `vim.Pos` objects.
if range1 == range2 then
  print("range1 and range2 are the same range")
end

local range = vim.range.extmark(0, 3, 5, 4, 0)

local lsp_range = {
  ['start'] = { line = 3, character = 5 },
  ['end'] = { line = 4, character = 0 }
}

local range = vim.range.lsp(0, lsp_range, 'utf-16')

-- A range represented by marks may be end-inclusive (decided by 'selection' option).
local start_lnum, start_col = unpack(api.nvim_buf_get_mark(bufnr, '<'))
local end_lnum, end_col = unpack(api.nvim_buf_get_mark(bufnr, '>'))

-- Create an end-exclusive range.
local range = vim.range.mark(0, start_lnum, start_col, end_lnum, end_col)

local range = vim.range(0, 3, 5, 4, 0)

-- Convert to extmark range, you can call it in a method style.
local extmark_range = range:to_extmark()

local range = vim.range(0, 3, 5, 4, 0)

-- Convert to LSP range, you can call it in a method style.
local lsp_range = range:to_lsp('utf-16')

local range = vim.range(0, 3, 5, 4, 0)

-- Convert to mark range, you can call it in a method style.
local start_lnum, start_col, end_lnum, end_col = range:to_mark()

Lua module: vim.re vim.re

Lua module: vim.regex vim.regex

Lua module: vim.secure vim.secure

Lua module: vim.snippet vim.snippet

vim.api.nvim_clear_autocmds({ group = 'nvim.snippet', buffer = 0 })

vim.keymap.set({ 'i', 's' }, '<Tab>', function()
   if vim.snippet.active({ direction = 1 }) then
     return '<Cmd>lua vim.snippet.jump(1)<CR>'
   else
     return '<Tab>'
   end
 end, { desc = '...', expr = true, silent = true })

Lua module: vim.spell vim.spell

vim.spell.check("the quik brown fox")
-- =>
-- {
--     {'quik', 'bad', 5}
-- }

Lua module: vim.system lua-vim-system

local task = vim.async.run(function()
  return vim.async.await(3, vim.system, { 'sleep', '10' }, {})
end)
task:close() -- Stops `sleep`.

local obj = vim.system({'sleep', '10'})
obj:kill('sigterm') -- sends SIGTERM to the process

local obj = vim.system({'echo', 'hello'}, { text = true })
local result = obj:wait(1000) -- waits up to 1000ms
print(result.code, result.signal, result.stdout, result.stderr)

-- Monitor a long-lived process that prints "READY".
local result = vim.system({ 'ssh', '-L', … }):wait(nil, function(stdout)
  return stdout:find('READY') ~= nil
end)

local obj = vim.system({'cat'}, { stdin = true })
obj:write({'hello', 'world'}) -- writes 'hello\nworld\n' to stdin
obj:write(nil) -- closes stdin

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 = '' }

Lua module: vim.text vim.text

vim.text.diff('a\n', 'b\nc\n')
-- =>
-- @@ -1 +1,2 @@
-- -a
-- +b
-- +c

vim.text.diff('a\n', 'b\nc\n', {result_type = 'indices'})
-- =>
-- {
--   {1, 1, 1, 2}
-- }

vim.print(vim.text.indent(0, ' a\n  b\n'))

local indented, old_indent = vim.text.indent(0, ' a\n b\n')
indented = vim.text.indent(old_indent + 2, indented)
vim.print(indented)

local text = '  a\n  b\n '
vim.print(vim.text.indent(0, (text:gsub('\n[\t ]+\n?$', '\n'))))

Lua module: vim.ui vim.ui

local opts = { prompt = 'Enter value for shiftwidth: ', scope = 'buffer' }
vim.ui.input(opts, function(input)
    vim.o.shiftwidth = tonumber(input)
end)

-- Asynchronous.
vim.ui.open("https://neovim.io/")
vim.ui.open("~/path/to/file")
-- Use the "osurl" command to handle the path or URL.
vim.ui.open("gh#neovim/neovim!29490", { cmd = { 'osurl' } })
-- Synchronous (wait until the process exits).
local cmd, err = vim.ui.open("$VIMRUNTIME")
if cmd then
  cmd:wait()
end

vim.ui.select({ 'tabs', 'spaces' }, {
  prompt = 'Select tabs or spaces:',
  format_item = function(item)
    return ('I choose %s!'):format(item)
  end,
  preview_item = function(item)
    local lines = { 'This is ' .. vim.inspect(item) }
    local buf = vim.api.nvim_create_buf(false, true)
    vim.api.nvim_buf_set_lines(buf, 0, -1, false, lines)
    vim.bo[buf].bufhidden = 'wipe'
    return { buf = buf }
  end,
}, function(choice)
  vim.o.expandtab = choice == 'spaces'
  vim.print(('Selected "%s" => expandtab=%s'):format(choice, vim.o.expandtab))
end)

Lua module: vim.ui.img vim.ui.img

-- Load image bytes from disk and display at row 5, column 10
local id = vim.ui.img.set(
 vim.fn.readblob('/path/to/img.png'),
 { row = 5, col = 10, width = 40, height = 20, zindex = 50 }
)

-- Update the image position
vim.ui.img.set(id, { row = 8, col = 12 })

-- Retrieve the current image opts
local opts = vim.ui.img.get(id)

-- Remove the image
vim.ui.img.del(id)

-- Remove all images
vim.ui.img.del(math.huge)

Lua module: vim.uri vim.uri

vim.uri.parse('HTTP://h/a') == vim.uri.new({ scheme = 'http', host = 'h', path = '/a' }) --> true

vim.uri.decode_query('q=a+b%26c&tag=x&tag=y&flag')
--> { q = 'a b&c', tag = { 'x', 'y' }, flag = '' }

vim.uri.encode('/a b?') --> '/a%20b%3f'
vim.uri.encode('/a b?', 'rfc2396') --> '%2fa%20b%3f'

vim.uri.encode_query({ q = 'a b&c', tag = { 'x', 'y' }, n = 1 })
--> 'n=1&q=a+b%26c&tag=x&tag=y'

vim.uri.from_fname('/a b/c#') --> 'file:///a%20b/c%23'
vim.uri.from_fname('C:\\a\\b') --> 'file:///C:/a/b'
vim.uri.from_fname('//server/share/a') --> 'file://server/share/a' (UNC)
vim.uri.from_fname('a') --> 'file:///home/user/a' (if CWD is "/home/user")
vim.uri.from_fname('jdt://a/b') --> 'jdt://a/b'

tostring(vim.uri.join('file:///home/u/proj', 'src', 'a#1.lua'))
--> 'file:///home/u/proj/src/a%231.lua'
tostring(vim.uri.join('file:///C:/a', '../../x')) --> 'file:///C:/x'
tostring(vim.uri.join('https://h/api/?v=1', 'users/')) --> 'https://h/api/users/?v=1'
vim.uri.join('file:///a', 'file:///b') --> error: a segment can't be a URI

tostring(vim.uri.new({ scheme = 'https', host = '::1', port = 8080, path = '/a' }))
--> 'https://[::1]:8080/a'
tostring(vim.uri.new({ scheme = 'https', host = 'h', path = '/s', query = { q = 'a b' } }))
--> 'https://h/s?q=a+b'

tostring(vim.uri.normalize('HTTPS://Example.COM:443/a/./b/../%7e%2f'))
--> 'https://example.com/a/~%2F'
vim.uri.normalize('HTTP://h:80') == vim.uri.normalize('http://h/') --> true

vim.uri.parse('https://u:p%40ss@example.com:80/a%20b?q=1#section')
--> { scheme = 'https', user = 'u', password = 'p@ss', host = 'example.com', port = 80,
     path = '/a%20b', query = { q = '1' }, querystr = 'q=1', fragment = 'section' }
vim.uri.parse('/a/b') --> nil
vim.uri.parse('C:/a') --> nil
vim.uri.parse('https://h:x') --> nil

-- tostring() builds the URI from the fields.
local u = vim.uri.parse('https://example.com/a')
u.host, u.port = '::1', 8080
tostring(u) --> 'https://[::1]:8080/a'

vim.uri.to_fname('file:///a%3Fb?c#d') --> '/a?b'
vim.uri.to_fname('file:///C:/a/b') --> 'C:/a/b'
vim.uri.to_fname('file://server/share/a') --> '//server/share/a'
vim.uri.to_fname('jdt://a/b') --> 'jdt://a/b'

Lua module: vim.version vim.version

local v = vim.version.parse(vim.system({'tmux', '-V'}):wait().stdout, {strict=false})
if vim.version.gt(v, {3, 2, 0}) then
  -- ...
end

VERSION RANGE SPEC version-range

1.2.3             is 1.2.3
=1.2.3            is 1.2.3
>1.2.3            greater than 1.2.3
<1.2.3            before 1.2.3
>=1.2.3           at least 1.2.3
<=1.2.3           at most 1.2.3
~1.2.3            is >=1.2.3 <1.3.0       "reasonably close to 1.2.3"
^1.2.3            is >=1.2.3 <2.0.0       "compatible with 1.2.3"
^0.2.3            is >=0.2.3 <0.3.0       (0.x.x is special)
^0.0.1            is =0.0.1               (0.0.x is special)
^1.2              is >=1.2.0 <2.0.0       (like ^1.2.0)
~1.2              is >=1.2.0 <1.3.0       (like ~1.2.0)
^1                is >=1.0.0 <2.0.0       "compatible with 1"
~1                same                    "reasonably close to 1"
1.x               same
1.*               same
1                 same
*                 any version
x                 same

1.2.3 - 2.3.4     is >=1.2.3 <2.3.4

Partial right: missing pieces treated as x (2.3 => 2.3.x).
1.2.3 - 2.3       is >=1.2.3 <2.4.0
1.2.3 - 2         is >=1.2.3 <3.0.0

Partial left: missing pieces treated as 0 (1.2 => 1.2.0).
1.2 - 2.3.0       is 1.2.0 - 2.3.0

local r = vim.version.range('1.0.0 - 2.0.0')
print(r:has('1.9.9'))       -- true
print(r:has('2.0.0'))       -- false
print(r:has(vim.version())) -- check against current Nvim version

local r = vim.version.range('1.0.0 - 2.0.0') -- >=1.0, <2.0
print(vim.version.ge({1,0,3}, r.from) and vim.version.lt({1,0,3}, r.to))

if vim.version.cmp({1,0,3}, {0,2,1}) == 0 then
  -- ...
end
local v1 = vim.version.parse('1.0.3-pre')
local v2 = vim.version.parse('0.2.1')
if vim.version.cmp(v1, v2) == 0 then
  -- ...
end

{ major = 1, minor = 0, patch = 1, prerelease = "rc1", build = "build.2" }

UI2 ui2

require('vim._core.ui2').enable({
  enable = true, -- Whether to enable or disable the UI.
  msg = { -- Options related to the message module.
    ---@type string|table<string, 'cmd'|'msg'|'pager'> Default message target
    ---or table mapping |ui-messages| kinds, triggers and IDs to a target.
    ---Table keys are matched as a Lua pattern to the message ID. 'default'
    ---mapping applies to any omitted kind: { default = 'cmd', progress = 'msg' }.
    targets = 'cmd',
    dialog = { -- Options related to dialog window.
      height = 0.5, -- Maximum height.
    },
    msg = { -- Options related to msg window.
      height = 0.5, -- Maximum height.
    },
    pager = { -- Options related to message window.
      height = 0.999, -- Maximum height.
    },
  },
})

set messagesopt+=maxheight:50,pager:<CR>,timeout:4000