nvim.lua

nvim is an object which contains shortcut/magic methods that are very useful for mappings.

Fun fact: nvim.fn/env/v/g/o/wo/bo were merged into master as of November 2019.

Why use this module?

Here's an excerpt of functionality from my init.lua. Without nvim.lua, it looks like this:

-- Save and close the current buffer instead of all of VIM.
-- But if it's the last buffer, then save and close vim.
if #vim.api.nvim_list_bufs() > 1 then
  if not vim.api.nvim_buf_get_option(vim.api.nvim_get_current_buf(), "modifiable") then
    vim.api.nvim_command("bd")
  else
    vim.api.nvim_command("w | bd")
  end
else
  vim.api.nvim_command("xit")
end

Here's what it looks like with nvim.lua:

if #nvim.list_bufs() > 1 then
  if not nvim.bo.modifiable then
    nvim.command("bd")
  else
    nvim.command("w | bd")
  end
else
  nvim.command("xit")
end

Or if you're extreme:

if #nvim.list_bufs() > 1 then
  if not nvim.bo.modifiable then
    nvim.ex.bd()
  else
    nvim.command("w | bd")
  end
else
  nvim.ex.xit()
end

Installation

Plug 'norcalli/nvim.lua'

Usage

local nvim = require 'nvim'

API

API Function and Command Shortcuts

All of these methods cache the inital lookup in the metatable, but there is a small overhead regardless.

nvim.$method

nvim.$method(...) redirects to vim.api.nvim_$method(...)

e.g. nvim.command(...) == vim.api.nvim_command(...).

This is mostly for laziness.

nvim.fn.$method

nvim.fn.$method(...) redirects to vim.api.nvim_call_function($method, {...})

e.g. nvim.fn.expand("%:h") or nvim.fn.has("terminal")

nvim.ex.$method

nvim.ex.$command(...) is approximately :$command flatten({...}).join(" ")

e.g. nvim.ex.edit("term://$SHELL") or nvim.ex.startinsert()

NOTE: Since ! isn't a valid identifier character, you can use _ at the end to indicate a ! e.g. nvim.ex.nnoremap_("x", "<Cmd>echo hi<CR>")

Variable shortcuts

nvim.g

nvim.g can be used to get/set g: global variables.
- e.g. nvim.g.variable == g:variable
- nvim.g.variable = 123 or nvim.g.variable = nil to delete the variable
- :h nvim_get_var :h nvim_set_var :h nvim_del_var for more

nvim.v

nvim.v can be used to get/set v: variables.
- e.g. nvim.v.count1 == v:count1
- Useful v: variables, v:register, v:count1, etc..
- nvim.v.variable = 123 to set the value (when not read-only).
- :h nvim_get_vvar :h nvim_set_vvar for more

nvim.b

nvim.b can be used to get/set b: buffer variables for the current buffer.
- Can use nvim.b[bufnr] to target a different buffer than the current one.
  - e.g. nvim.b[bufnr].x = '123'
- e.g. nvim.b.variable == b:variable
- nvim.b.variable = 123 or nvim.b.variable = nil to delete the variable
- :h nvim_buf_get_var :h nvim_buf_set_var :h nvim_buf_del_var for more

nvim.w

nvim.w can be used to get/set w: buffer variables for the current buffer.
- Can use nvim.w[winnr] to target a different window than the current one.
  - e.g. nvim.w[winnr].x = '123'
- e.g. nvim.w.variable == w:variable
- nvim.w.variable = 123 or nvim.w.variable = nil to delete the variable
- :h nvim_win_get_var :h nvim_win_set_var :h nvim_win_del_var for more
If you're interested in variables set by set/setlocal, then you want nvim.wo.

nvim.env

nvim.env can be used to get/set environment variables.
- e.g. nvim.env.PWD == $PWD
- nvim.env.TEST = 123 to set the value. Equivalent to let $TEST = 123.
- :h setreg :h setreg for more. These aren't API functions.

nvim.o

nvim.o can be used to get/set global options, as in :h options which are set through set.
- e.g. nvim.o.shiftwidth == &shiftwidth
- nvim.o.shiftwidth = 8 is equivalent to set shiftwidth=8 or let &shiftwidth = 8
- :h nvim_get_option :h nvim_set_option for more.

nvim.bo

nvim.bo can be used to get/set buffer options, as in :h options which are set through setlocal.
- Can use nvim.bo[bufnr] to target a different buffer than the current one.
  - e.g. nvim.bo[bufnr].ft = 'markdown'
- Only for the current buffer.
- e.g. nvim.bo.shiftwidth == &shiftwidth
- nvim.bo.shiftwidth = 8 is equivalent to setlocal shiftwidth=8
- :h nvim_buf_get_option :h nvim_buf_set_option for more.

nvim.wo

nvim.wo can be used to get/set window options, as in :h options which are set through set/setlocal.
- Can use nvim.wo[winnr] to target a different window than the current one.
  - e.g. nvim.wo[winnr].wrap = false
- These are the valid options as of writing: { "arabic", "arab", "breakindent", "bri", "breakindentopt", "briopt", "colorcolumn", "cc", "concealcursor", "cocu", "conceallevel", "cole", "cursorbind", "crb", "cursorcolumn", "cuc", "cursorline", "cul", "diff", "fillchars", "fcs", "foldcolumn", "fdc", "foldenable", "fen", "foldexpr", "fde", "foldignore", "fdi", "foldlevel", "fdl", "foldmarker", "fmr", "foldmethod", "fdm", "foldminlines", "fml", "foldnestmax", "fdn", "foldtext", "fdt", "linebreak", "lbr", "list", "listchars", "lcs", "number", "nu", "numberwidth", "nuw", "previewwindow", "pvw", "relativenumber", "rnu", "rightleft", "rl", "rightleftcmd", "rlc", "scroll", "scr", "scrollbind", "scb", "signcolumn", "scl", "spell", "statusline", "stl", "winblend", "winbl", "winhighlight", "winhl", "winfixheight", "wfh", "winfixwidth", "wfw", "wrap" }
- e.g. nvim.wo.foldlevel == &foldlevel
- nvim.wo.foldlevel = 4 is equivalent to setlocal foldlevel=4
- nvim.wo.variable = nil to delete the variable. (only works if there's a global fallback)
- :h nvim_win_get_option :h nvim_win_set_option for more.

Afourcat/nvim.lua