--- *mini.tabline* Tabline --- --- MIT License Copyright (c) 2021 Evgeni Chasnovski --- Key idea: show all listed buffers in readable way with minimal total width. --- --- Features: --- - Buffers are listed in the order of their identifier (see |bufnr()|). --- --- - Different highlight groups for "states" of buffer affecting "buffer tabs". --- --- - Buffer names are made unique by extending paths to files or appending --- unique identifier to buffers without name. --- --- - Current buffer is displayed "optimally centered" (in center of screen --- while maximizing the total number of buffers shown) when there are many --- buffers open. --- --- - "Buffer tabs" are clickable if Neovim allows it. --- --- - Extra information section in case of multiple Neovim tabpages. --- --- - Truncation symbols which show if there are tabs to the left and/or right. --- Exact characters are taken from |'listchars'| global value (`precedes` and --- `extends` fields) and are shown only if |'list'| option is enabled. --- --- What it doesn't do: --- - Custom buffer order is not supported. --- --- # Dependencies ~ --- --- Suggested dependencies (provide extra functionality, will work without them): --- --- - Enabled |mini.icons| module to show icons near file names. --- Falls back to [nvim-tree/nvim-web-devicons](https://github.com/nvim-tree/nvim-web-devicons) --- or shows nothing. --- --- # Setup ~ --- --- This module needs a setup with `require('mini.tabline').setup({})` --- (replace `{}` with your `config` table). It will create global Lua table --- `MiniTabline` which you can use for scripting or manually (with --- `:lua MiniTabline.*`). --- --- See |MiniTabline.config| for `config` structure and default values. --- --- You can override runtime config settings locally to buffer inside --- `vim.b.minitabline_config` which should have same structure as --- `MiniTabline.config`. See |mini.nvim-buffer-local-config| for more details. --- --- # Suggested option values ~ --- --- Some options are set automatically by |MiniTabline.setup()|: --- - |'showtabline'| is set to 2 to always show tabline. --- --- # Highlight groups ~ --- *MiniTabline-hl-groups* --- --- - `MiniTablineCurrent` - buffer is current (has cursor in it). --- - `MiniTablineVisible` - buffer is visible (displayed in some window). --- - `MiniTablineHidden` - buffer is hidden (not displayed). --- - `MiniTablineModifiedCurrent` - buffer is modified and current. --- - `MiniTablineModifiedVisible` - buffer is modified and visible. --- - `MiniTablineModifiedHidden` - buffer is modified and hidden. --- - `MiniTablineFill` - unused right space of tabline. --- - `MiniTablineTabpagesection` - section with tabpage information. --- - `MiniTablineTrunc` - truncation symbols indicating more left/right tabs. --- --- To change any highlight group, set it directly with |nvim_set_hl()|. --- --- # Disabling ~ --- --- To disable (show empty tabline), set `vim.g.minitabline_disable` (globally) or --- `vim.b.minitabline_disable` (for a buffer) to `true`. Considering high number --- of different scenarios and customization intentions, writing exact rules --- for disabling module's functionality is left to user. See --- |mini.nvim-disabling-recipes| for common recipes. ---@tag MiniTabline -- Module definition ========================================================== local MiniTabline = {} local H = {} --- Module setup --- ---@param config table|nil Module config table. See |MiniTabline.config|. --- ---@usage >lua --- require('mini.tabline').setup() -- use default config --- -- OR --- require('mini.tabline').setup({}) -- replace {} with your config table --- < MiniTabline.setup = function(config) -- Export module _G.MiniTabline = MiniTabline -- Setup config config = H.setup_config(config) -- Apply config H.apply_config(config) -- Define behavior H.create_autocommands() -- Create default highlighting H.create_default_hl() -- Function to make tabs clickable vim.api.nvim_exec( [[function! MiniTablineSwitchBuffer(buf_id, clicks, button, mod) execute 'buffer' a:buf_id endfunction]], false ) end --- Defaults ~ ---@eval return MiniDoc.afterlines_to_code(MiniDoc.current.eval_section) ---@text # Format ~ --- --- `config.format` is a callable that takes buffer identifier and pre-computed --- label as arguments and returns a string with formatted label. Output will be --- treated strictly as text (i.e. no |'statusline'| like constructs is allowed). --- This function will be called for all displayable in tabline buffers. --- Default: |MiniTabline.default_format()|. --- --- Example of adding "+" suffix for modified buffers: >lua --- --- function(buf_id, label) --- local suffix = vim.bo[buf_id].modified and '+ ' or '' --- return MiniTabline.default_format(buf_id, label) .. suffix --- end --- < MiniTabline.config = { -- Whether to show file icons (requires 'mini.icons') show_icons = true, -- Function which formats the tab label -- By default surrounds with space and possibly prepends with icon format = nil, -- Where to show tabpage section in case of multiple vim tabpages. -- One of 'left', 'right', 'none'. tabpage_section = 'left', } --minidoc_afterlines_end -- Module functionality ======================================================= --- Make string for |'tabline'| MiniTabline.make_tabline_string = function() if H.is_disabled() then return '' end H.make_tabpage_section() H.list_tabs() H.finalize_labels() H.fit_width() return H.concat_tabs() end --- Default tab format --- --- Used by default as `config.format`. --- Prepends label with padded icon based on buffer's name (if `show_icon` --- in |MiniTabline.config| is `true`) and surrounds label with single space. --- Note: it is meant to be used only as part of `format` in |MiniTabline.config|. --- ---@param buf_id number Buffer identifier. ---@param label string Pre-computed label. --- ---@return string Formatted label. MiniTabline.default_format = function(buf_id, label) if H.get_icon == nil then return string.format(' %s ', label) end return string.format(' %s %s ', H.get_icon(vim.api.nvim_buf_get_name(buf_id)), label) end -- Helper data ================================================================ -- Module default config H.default_config = vim.deepcopy(MiniTabline.config) -- Table to keep track of tabs H.tabs = {} -- Keep track of initially unnamed buffers H.unnamed_buffers_seq_ids = {} -- Separator of file path H.path_sep = package.config:sub(1, 1) -- String with tabpage prefix H.tabpage_section = '' -- Data about truncation characters used when there are too much tabs H.trunc = { left = '', right = '', needs_left = false, needs_right = false } -- Buffer number of center buffer H.center_buf_id = nil -- Helper functionality ======================================================= -- Settings ------------------------------------------------------------------- H.setup_config = function(config) H.check_type('config', config, 'table', true) config = vim.tbl_deep_extend('force', vim.deepcopy(H.default_config), config or {}) H.check_type('show_icons', config.show_icons, 'boolean') H.check_type('format', config.format, 'function', true) H.check_type('tabpage_section', config.tabpage_section, 'string') return config end H.apply_config = function(config) MiniTabline.config = config -- Make tabline always visible (essential for custom tabline) vim.o.showtabline = 2 -- Cache truncation characters H.cache_trunc_chars() -- Set tabline string vim.o.tabline = '%!v:lua.MiniTabline.make_tabline_string()' end H.create_autocommands = function() local gr = vim.api.nvim_create_augroup('MiniTabline', {}) vim.api.nvim_create_autocmd('ColorScheme', { group = gr, callback = H.create_default_hl, desc = 'Ensure colors' }) local trunc_opts = { group = gr, pattern = { 'list', 'listchars' }, callback = H.cache_trunc_chars } trunc_opts.desc = 'Ensure truncation characters' vim.api.nvim_create_autocmd('OptionSet', trunc_opts) end --stylua: ignore H.create_default_hl = function() local set_default_hl = function(name, data) data.default = true vim.api.nvim_set_hl(0, name, data) end set_default_hl('MiniTablineCurrent', { link = 'TabLineSel' }) set_default_hl('MiniTablineVisible', { link = 'TabLineSel' }) set_default_hl('MiniTablineHidden', { link = 'TabLine' }) set_default_hl('MiniTablineModifiedCurrent', { link = 'StatusLine' }) set_default_hl('MiniTablineModifiedVisible', { link = 'StatusLine' }) set_default_hl('MiniTablineModifiedHidden', { link = 'StatusLineNC' }) set_default_hl('MiniTablineTabpagesection', { link = 'Search' }) set_default_hl('MiniTablineFill', { link = 'Normal' }) set_default_hl('MiniTablineTrunc', { link = 'MiniTablineHidden' }) end H.is_disabled = function() return vim.g.minitabline_disable == true or vim.b.minitabline_disable == true end H.get_config = function(config) return vim.tbl_deep_extend('force', MiniTabline.config, vim.b.minitabline_config or {}, config or {}) end -- Work with tabpages --------------------------------------------------------- H.make_tabpage_section = function() local n_tabpages = vim.fn.tabpagenr('$') if n_tabpages == 1 or H.get_config().tabpage_section == 'none' then H.tabpage_section = '' return end local cur_tabpagenr = vim.fn.tabpagenr() H.tabpage_section = string.format(' Tab %s/%s ', cur_tabpagenr, n_tabpages) end -- Work with tabs ------------------------------------------------------------- -- List tabs H.list_tabs = function() local tabs = {} for _, buf_id in ipairs(vim.api.nvim_list_bufs()) do if vim.bo[buf_id].buflisted then local tab = { buf_id = buf_id } tab['hl'] = H.construct_highlight(buf_id) tab['tabfunc'] = '%' .. buf_id .. '@MiniTablineSwitchBuffer@' tab['label'], tab['label_extender'] = H.construct_label_data(buf_id) table.insert(tabs, tab) end end H.tabs = tabs end -- Tab's highlight group H.construct_highlight = function(buf_id) local hl_type = buf_id == vim.api.nvim_get_current_buf() and 'Current' or (vim.fn.bufwinnr(buf_id) > 0 and 'Visible' or 'Hidden') if vim.bo[buf_id].modified then hl_type = 'Modified' .. hl_type end return '%#MiniTabline' .. hl_type .. '#' end -- Tab's label and label extender H.construct_label_data = function(buf_id) local label, label_extender local bufpath = vim.api.nvim_buf_get_name(buf_id) if bufpath ~= '' then -- Process path buffer label = vim.fn.fnamemodify(bufpath, ':t') label_extender = H.make_path_extender(buf_id) else -- Process unnamed buffer label = H.make_unnamed_label(buf_id) label_extender = function(x) return x end end return label, label_extender end H.make_path_extender = function(buf_id) -- Add parent to current label (if possible) return function(label) local full_path = vim.api.nvim_buf_get_name(buf_id) -- Using `vim.pesc` prevents effect of problematic characters (like '.') local pattern = string.format('[^%s]+%s%s$', H.path_sep, H.path_sep, vim.pesc(label)) return string.match(full_path, pattern) or label end end -- Work with unnamed buffers -------------------------------------------------- -- Unnamed buffers are tracked in `H.unnamed_buffers_seq_ids` for -- disambiguation. This table is designed to store 'sequential' buffer -- identifier. This approach allows to have the following behavior: -- - Create three unnamed buffers. -- - Delete second one. -- - Tab label for third one remains the same. H.make_unnamed_label = function(buf_id) local buftype = vim.bo[buf_id].buftype -- Differentiate quickfix/location lists and scratch/other unnamed buffers local label = buftype == 'quickfix' -- There can be only one quickfix buffer and many location buffers and (vim.fn.getqflist({ qfbufnr = true }).qfbufnr == buf_id and '*quickfix*' or '*location*') or ((buftype == 'nofile' or buftype == 'acwrite') and '!' or '*') -- Possibly add tracking id local unnamed_id = H.get_unnamed_id(buf_id) if unnamed_id > 1 then label = string.format('%s(%d)', label, unnamed_id) end return label end H.get_unnamed_id = function(buf_id) -- Use existing sequential id if possible local seq_id = H.unnamed_buffers_seq_ids[buf_id] if seq_id ~= nil then return seq_id end -- Cache sequential id for currently unnamed buffer `buf_id` H.unnamed_buffers_seq_ids[buf_id] = vim.tbl_count(H.unnamed_buffers_seq_ids) + 1 return H.unnamed_buffers_seq_ids[buf_id] end -- Work with labels ----------------------------------------------------------- H.finalize_labels = function() if #H.tabs == 0 then return end -- Deduplicate local nonunique_buf_ids = H.get_nonunique_buf_ids() while #nonunique_buf_ids > 0 do local nothing_changed = true -- Extend labels for _, buf_id in ipairs(nonunique_buf_ids) do local tab = H.tabs[buf_id] local old_label = tab.label tab.label = tab.label_extender(tab.label) if old_label ~= tab.label then nothing_changed = false end end if nothing_changed then break end nonunique_buf_ids = H.get_nonunique_buf_ids() end -- Format labels local config = H.get_config() -- - Ensure cached `get_icon` for `default_format` (for better performance) H.ensure_get_icon(config) -- - Apply formatting local format = config.format or MiniTabline.default_format for _, tab in pairs(H.tabs) do tab.label = format(tab.buf_id, tab.label) end end H.get_nonunique_buf_ids = function() local label_counts = {} for _, tab in ipairs(H.tabs) do label_counts[tab.label] = (label_counts[tab.label] or 0) + 1 end local res = {} for i, tab in ipairs(H.tabs) do if label_counts[tab.label] > 1 then table.insert(res, i) end end return res end -- Fit tabline to maximum displayed width ------------------------------------- H.fit_width = function() if #H.tabs == 0 then return end local cur_buf = vim.api.nvim_get_current_buf() if vim.bo[cur_buf].buflisted then H.center_buf_id = cur_buf end -- Compute label width data local center_offset = 1 local tot_width = 0 for _, tab in pairs(H.tabs) do tab.label_width = H.strwidth(tab.label) tab.width_on_left = tot_width tot_width = tot_width + tab.label_width if tab.buf_id == H.center_buf_id then -- Make right end of 'center tab' to be always displayed in center in -- case of truncation center_offset = tot_width end end local display_interval = H.compute_display_interval(center_offset, tot_width) H.truncate_tabs_display(display_interval) end H.compute_display_interval = function(center_offset, tabline_width) -- left - first character to be displayed (starts with 1) -- right - last character to be displayed -- Conditions to be satisfied: -- 1) right - left + 1 = math.min(tot_width, tabline_width) -- 2) 1 <= left <= tabline_width; 1 <= right <= tabline_width local tot_width = vim.o.columns - H.strwidth(H.tabpage_section) -- Usage of `math.floor` is crucial to avoid non-integer values which might -- affect total width of output tabline string. -- Using `floor` instead of `ceil` has effect when `tot_width` is odd: -- - `floor` makes "true center" to be between second to last and last label -- character (usually non-space and space). -- - `ceil` - between last character of center label and first character of -- next label (both whitespaces). local right = math.min(tabline_width, math.floor(center_offset + 0.5 * tot_width)) local left = math.max(1, right - tot_width + 1) right = left + math.min(tot_width, tabline_width) - 1 return { left, right } end H.truncate_tabs_display = function(display_interval) local display_left, display_right = display_interval[1], display_interval[2] -- Gather visible tabs local tabs, n, first, last = {}, 0, nil, nil for i, tab in ipairs(H.tabs) do if display_left <= (tab.width_on_left + tab.label_width) and (tab.width_on_left + 1) <= display_right then table.insert(tabs, tab) n, first, last = n + 1, first or i, i end end -- Remove extra width from first and last tabs if needed local extra_on_left = display_left - (tabs[1].width_on_left + 1) if extra_on_left > 0 then for w = vim.fn.strchars(tabs[1].label) - 1, 1, -1 do tabs[1].label = vim.fn.strcharpart(tabs[1].label, 1, w) if extra_on_left <= (tabs[1].label_width - H.strwidth(tabs[1].label)) then break end end -- Compensate for possible overtruncation in case of multicell characters display_right = display_right + (tabs[1].label_width - H.strwidth(tabs[1].label) - extra_on_left) end local extra_on_right = (tabs[n].width_on_left + H.strwidth(tabs[n].label)) - display_right if extra_on_right > 0 then for w = vim.fn.strchars(tabs[n].label) - 1, 1, -1 do tabs[n].label = vim.fn.strcharpart(tabs[n].label, 0, w) if extra_on_right <= (tabs[n].label_width - H.strwidth(tabs[n].label)) then break end end end -- Truncate first and/or last tabs if there is anything to the left/right H.trunc.needs_left = H.trunc.left ~= '' and (first > 1 or H.strwidth(tabs[1].label) < tabs[1].label_width) if H.trunc.needs_left then tabs[1].label = vim.fn.strcharpart(tabs[1].label, 1) end H.trunc.needs_right = H.trunc.right ~= '' and (last < #H.tabs or H.strwidth(tabs[n].label) < tabs[n].label_width) if H.trunc.needs_right then tabs[n].label = vim.fn.strcharpart(tabs[n].label, 0, H.strwidth(tabs[n].label) - 1) end H.tabs = tabs end H.cache_trunc_chars = function() local trunc_chars = { left = '', right = '' } if vim.go.list then local listchars = vim.go.listchars trunc_chars.left = listchars:match('precedes:(.[^,]*)') or '' trunc_chars.right = listchars:match('extends:(.[^,]*)') or '' end H.trunc = trunc_chars end -- Concatenate tabs into single tablien string -------------------------------- H.concat_tabs = function() -- NOTE: it is assumed that all padding is incorporated into labels local t = {} if H.trunc.needs_left then table.insert(t, '%#MiniTablineTrunc#' .. H.trunc.left:gsub('%%', '%%%%')) end for _, tab in ipairs(H.tabs) do -- Escape '%' in labels table.insert(t, tab.hl .. tab.tabfunc .. tab.label:gsub('%%', '%%%%')) end if H.trunc.needs_right then table.insert(t, '%#MiniTablineTrunc#' .. H.trunc.right:gsub('%%', '%%%%')) end -- Usage of `%X` makes filled space to the right "non-clickable" local res = table.concat(t, '') .. '%X%#MiniTablineFill#' -- Add tabpage section if H.tabpage_section ~= '' then local position = H.get_config().tabpage_section if position == 'left' then res = '%#MiniTablineTabpagesection#' .. H.tabpage_section .. res end if position == 'right' then res = res .. '%=%#MiniTablineTabpagesection#' .. H.tabpage_section end end return res end -- Utilities ------------------------------------------------------------------ H.error = function(msg) error('(mini.tabline) ' .. msg, 0) end H.check_type = function(name, val, ref, allow_nil) if type(val) == ref or (ref == 'callable' and vim.is_callable(val)) or (allow_nil and val == nil) then return end H.error(string.format('`%s` should be %s, not %s', name, ref, type(val))) end H.strwidth = function(x) return vim.api.nvim_strwidth(x) end H.ensure_get_icon = function(config) if not config.show_icons then -- Show no icon H.get_icon = nil elseif H.get_icon ~= nil then -- Cache only once return elseif _G.MiniIcons ~= nil then -- Prefer 'mini.icons' H.get_icon = function(name) return (_G.MiniIcons.get('file', name)) end else -- Try falling back to 'nvim-web-devicons' local has_devicons, devicons = pcall(require, 'nvim-web-devicons') if not has_devicons then return end -- Use basename because it makes exact file name matching work H.get_icon = function(name) return (devicons.get_icon(vim.fn.fnamemodify(name, ':t'), nil, { default = true })) end end end return MiniTabline