About

Simple and efficient buffer switcher, using minimum of 2 keystrokes to get anywhere. Whole plugin is just a single window and command. This plugin is to meet my personal requirements, which doesn't include colors or icons, although I might still add more features.

Screenshot

Installation

Just use any package manager to install. setup() function is not provided, instead see configuration. icon option depends on nvim-web-devicons, which must be loaded beforehand.

Usage

Single command, :BuffersToggle, toggles buffer window. Every buffer is filtered using customizable predicate, by default that is: buffer exists and has buflisted option set (see defaults) In that window, only survived buffers are displayed.

From this window, any buffer can be opened using provided key next to it and buffers window is closed.

I recommend mapping :BuffersToggle to single key for fastest navigation.

Configuration

Whole configuration is done via vim.g.buffers_config table which is checked every time buffers window opens, so it can be tweaked, without reloading.

Defaults

---@type buffers.Config
{
	width = 70, -- window width (longer lines are not yet handled)
	min_heigh = 6, -- minimum window height
	position = 'bottom_right', -- window position (can be 'bottom_right', 'top_right' or 'center')
	border = vim.o.winborder, -- window border (accepts same values as vim.api.keyset.win_config.border)
	win_opts = {}, -- additional window local options
	separator = ' | ', -- separator between char and buffer name
	icon = false, -- whether to show icons or not (requires nvim-tree/nvim-web-devicons)
	-- characters that can be bound to buffers
	chars = "qwertyuiopasdfghjklzxcvbnm1234567890",
	-- if non of the characters from `chars` is available use this list (see #internals for more info)
	backup_chars = "QWERTYUIOPASDFGHJKLZXCVBNM_-",
	-- called for every buffer, to determine if it should be listed in buffers window
	filter = function(bufnr)
		return vim.fn.buflised(bufnr)
	end,
	-- how to format buffer names ('relative_path', 'filename_first' or custom function)
	-- for function usage see #formatters
	formatter = 'relative_path',
	-- which keys are used to close the buffers window, without warning
	-- note: <C-c> always closes the window
	close_keys = {"<Esc>"},
}

Internals

Picking chars

Single character bound to each buffer is generated by simple algorithm called get_buffer_char.

local function get_buffer_char(name, buffer_table, chars)
	local char = name:sub(1, 1)
	local i = 2
	while buffer_table:get(char) or chars:find(char, 1, true) == nil do
		if i > #name then
			return nil
		end
		char = name:sub(i, i)
		i = i + 1
	end
	return char
end

This function returns first valid character from buffer's name. Character is valid if it's:

• not already used
• found in chars string

Usage of this function is more interesting:

• For each buffer, first it's called with chars string from configuration.
• If nil is returned, than it's called with backup_chars.
• If that also fails, first available character from chars and backup_chars is used.

Accidental overlap of keys is pretty much impossible.

Mapping chars

For actually mapping character to buffers, getcharstr function is used. Before commit a541273, I was using keymaps which where problematic! thanks to this comment

close_keys option was added because of getcharstr, so BuffersToggle command is less useful, and can just be BuffersOpen, but it still functions as toggle.

Formatters

each formatter is a function that takes full path to a file and returns two values:

1. string formatted string to be used
2. integer[] pair which denotes range for highlighting with Comment hl group. This should be used for less important info, like file path to make file name stand out more. Range is end-exclusive.

TODO

• add custom formatting option
• add icons
• add more highlights
• add docs

Contribution

PRs and Issues are welcome!