Api

API の使用法 api-rpc RPC rpc

接続 rpc-connecting

nvim --listen 127.0.0.1:6666

#!/usr/bin/env ruby
# Requires msgpack-rpc: gem install msgpack-rpc
#
# To run this script, execute it from a running Nvim instance (notice the
# trailing '&' which is required since Nvim won't process events while
# running a blocking command):
#
#   :!./hello.rb &
#
# Or from another shell by setting NVIM_LISTEN_ADDRESS:
# $ NVIM_LISTEN_ADDRESS=[address] ./hello.rb
require 'msgpack/rpc'
require 'msgpack/rpc/transport/unix'
nvim = MessagePack::RPC::Client.new(MessagePack::RPC::UNIXTransport.new, ENV['NVIM_LISTEN_ADDRESS'])
result = nvim.call(:nvim_command, 'echo "hello world!"')

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

let nvim = jobstart(['nvim', '--embed'], {'rpc': v:true})
echo rpcrequest(nvim, 'nvim_eval', '"Hello " . "world!"')
call jobstop(nvim)

API 定義 api-definitions

API Type                              C type
------------------------------------------------------------------------
Nil
Boolean                               bool
Integer (signed 64-bit integer)       int64_t
Float (IEEE 754 double precision)     double
String                                {char* data, size_t size} struct
Array                                 kvec
Dict (msgpack: map)                   kvec
Object                                any of the above

EXT Type      C type                                  Data
------------------------------------------------------------------------
Buffer        enum value kObjectTypeBuffer            |bufnr()|
Window        enum value kObjectTypeWindow            |window-ID|
Tabpage       enum value kObjectTypeTabpage           internal handle

API メタデータ api-metadata

nvim --api-info | python -c 'import msgpack, sys, yaml; yaml.dump(msgpack.unpackb(sys.stdin.buffer.read()), sys.stdout)'

:lua vim.print(vim.fn.api_info())

:new|put =map(filter(api_info().functions, '!has_key(v:val,''deprecated_since'')'), 'v:val.name')

API コントラクト api-contract

グローバルイベント api-global-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)

バッファのハイライト api-highlights

vim.api.nvim_buf_add_highlight(buf, ns_id, hl_group, line, col_start, col_end)

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

src = vim.new_highlight_source()
buf = vim.current.buffer
for i in range(5):
    buf.add_highlight("String",i,0,-1,src_id=src)
# some time later ...
buf.clear_namespace(src)

call nvim_buf_set_lines(0, 0, 0, v:true, ["test text"])
let src = nvim_buf_add_highlight(0, 0, "String", 1, 0, 4)
call nvim_buf_add_highlight(0, src, "Identifier", 0, 5, -1)
" some time later ...
call nvim_buf_clear_namespace(0, src, 0, -1)

フローティングウィンドウ api-floatwin

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

拡張マーク 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]

グローバル関数 api-global

: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.keymap.set('n', 'x', function()
  vim.api.nvim_paste([[
    line1
    line2
    line3
  ]], false, -1)
end, { buffer = true })

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

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

Vimscript関数 api-vimscript

コマンド関数 api-command

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

オプション関数 api-options

バッファー関数 api-buffer

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

Extmark関数 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)

ウィンドウ関数 api-window

Win_config 関数 api-win_config

vim.api.nvim_open_win(0, false,
  {relative='win', row=3, col=3, width=12, height=3})

vim.api.nvim_open_win(0, false,
  {relative='win', width=12, height=3, bufpos={100,10}})

vim.api.nvim_open_win(0, false, {
  split = 'left',
  win = 0
})

[ "/", "-", \"\\\\\", "|" ],

[ "x" ].

[ "", "", "", ">", "", "", "", "<" ]

[ ["+", "MyCorner"], ["x", "MyBorder"] ].

タブページ関数 api-tabpage

自動コマンド関数 api-autocmd

local id = vim.api.nvim_create_augroup("MyGroup", {
    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",
})

UI 関数 api-ui