Nvim API API api

API Usage api-rpc RPC rpc

CONNECTING rpc-connecting

nvim --listen 127.0.0.1:6666

#!/usr/bin/env ruby
# Requires msgpack: gem install msgpack
#
# To run this script, use Nvim's built-in terminal emulator:
#
#   :term ruby hello.rb
#
# Or from another shell by setting NVIM:
# :echo v:servername -- this is the unix socket path address
# $ NVIM=[unix_socket_path_address] ruby ./hello.rb
# or if you run the command above: nvim --listen 127.0.0.1:6666 -- tcp socket address
# $ NVIM=127.0.0.1:6666 ruby hello.rb

require 'msgpack'
require 'socket'

sock =
if ENV['NVIM'] =~ /:\d+$/
    host, port = ENV['NVIM'].split(':')
    TCPSocket.new(host, port)
else
    UNIXSocket.new(ENV['NVIM'])
end
sock.write([0, 0, 'nvim_command', ['echo "hello world!"']].to_msgpack)
p MessagePack::Unpacker.new(sock).read.last

>>> from pynvim import attach
>>> nvim = attach('socket', path='[address]')
>>> nvim.command('echo "hello world!"')

local nvim = vim.fn.jobstart({ 'nvim', '--embed' }, { rpc = true })
print(vim.rpcrequest(nvim, 'nvim_eval', '"Hello " . "world!"'))
vim.fn.jobstop(nvim)

API Definitions api-definitions

API metadata api-metadata

API contract api-contract

Buffer update events api-buffer-updates

nvim_buf_lines_event[{buf}, {changedtick}, 0, -1, [""], v:false]

nvim_buf_lines_event[{buf}, {changedtick}, 0, 0, ["line1", "line2"], v:false]

nvim_buf_lines_event[{buf}, {changedtick}, {linenr}, {linenr} + 1,
                     ["Hello world!"], v:false]

nvim_buf_lines_event[{buf}, {changedtick}, 2, 22, [], v:false]

nvim_buf_lines_event[{buf}, {changedtick}, 2, 5,
  ['pasted line 1', 'pasted line 2', 'pasted line 3', 'pasted line 4',
   'pasted line 5', 'pasted line 6'],
  v:false
]

nvim_buf_detach_event[{buf}]

vim.api.nvim_buf_get_lines(buf, firstline, new_lastline, true)

Buffer highlighting api-highlights

-- create the highlight through an extmark
extid = vim.api.nvim_buf_set_extmark(buf, ns_id, line, col_start, {end_col = col_end, hl_group = hl_group})

-- example: modify the extmark's highlight group
vim.api.nvim_buf_set_extmark(buf, ns_id, line, col_start, {end_col = col_end, hl_group = NEW_HL_GROUP, id = extid})

-- example: change the highlight's position
vim.api.nvim_buf_set_extmark(buf, ns_id, NEW_LINE, col_start, {end_col = col_end, hl_group = NEW_HL_GROUP, id = extid})

Floating windows api-floatwin floating-windows E5601 E5602

if vim.api.nvim_win_get_config(window_id).relative ~= '' then
  -- window with this window_id is floating
end

let buf = nvim_create_buf(v:false, v:true)
call nvim_buf_set_lines(buf, 0, -1, v:true, ["test", "text"])
let opts = {'relative': 'cursor', 'width': 10, 'height': 2, 'col': 0,
    \ 'row': 1, 'anchor': 'NW', 'style': 'minimal'}
let win = nvim_open_win(buf, 0, opts)
" optional: change highlight, otherwise Pmenu is used
call nvim_set_option_value('winhl', 'Normal:MyHighlight', {'win': win})

Extended marks api-extended-marks extmarks extmark

 f o o b a r      line contents
 0 1 2 3 4 5      character positions (0-based)
0 1 2 3 4 5 6     extmark positions (0-based)

f o o|b a r      line (| = cursor)
     3           extmark

f o o z|b a r    line (| = cursor)
       4         extmark (after typing "z")

f o o z b a r|   line (| = cursor)
             7   extmark

f o o z b a r    first line
                 extmarks (none present)
|                second line (| = cursor)
0                extmark (after typing <CR>)

  01 2345678
0 ex|ample..
    ^ extmark position

let g:mark_ns = nvim_create_namespace('myplugin')
let g:mark_id = nvim_buf_set_extmark(0, g:mark_ns, 0, 2)

echo nvim_buf_get_extmark_by_id(0, g:mark_ns, g:mark_id)
" => [0, 2]

echo nvim_buf_get_extmarks(0, g:mark_ns, 0, -1)
" => [[1, 0, 2]]

  0 12345678
0 e|ample..
   ^ extmark position

echo nvim_buf_get_extmark_by_id(0, g:mark_ns, g:mark_id)
" => [0, 1]

Global Events api-events

Global Functions api-global

vim.api.nvim_echo({ { 'chunk1-line1\nchunk1-line2\n' }, { 'chunk2-line1' } }, true)

local peer = vim.fn.jobstart({ vim.v.progpath, '--clean', '--embed' }, { rpc=true })
vim.print(vim.rpcrequest(peer, 'nvim_exec_lua', [[
      local a, b = ...
      return ('result: %s'):format(a + b)
    ]],
    { 1, 3 }
  )
)

:let key = nvim_replace_termcodes('<C-o>', v:true, v:false, v:true)
:call nvim_feedkeys(key, 'n', v:false)

:echo nvim_get_color_by_name("Pink")
:echo nvim_get_color_by_name("#cbcbcb")

vim.print(vim.api.nvim_get_chan_info(vim.api.nvim_list_uis()[1].chan).client.name)

vim.api.nvim_create_user_command('TermHl', function()
  vim.api.nvim_open_term(0)
end, { desc = 'Highlights ANSI termcodes in curbuf' })

vim.keymap.set('n', 'x', function()
  vim.api.nvim_paste([[
    line1
    line2
    line3
  ]], false, -1)
end, { buf = 0 })

call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true})

nmap <nowait> <Space><NL> <Nop>

Vimscript Functions api-vimscript

Autocmd Functions api-autocmd

local id = vim.api.nvim_create_augroup('my.lsp.config', {
  clear = false
})

vim.api.nvim_create_autocmd({'BufEnter', 'BufWinEnter'}, {
  pattern = {'*.c', '*.h'},
  callback = function(ev)
    print(string.format('event fired: %s', vim.inspect(ev)))
  end
})

vim.api.nvim_create_autocmd({'BufEnter', 'BufWinEnter'}, {
  pattern = {'*.c', '*.h'},
  command = "echo 'Entering a C or C++ file'",
})

pattern = vim.fn.expand('~') .. '/some/path/*.py'

-- Matches all criteria
autocommands = vim.api.nvim_get_autocmds({
  group = 'MyGroup',
  event = {'BufEnter', 'BufWinEnter'},
  pattern = {'*.c', '*.h'}
})

-- All commands from one group
autocommands = vim.api.nvim_get_autocmds({
  group = 'MyGroup',
})

Buffer Functions api-buffer

events = {}
vim.api.nvim_buf_attach(0, false, {
  on_lines = function(...)
    table.insert(events, {...})
  end,
})

vim.bo.buflisted = false
vim.api.nvim_buf_delete(0, { unload = true })

Command Functions api-command

vim.api.nvim_cmd({
    cmd = 'edit',
    args = { '%foo"|bar#baz"' },
    magic = { file = false, bar = false }
  },
  {}
)

:call nvim_create_user_command('SayHello', 'echo "Hello world!"', {'bang': v:true})
:SayHello
Hello world!

Extmark Functions api-extmark

vim.api.nvim_buf_get_extmarks(0, my_ns, 0, -1)
vim.api.nvim_buf_get_extmarks(0, my_ns, {0,0}, {-1,-1})

local api = vim.api
local pos = api.nvim_win_get_cursor(0)
local ns  = api.nvim_create_namespace('my-plugin')
-- Create new extmark at line 1, column 1.
local m1  = api.nvim_buf_set_extmark(0, ns, 0, 0)
-- Create new extmark at line 3, column 1.
local m2  = api.nvim_buf_set_extmark(0, ns, 2, 0)
-- Get extmarks only from line 3.
local ms  = api.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0})
-- Get all marks in this buffer + namespace.
local all = api.nvim_buf_get_extmarks(0, ns, 0, -1)
vim.print(ms)

Options Functions api-options

Tabpage Functions api-tabpage

UI Functions api-ui

Win_config Functions api-win_config

-- Window-relative float with 'statusline' enabled:
local w1 = vim.api.nvim_open_win(0, false,
  {relative='win', row=3, col=3, width=40, height=4})
vim.wo[w1].statusline = vim.o.statusline

-- Buffer-relative float (travels as buffer is scrolled):
vim.api.nvim_open_win(0, false,
  {relative='win', width=40, height=4, bufpos={100,10}})

-- Vertical split left of the current window:
vim.api.nvim_open_win(0, false, { split = 'left', win = 0, })

vim.print(vim.api.nvim_win_get_config(0).relative == '' and 'non-float' or 'float')
-- Or use win_gettype().
vim.print(vim.fn.win_gettype())

vim.api.nvim_win_set_config(0, { split = 'above', win = vim.fn.win_getid(1), })

Window Functions api-window