Neovim Lua: Complete Guide to vim.fn, vim.api, and Lua Scripting

~/.config/nvim/
├── init.lua              -- Entry point
├── lua/
│   ├── options.lua       -- vim.opt settings
│   ├── keymaps.lua       -- vim.keymap.set() bindings
│   ├── autocmds.lua      -- vim.api.nvim_create_autocmd()
│   └── plugins/
│       ├── lsp.lua       -- LSP configuration
│       ├── treesitter.lua
│       └── telescope.lua

-- init.lua
vim.g.mapleader = ' '
require('options')      -- loads lua/options.lua
require('keymaps')      -- loads lua/keymaps.lua
require('autocmds')     -- loads lua/autocmds.lua

-- Boolean options
vim.opt.number         = true
vim.opt.relativenumber = true
vim.opt.wrap           = false
vim.opt.signcolumn     = 'yes'

-- Numeric options
vim.opt.tabstop    = 2
vim.opt.shiftwidth = 2
vim.opt.scrolloff  = 8

-- String options
vim.opt.clipboard  = 'unnamedplus'

-- List options (comma-separated internally)
vim.opt.wildignore:append({ '*.o', '*.pyc', 'node_modules' })
vim.opt.shortmess:append('I')  -- skip intro screen

-- Map options
vim.opt.listchars = { tab = '» ', trail = '·', nbsp = '␣' }

-- Reading an option value
local tw = vim.opt.tabstop:get()  -- returns Lua number
local wc = vim.o.wildignore       -- returns raw string

-- Basic mappings
vim.keymap.set('n', '<leader>w', ':w<CR>', { desc = 'Save file' })
vim.keymap.set('n', '<leader>q', ':q<CR>', { desc = 'Quit' })

-- Lua function callback
vim.keymap.set('n', '<leader>l', function()
  vim.diagnostic.setloclist()
end, { desc = 'Diagnostics to loclist' })

-- Multiple modes at once
vim.keymap.set({ 'n', 'v' }, '<leader>y', '"+y', { desc = 'Yank to clipboard' })

-- Buffer-local mapping (e.g. in an LspAttach autocmd)
vim.keymap.set('n', 'gd', vim.lsp.buf.definition, { buffer = bufnr, desc = 'Go to definition' })

-- Expression mapping
vim.keymap.set('n', 'k', "v:count == 0 ? 'gk' : 'k'", { expr = true, desc = 'Move by visual line' })

-- Delete a mapping
vim.keymap.del('n', '<leader>q')

-- Create a group (clears existing autocmds in the group on reload)
local augroup = vim.api.nvim_create_augroup('MyGroup', { clear = true })

-- Highlight on yank
vim.api.nvim_create_autocmd('TextYankPost', {
  group = augroup,
  callback = function()
    vim.hl.on_yank({ timeout = 200 })
  end,
  desc = 'Briefly highlight yanked text',
})

-- Format on save
vim.api.nvim_create_autocmd('BufWritePre', {
  group = augroup,
  pattern = { '*.lua', '*.ts', '*.tsx' },
  callback = function()
    vim.lsp.buf.format({ async = false })
  end,
  desc = 'LSP format before save',
})

-- Set options for specific file types
vim.api.nvim_create_autocmd('FileType', {
  group = augroup,
  pattern = 'markdown',
  callback = function()
    vim.opt_local.wrap = true
    vim.opt_local.spell = true
  end,
})

-- Simple command
vim.api.nvim_create_user_command('Hello', function()
  print('Hello from Lua!')
end, { desc = 'Print a greeting' })

-- Command with arguments and completion
vim.api.nvim_create_user_command('Grep', function(opts)
  vim.cmd('silent grep! ' .. opts.args)
  vim.cmd('copen')
end, { nargs = '+', desc = 'Grep and open quickfix' })

-- Buffer-local command
vim.api.nvim_buf_create_user_command(0, 'Format', function()
  vim.lsp.buf.format()
end, { desc = 'Format current buffer' })

-- Built-in functions
local home = vim.fn.expand('$HOME')        -- expand env vars and special chars
local cwd  = vim.fn.getcwd()               -- current working directory
local ext  = vim.fn.fnamemodify('a.lua', ':e')  -- 'lua'

-- Check if a file exists
if vim.fn.filereadable('/etc/hosts') == 1 then
  print('File exists')
end

-- System commands (synchronous)
local result = vim.fn.system('git rev-parse --short HEAD')
local output = vim.fn.systemlist('ls -la')  -- returns a table of lines

-- Autoload functions (use bracket notation for # characters)
vim.fn['plug#begin']()

-- Float/popup windows
local buf = vim.api.nvim_create_buf(false, true)
vim.fn.setbufline(buf, 1, { 'Line 1', 'Line 2' })

-- Basic async job
local job_id = vim.fn.jobstart('make build', {
  on_stdout = function(_, data, _)
    -- data is a list of lines (last element may be '')
    for _, line in ipairs(data) do
      if line ~= '' then
        print('stdout: ' .. line)
      end
    end
  end,
  on_stderr = function(_, data, _)
    for _, line in ipairs(data) do
      if line ~= '' then
        vim.notify(line, vim.log.levels.ERROR)
      end
    end
  end,
  on_exit = function(_, exit_code, _)
    if exit_code == 0 then
      vim.notify('Build succeeded', vim.log.levels.INFO)
    else
      vim.notify('Build failed (exit ' .. exit_code .. ')', vim.log.levels.ERROR)
    end
  end,
})

-- Pass custom environment variables to a job
vim.fn.jobstart({ 'node', 'server.js' }, {
  env = {
    NODE_ENV = 'development',
    PORT = '3000',
    DATABASE_URL = 'postgresql://localhost/mydb',
  },
  cwd = vim.fn.expand('~/projects/myapp'),
  on_exit = function(_, code, _)
    vim.notify('Server exited with code ' .. code)
  end,
})

-- Inherit current env and override specific vars
-- Note: env replaces the entire environment by default.
-- To extend the current environment, merge with vim.fn.environ():
local current_env = vim.fn.environ()
current_env.MY_VAR = 'custom_value'
current_env.DEBUG = '1'

vim.fn.jobstart('my-tool', {
  env = current_env,
  on_stdout = function(_, data, _)
    vim.print(data)
  end,
})

-- Read environment variables
local home   = vim.env.HOME          -- '/home/user'
local editor = vim.env.EDITOR        -- 'nvim'
local path   = vim.env.PATH

-- Set environment variables (affects Neovim session + child processes)
vim.env.MYVAR = 'hello'

-- Expand $HOME and ~ in paths (vim.env does not expand these)
local config = vim.fn.expand('$HOME/.config/nvim')
local notes  = vim.fn.expand('~/notes')

-- Get all environment variables as a dict
local all_env = vim.fn.environ()

-- Check if a variable is set
if vim.env.VIRTUAL_ENV then
  print('Inside a Python venv: ' .. vim.env.VIRTUAL_ENV)
end

-- Conditional config based on environment
if vim.env.SSH_TTY then
  vim.opt.clipboard = ''  -- no clipboard over SSH
end

-- Synchronous: block until complete
local result = vim.system({ 'git', 'branch', '--show-current' }):wait()
print(result.stdout)  -- 'main\n'
print(result.code)    -- 0

-- Asynchronous with callback
vim.system({ 'curl', '-s', 'https://httpbin.org/ip' }, {}, function(obj)
  vim.schedule(function()
    vim.notify(obj.stdout)
  end)
end)

-- With environment and cwd options
vim.system(
  { 'npm', 'test' },
  { env = { CI = 'true' }, cwd = '/path/to/project' }
):wait()

-- Timer: debounced save
local timer = vim.uv.new_timer()
vim.api.nvim_create_autocmd('TextChanged', {
  callback = function()
    timer:stop()
    timer:start(1000, 0, vim.schedule_wrap(function()
      vim.cmd('silent! write')
    end))
  end,
})

-- File watcher: reload config on change
local watcher = vim.uv.new_fs_event()
local config_path = vim.fn.stdpath('config') .. '/init.lua'
watcher:start(config_path, {}, vim.schedule_wrap(function()
  vim.notify('Config changed, reloading...')
  vim.cmd('source ' .. config_path)
end))

-- Read a file asynchronously
vim.uv.fs_open('/tmp/data.txt', 'r', 438, function(err, fd)
  if err then return end
  vim.uv.fs_read(fd, 1024, 0, function(err2, data)
    vim.uv.fs_close(fd, function() end)
    if data then
      vim.schedule(function() vim.notify(data) end)
    end
  end)
end)

-- Safe require (plugin might not be installed)
local ok, telescope = pcall(require, 'telescope')
if not ok then
  vim.notify('telescope.nvim not installed', vim.log.levels.WARN)
  return
end
telescope.setup({})

-- Safe API call with error message
local ok2, err = pcall(vim.api.nvim_set_hl, 0, 'BadGroup', { invalid = true })
if not ok2 then
  vim.notify('Highlight error: ' .. err, vim.log.levels.ERROR)
end

-- xpcall with traceback for debugging
xpcall(function()
  require('plugins.lsp')
end, function(err)
  vim.notify('LSP setup failed:\n' .. debug.traceback(err), vim.log.levels.ERROR)
end)

vim.keymap.set('n', '<leader>tw', function()
  vim.opt.wrap = not vim.opt.wrap:get()
  vim.notify('wrap: ' .. tostring(vim.opt.wrap:get()))
end, { desc = 'Toggle word wrap' })

vim.api.nvim_create_autocmd('BufWritePost', {
  pattern = '*.lua',
  callback = function()
    local bufnr = vim.api.nvim_get_current_buf()
    vim.system({ 'stylua', vim.api.nvim_buf_get_name(bufnr) }, {}, function(obj)
      if obj.code == 0 then
        vim.schedule(function()
          vim.cmd('checktime')  -- reload buffer
        end)
      end
    end)
  end,
})

vim.api.nvim_create_user_command('Scratch', function()
  local buf = vim.api.nvim_create_buf(false, true)
  vim.api.nvim_set_current_buf(buf)
  vim.bo[buf].filetype = 'markdown'
end, { desc = 'Open a scratch buffer' })