Vimcraft Docs / vim.api - Core API Functions

vim.api - Core API Functions

Low-level Neovim-compatible API for direct editor manipulation. Uses camelCase naming (JavaScript convention).

Buffer Functions

getCurrentBuf / setCurrentBuf

// Get current buffer handle
const buf = vim.api.getCurrentBuf();

// Set current buffer
vim.api.setCurrentBuf(bufHandle);

Buffer Content

// Get lines from buffer (0-indexed, end is exclusive)
const lines = vim.api.bufGetLines(buf, 0, 10, false);

// Set lines in buffer
vim.api.bufSetLines(buf, 0, 1, false, ['new first line']);

// Get line count
const count = vim.api.bufLineCount(buf);

// Get/set buffer name (file path)
const name = vim.api.bufGetName(buf);
vim.api.bufSetName(buf, '/path/to/file.ts');

Buffer Management

// Check if buffer is valid
if (vim.api.bufIsValid(buf)) {
  // Delete buffer
  vim.api.bufDelete(buf, { force: false, unload: false });
}

Window Functions

getCurrentWin / setCurrentWin

// Get current window handle
const win = vim.api.getCurrentWin();

// Set current window
vim.api.setCurrentWin(winHandle);

Window-Buffer Relationship

// Get buffer displayed in window
const buf = vim.api.winGetBuf(win);

// Display different buffer in window
vim.api.winSetBuf(win, newBuf);

Cursor Position

// Get cursor position [row, col] (1-indexed row, 0-indexed col)
const [row, col] = vim.api.winGetCursor(win);

// Set cursor position
vim.api.winSetCursor(win, [10, 5]); // Line 10, column 5

Window Size

// Get/set window dimensions
const height = vim.api.winGetHeight(win);
const width = vim.api.winGetWidth(win);

vim.api.winSetHeight(win, 20);
vim.api.winSetWidth(win, 80);

Window Management

// Check validity and close
if (vim.api.winIsValid(win)) {
  vim.api.winClose(win, false); // force: false
}

Tabpage Functions

// Get current tabpage
const tab = vim.api.getCurrentTabpage();

// Set current tabpage
vim.api.setCurrentTabpage(tabHandle);

// List all tabpages
const tabs = vim.api.listTabpages();

Autocommand Functions

createAutocmd

Create event-driven callbacks:

// Single event
const id = vim.api.createAutocmd('BufEnter', {
  pattern: '*.ts',
  callback: (args) => {
    console.log('Entered TypeScript file:', args.file);
  },
  desc: 'Log TypeScript file entry'
});

// Multiple events
vim.api.createAutocmd(['BufRead', 'BufNewFile'], {
  pattern: '*.md',
  callback: (args) => {
    vim.opt.wrap = true;
  }
});

// Run once only
vim.api.createAutocmd('VimEnter', {
  once: true,
  callback: () => {
    console.log('Vimcraft started!');
  }
});

Autocommand Events

Common events:

BufEnter, BufLeave, BufRead, BufWrite, BufWritePre, BufWritePost
FileType, WinEnter, WinLeave
InsertEnter, InsertLeave
CursorMoved, CursorHold
VimEnter, VimLeave
TextChanged, TextYankPost

Autocommand Groups

// Create group (clears existing if same name)
const groupId = vim.api.createAugroup('MyPlugin', { clear: true });

// Create autocmd in group
vim.api.createAutocmd('BufWrite', {
  group: 'MyPlugin',
  callback: () => console.log('Saved!')
});

// Clear all autocmds in group
vim.api.clearAutocmds({ group: 'MyPlugin' });

Delete Autocommand

// Delete by ID
vim.api.delAutocmd(id);

User Command Functions

createUserCmd

Create custom Ex commands:

// Simple command
vim.api.createUserCmd('Hello', () => {
  console.log('Hello, Vimcraft!');
}, { desc: 'Say hello' });

// Command with arguments
vim.api.createUserCmd('Greet', (args) => {
  console.log(`Hello, ${args.args}!`);
}, { nargs: 1 });

// Command with bang support
vim.api.createUserCmd('Save', (args) => {
  if (args.bang) {
    console.log('Force saving...');
  }
}, { bang: true });

// Buffer-local command
vim.api.bufCreateUserCmd(buf, 'LocalCmd', () => {
  console.log('Buffer-local command');
}, {});

Command Options

interface UserCommandOpts {
  nargs?: '0' | '1' | '*' | '?' | '+';  // Argument count
  bang?: boolean;      // Allow ! modifier
  range?: boolean;     // Allow line range
  desc?: string;       // Description
  complete?: 'file' | 'dir' | 'buffer' | string;  // Completion
}

Delete User Command

vim.api.delUserCmd('Hello');
vim.api.bufDelUserCmd(buf, 'LocalCmd');

Highlight Functions

// Create namespace for highlights
const ns = vim.api.createNamespace('my-plugin');

// Set highlight group
vim.api.setHighlight(0, 'MyHighlight', {
  fg: '#ff0000',
  bg: '#000000',
  bold: true
});

// Add highlight to buffer region
vim.api.bufAddHighlight(buf, ns, 'MyHighlight', lineNum, colStart, colEnd);

// Clear highlights in namespace
vim.api.bufClearNamespace(buf, ns, 0, -1);

Keymap Functions

// Set global keymap
vim.api.setKeymap('n', '<leader>x', ':echo "hello"<CR>', { silent: true });

// Delete keymap
vim.api.delKeymap('n', '<leader>x');

// Get keymaps for mode
const maps = vim.api.getKeymap('n');

// Buffer-local keymaps
vim.api.bufSetKeymap(buf, 'n', 'K', ':help<CR>', {});
vim.api.bufDelKeymap(buf, 'n', 'K');

Option & Variable Functions

// Global options
const value = vim.api.getOption('number');
vim.api.setOption('number', true);

// Buffer options
vim.api.bufGetOption(buf, 'filetype');
vim.api.bufSetOption(buf, 'filetype', 'typescript');

// Window options
vim.api.winGetOption(win, 'wrap');
vim.api.winSetOption(win, 'wrap', false);

// Variables
vim.api.getVar('my_var');
vim.api.setVar('my_var', 'value');
vim.api.delVar('my_var');

// Buffer variables
vim.api.bufGetVar(buf, 'my_var');
vim.api.bufSetVar(buf, 'my_var', 'value');

Misc Functions

// Execute Ex command
vim.api.command('write');

// Get current mode
const { mode, blocking } = vim.api.getMode();

// Notify user
vim.api.notify('Hello!', 2, {}); // log_level: 2 = INFO

// Echo message with highlight
vim.api.echo([['Hello ', 'Normal'], ['World', 'Error']], true, {});