[{"result":{"data":[{"id":"60618f21-244c-46e5-9800-d788103bf2c7","title":"refactor!: make scratch buffer if deleting last buffer","text":"refactor!: make scratch buffer if deleting last buffer\n\nPreviously, buffer would be listed and non-scratch.","type":"breaking-change","createdAt":"2023-07-17T02:57:23.535Z","breakingChange":{"id":11,"postId":"60618f21-244c-46e5-9800-d788103bf2c7","pluginId":109178,"externalUrl":"https://github.com/willothy/nvim-cokeline/commit/368cd3ebd2395405c2e333d6aa05d8d509ed99d2","sha":"368cd3ebd2395405c2e333d6aa05d8d509ed99d2","plugin":{"id":109178,"owner":"willothy","name":"nvim-cokeline","type":"github","source":"awesome-neovim","category":"tabline","link":"https://github.com/willothy/nvim-cokeline","shortDescription":":nose: A Neovim bufferline for people with addictive personalities","createdAt":"2023-07-15T22:16:40.354Z","readme":"\n

\n 👃 nvim-cokeline\n

\n\n\n

\nA Neovim bufferline for people with addictive personalities\n

\n\n\nThe goal of this plugin is not to be an opinionated bufferline with (more or\nless) limited customization options. Rather, it tries to provide a general\nframework allowing you to build **_your_** ideal bufferline, whatever that\nmight look like.\n\n\n![preview](https://user-images.githubusercontent.com/38540736/226447816-c696153f-ccee-4e4a-8b6a-55e53ee737f8.png)\n\n## :book: Table of Contents\n\n- [Features](#sparkles-features)\n- [Requirements](#electric_plug-requirements)\n- [Installation](#package-installation)\n- [Configuration](#wrench-configuration)\n- [Mappings](#musical_keyboard-mappings)\n\n\n\n## :sparkles: Features\n\n### Endlessly customizable\n\n`nvim-cokeline` aims to be the most customizable bufferline plugin around. If\nyou have an idea in mind of what your bufferline should look like, you should\nbe able to make it look that way. If you can't, open an issue and we'll try to\nmake it happen!\n\n\nHere's a (very limited) showcase of what it can be configured to look like\n(check out the wiki for more examples):\n\n

Click to see configuration

\n\n```lua\nlocal get_hex = require('cokeline.hlgroups').get_hl_attr\n\nrequire('cokeline').setup({\n default_hl = {\n fg = function(buffer)\n return\n buffer.is_focused\n and get_hex('ColorColumn', 'bg')\n or get_hex('Normal', 'fg')\n end,\n bg = function(buffer)\n return\n buffer.is_focused\n and get_hex('Normal', 'fg')\n or get_hex('ColorColumn', 'bg')\n end,\n },\n\n components = {\n {\n text = function(buffer) return ' ' .. buffer.devicon.icon end,\n fg = function(buffer) return buffer.devicon.color end,\n },\n {\n text = function(buffer) return buffer.unique_prefix end,\n fg = get_hex('Comment', 'fg'),\n italic = true\n },\n {\n text = function(buffer) return buffer.filename .. ' ' end,\n underline = function(buffer)\n return buffer.is_hovered and not buffer.is_focused\n end\n },\n {\n text = '',\n on_click = function(_, _, _, _, buffer)\n buffer:delete()\n end\n },\n {\n text = ' ',\n }\n },\n})\n```\n\n

\n\n![cokeline-default](https://user-images.githubusercontent.com/38540736/226447806-0d4be251-788e-495c-abf7-ae5041dcc702.png)\n\n

Click to see configuration

\n\n```lua\nlocal get_hex = require('cokeline.hlgroups').get_hl_attr\n\nlocal green = vim.g.terminal_color_2\nlocal yellow = vim.g.terminal_color_3\n\nrequire('cokeline').setup({\n default_hl = {\n fg = function(buffer)\n return\n buffer.is_focused\n and get_hex('Normal', 'fg')\n or get_hex('Comment', 'fg')\n end,\n bg = get_hex('ColorColumn', 'bg'),\n },\n\n components = {\n {\n text = '｜',\n fg = function(buffer)\n return\n buffer.is_modified and yellow or green\n end\n },\n {\n text = function(buffer) return buffer.devicon.icon .. ' ' end,\n fg = function(buffer) return buffer.devicon.color end,\n },\n {\n text = function(buffer) return buffer.index .. ': ' end,\n },\n {\n text = function(buffer) return buffer.unique_prefix end,\n fg = get_hex('Comment', 'fg'),\n italic = true,\n },\n {\n text = function(buffer) return buffer.filename .. ' ' end,\n bold = function(buffer) return buffer.is_focused end,\n },\n {\n text = ' ',\n },\n },\n})\n```\n\n

\n\n![cokeline-noib3](https://user-images.githubusercontent.com/38540736/226447808-fc834732-efd1-4fd1-a0de-65ebea213d3f.png)\n\n

Click to see configuration

\n\n```lua\nlocal get_hex = require('cokeline.hlgroups').get_hl_attr\n\nrequire('cokeline').setup({\n default_hl = {\n fg = function(buffer)\n return\n buffer.is_focused\n and get_hex('Normal', 'fg')\n or get_hex('Comment', 'fg')\n end,\n bg = 'NONE',\n },\n components = {\n {\n text = function(buffer) return (buffer.index ~= 1) and '▏' or '' end,\n fg = function() return get_hex('Normal', 'fg') end\n },\n {\n text = function(buffer) return ' ' .. buffer.devicon.icon end,\n fg = function(buffer) return buffer.devicon.color end,\n },\n {\n text = function(buffer) return buffer.filename .. ' ' end,\n bold = function(buffer) return buffer.is_focused end\n },\n {\n text = '󰖭',\n on_click = function(_, _, _, _, buffer)\n buffer:delete()\n end\n },\n {\n text = ' ',\n },\n },\n})\n```\n\n

\n\n![cokeline-bufferline-lua](https://user-images.githubusercontent.com/38540736/226447803-13f3d3ee-454f-42be-81b4-9254f95503e4.png)\n\n\n\n### Dynamic rendering\n\n\n\nEven when you have a lot of buffers open, `nvim-cokeline` is rendered to always\nkeep the focused buffer visible and in the middle of the bufferline. Also, if a\nbuffer doesn't fit entirely we still try to include as much of it as possible\nbefore cutting off the rest.\n\n\n\n![rendering](https://user-images.githubusercontent.com/38540736/226447817-4f3679c8-a10a-48ad-8329-b21c3ee54968.gif)\n\n\n\n### LSP support\n\nIf a buffer has an LSP client attached to it, you can configure the style of a\ncomponent to change based on how many errors, warnings, infos and hints are\nreported by the LSP.\n\n\n\n![lsp-styling](https://user-images.githubusercontent.com/38540736/226447813-4ec42530-9e86-43f5-98ed-fd7b4012120b.gif)\n\n\n\n### Buffer pick\n\nYou can focus and close any buffer by typing its `pick_letter`. Letters are\nassigned by filename by default (e.g. `foo.txt` gets the letter `f`), and by\nkeyboard reachability if the letter is already assigned to another buffer.\n\n\n\n

Click to see configuration

\n\n```lua\nlocal is_picking_focus = require('cokeline.mappings').is_picking_focus\nlocal is_picking_close = require('cokeline.mappings').is_picking_close\nlocal get_hex = require('cokeline.hlgroups').get_hl_attr\n\nlocal red = vim.g.terminal_color_1\nlocal yellow = vim.g.terminal_color_3\n\nrequire('cokeline').setup({\n default_hl = {\n fg = function(buffer)\n return\n buffer.is_focused\n and get_hex('Normal', 'fg')\n or get_hex('Comment', 'fg')\n end,\n bg = function() return get_hex('ColorColumn', 'bg') end,\n },\n\n components = {\n {\n text = function(buffer) return (buffer.index ~= 1) and '▏' or '' end,\n },\n {\n text = ' ',\n },\n {\n text = function(buffer)\n return\n (is_picking_focus() or is_picking_close())\n and buffer.pick_letter .. ' '\n or buffer.devicon.icon\n end,\n fg = function(buffer)\n return\n (is_picking_focus() and yellow)\n or (is_picking_close() and red)\n or buffer.devicon.color\n end,\n italic = function()\n return\n (is_picking_focus() or is_picking_close())\n end,\n bold = function()\n return\n (is_picking_focus() or is_picking_close())\n end\n },\n {\n text = ' ',\n },\n {\n text = function(buffer) return buffer.filename .. ' ' end,\n bold = function(buffer) return buffer.is_focused end,\n },\n {\n text = '',\n on_click = function(_, _, _, _, buffer)\n buffer:delete()\n end,\n },\n {\n text = ' ',\n },\n },\n})\n```\n\n

\n\n![buffer-pick](https://user-images.githubusercontent.com/38540736/226447793-8e2341b3-e454-49dc-af84-72d3b56f40d3.gif)\n\n\n\n### Sidebars\n\nYou can add a left sidebar to integrate nicely with file explorer plugins like\n[nvim-tree.lua](https://github.com/kyazdani42/nvim-tree.lua),\n[CHADTree](https://github.com/ms-jpq/chadtree) or\n[NERDTree](https://github.com/preservim/nerdtree).\n\n\n\n

Click to see configuration

\n\n```lua\nlocal get_hex = require('cokeline.hlgroups').get_hl_attr\n\nlocal yellow = vim.g.terminal_color_3\n\nrequire('cokeline').setup({\n default_hl = {\n fg = function(buffer)\n return\n buffer.is_focused\n and get_hex('Normal', 'fg')\n or get_hex('Comment', 'fg')\n end,\n bg = function() return get_hex('ColorColumn', 'bg') end,\n },\n\n sidebar = {\n filetype = {'NvimTree', 'neo-tree'},\n components = {\n {\n text = function(buf)\n return buf.filetype\n end,\n fg = yellow,\n bg = function() return get_hex('NvimTreeNormal', 'bg') end,\n bold = true,\n },\n }\n },\n\n components = {\n {\n text = function(buffer) return (buffer.index ~= 1) and '▏' or '' end,\n },\n {\n text = ' ',\n },\n {\n text = function(buffer)\n return buffer.devicon.icon\n end,\n fg = function(buffer)\n return buffer.devicon.color\n end,\n },\n {\n text = ' ',\n },\n {\n text = function(buffer) return buffer.filename .. ' ' end,\n bold = function(buffer)\n return buffer.is_focused\n end,\n },\n {\n text = '',\n on_click = function(_, _, _, _, buffer)\n buffer:delete()\n end,\n },\n {\n text = ' ',\n },\n },\n})\n```\n\n

\n\n![sidebars](https://user-images.githubusercontent.com/38540736/226447821-de543b87-909c-445f-ac6e-82f5f6bbf9aa.png)\n\n\n\n### Unique buffer names\n\nWhen files with the same filename belonging to different directories are opened\nsimultaneously, you can include a unique filetree prefix to distinguish between\nthem:\n\n\n\n![unique-prefix](https://user-images.githubusercontent.com/38540736/226447822-3315ad2f-35c9-4fc3-a777-c01cd8f2fe46.gif)\n\n\n\n### Clickable buffers\n\nLeft click on a buffer to focus it, and right click to delete it. Alternatively, define custom click handlers for each component that override the default behavior.\n\n\n\n![clickable-buffers](https://user-images.githubusercontent.com/38540736/226447799-e845d266-0658-44e3-bd89-f706577844bf.gif)\n\n\n\n### Hover events\n\nEach component has access to an is_hovered property, and can be given custom `on_mouse_enter` and `on_mouse_leave` handlers, allowing for implementations of close buttons, diagnostic previews, and more complex funcionality.\n\nNote: requires `:h 'mousemoveevent'`\n\n\n\n![hover-events](https://github.com/willothy/nvim-cokeline/assets/38540736/fb92475f-d775-44fe-9c95-a76c1cbaf560)\n\n![hover-events-2](https://github.com/willothy/nvim-cokeline/assets/38540736/3b319c79-0bff-41dd-9a08-36fd627b3d08)\n\n\n\n### Buffer re-ordering (including mouse-drag reordering)\n\n\n\n![reordering](https://user-images.githubusercontent.com/38540736/226447818-bdf63d70-e153-4353-992d-d317a5764c09.gif)\n\n\n\n### Close icons\n\n\n\n![close-icons](https://user-images.githubusercontent.com/38540736/226447802-29b2919e-dd20-4789-8d6a-250d6d453c64.gif)\n\n\n\n### Buffer history tracking\n\n```lua\nrequire(\"cokeline.history\"):last():focus()\n```\n\nIf you are a user of [`resession.nvim`](https://github.com/stevearc/resession.nvim), cokeline's history will be restored along with\nthe rest of your sessions.\n\n## :electric_plug: Requirements\n\nThe two main requirements are Neovim 0.5+ and the `termguicolors` option to be\nset. If you want to display devicons in your bufferline you'll also need the\n[kyazdani42/nvim-web-devicons](https://github.com/kyazdani42/nvim-web-devicons)\nplugin and a patched font (see [Nerd Fonts](https://www.nerdfonts.com/)).\n\nAs of v0.4.0, [nvim-lua/plenary.nvim](https://github.com/nvim-lua/plenary.nvim) is required as well.\n\n## :package: Installation\n\n### Lua\n\n#### With lazy.nvim\n\n```lua\nrequire(\"lazy\").setup({\n {\n \"willothy/nvim-cokeline\",\n dependencies = {\n \"nvim-lua/plenary.nvim\", -- Required for v0.4.0+\n \"kyazdani42/nvim-web-devicons\", -- If you want devicons\n \"stevearc/resession.nvim\" -- Optional, for persistent history\n },\n config = true\n}\n})\n```\n\n### Vimscript\n\nIf your config is still written in Vimscript and you use\n[vim-plug](https://github.com/junegunn/vim-plug):\n\n```vim\ncall plug#begin('~/.config/nvim/plugged')\n \" ...\n Plug 'nvim-lua/plenary.nvim' \" Required for v0.4.0+\n Plug 'kyazdani42/nvim-web-devicons' \" If you want devicons\n Plug 'willothy/nvim-cokeline'\n \" ...\ncall plug#end()\n\nset termguicolors\nlua << EOF\n require('cokeline').setup()\nEOF\n```\n\n## :wrench: Configuration\n\n> **note**
\n> Check out the [wiki](https://github.com/willothy/nvim-cokeline/wiki) for more details and API documentation.\n\nAll the configuration is done by changing the contents of the Lua table passed to\nthe `setup` function.\n\nThe valid keys are:\n\n```lua\nrequire('cokeline').setup({\n -- Only show the bufferline when there are at least this many visible buffers.\n -- default: `1`.\n ---@type integer\n show_if_buffers_are_at_least = 1,\n\n buffers = {\n -- A function to filter out unwanted buffers. Takes a buffer table as a\n -- parameter (see the following section for more infos) and has to return\n -- either `true` or `false`.\n -- default: `false`.\n ---@type false | fun(buf: Buffer):boolean\n filter_valid = false,\n\n -- A looser version of `filter_valid`, use this function if you still\n -- want the `cokeline-{switch,focus}-{prev,next}` mappings to work for\n -- these buffers without displaying them in your bufferline.\n -- default: `false`.\n ---@type false | fun(buf: Buffer):boolean\n filter_visible = false,\n\n -- Which buffer to focus when a buffer is deleted, `prev` focuses the\n -- buffer to the left of the deleted one while `next` focuses the one the\n -- right.\n -- default: 'next'.\n focus_on_delete = 'prev' | 'next',\n\n -- If set to `last` new buffers are added to the end of the bufferline,\n -- if `next` they are added next to the current buffer.\n -- if set to `directory` buffers are sorted by their full path.\n -- if set to `number` buffers are sorted by bufnr, as in default Neovim\n -- default: 'last'.\n ---@type 'last' | 'next' | 'directory' | 'number' | fun(a: Buffer, b: Buffer):boolean\n new_buffers_position = 'last',\n\n -- If true, right clicking a buffer will close it\n -- The close button will still work normally\n -- Default: true\n ---@type boolean\n delete_on_right_click = true,\n },\n\n mappings = {\n -- Controls what happens when the first (last) buffer is focused and you\n -- try to focus/switch the previous (next) buffer. If `true` the last\n -- (first) buffers gets focused/switched, if `false` nothing happens.\n -- default: `true`.\n ---@type boolean\n cycle_prev_next = true,\n\n -- Disables mouse mappings\n -- default: `false`.\n ---@type boolean\n disable_mouse = false,\n },\n\n -- Maintains a history of focused buffers using a ringbuffer\n history = {\n ---@type boolean\n enabled = true,\n ---The number of buffers to save in the history\n ---@type integer\n size = 2\n },\n\n rendering = {\n -- The maximum number of characters a rendered buffer is allowed to take\n -- up. The buffer will be truncated if its width is bigger than this\n -- value.\n -- default: `999`.\n ---@type integer\n max_buffer_width = 999,\n },\n\n pick = {\n -- Whether to use the filename's first letter first before\n -- picking a letter from the valid letters list in order.\n -- default: `true`\n ---@type boolean\n use_filename = true,\n\n -- The list of letters that are valid as pick letters. Sorted by\n -- keyboard reachability by default, but may require tweaking for\n -- non-QWERTY keyboard layouts.\n -- default: `'asdfjkl;ghnmxcvbziowerutyqpASDFJKLGHNMXCVBZIOWERTYQP'`\n ---@type string\n letters = 'asdfjkl;ghnmxcvbziowerutyqpASDFJKLGHNMXCVBZIOWERTYQP',\n },\n\n -- The default highlight group values.\n -- The `fg`, `bg`, and `sp` keys are either colors in hexadecimal format or\n -- functions taking a `buffer` parameter and returning a color in\n -- hexadecimal format. Style attributes work the same way, but functions\n -- should return boolean values.\n default_hl = {\n -- default: `ColorColumn`'s background color for focused buffers,\n -- `Normal`'s foreground color for unfocused ones.\n ---@type nil | string | fun(buffer: Buffer): string\n fg = function(buffer)\n local hlgroups = require(\"cokeline.hlgroups\")\n return buffer.is_focused and hlgroups.get_hl_attr(\"ColorColumn\", \"bg\")\n or hlgroups.get_hl_attr(\"Normal\", \"fg\")\n end,\n\n -- default: `Normal`'s foreground color for focused buffers,\n -- `ColorColumn`'s background color for unfocused ones.\n -- default: `Normal`'s foreground color.\n ---@type nil | string | function(buffer: Buffer): string,\n bg = function(buffer)\n local hlgroups = require(\"cokeline.hlgroups\")\n return buffer.is_focused and hlgroups.get_hl_attr(\"Normal\", \"fg\")\n or hlgroups.get_hl_attr(\"ColorColumn\", \"bg\")\n end,\n\n -- default: unset.\n ---@type nil | string | function(buffer): string,\n sp = nil,\n\n ---@type nil | boolean | fun(buf: Buffer):boolean\n bold = nil,\n ---@type nil | boolean | fun(buf: Buffer):boolean\n italic = nil,\n ---@type nil | boolean | fun(buf: Buffer):boolean\n underline = nil,\n ---@type nil | boolean | fun(buf: Buffer):boolean\n undercurl = nil,\n ---@type nil | boolean | fun(buf: Buffer):boolean\n strikethrough = nil,\n },\n\n -- The highlight group used to fill the tabline space\n fill_hl = 'TabLineFill',\n\n -- A list of components to be rendered for each buffer. Check out the section\n -- below explaining what this value can be set to.\n -- default: see `/lua/cokeline/defaults.lua`\n ---@type Component[]\n components = {},\n\n -- Custom areas can be displayed on the right hand side of the bufferline.\n -- They act identically to buffer components, except their methods don't take a Buffer object.\n -- If you want a rhs component to be stateful, you can wrap it in a closure containing state.\n ---@type Component[] | false\n rhs = {},\n\n -- Tabpages can be displayed on either the left or right of the bufferline.\n -- They act the same as other components, except they are passed TabPage objects instead of\n -- buffer objects.\n ---@type table | false\n tabs = {\n placement = \"left\" | \"right\",\n ---@type Component[]\n components = {}\n },\n\n -- Left sidebar to integrate nicely with file explorer plugins.\n -- This is a table containing a `filetype` key and a list of `components` to\n -- be rendered in the sidebar.\n -- The last component will be automatically space padded if necessary\n -- to ensure the sidebar and the window below it have the same width.\n ---@type table | false\n sidebar = {\n ---@type string | string[]\n filetype = { \"NvimTree\", \"neo-tree\", \"SidebarNvim\" },\n ---@type Component[]\n components = {},\n },\n})\n```\n\n### So what's `function(buffer)`?\n\nSome of the configuration options can be functions that take a [`Buffer`](https://github.com/willothy/nvim-cokeline/wiki/Buffer) as a\nsingle parameter. This is useful as it allows users to set the values of\ncomponents dynamically based on the buffer that component is being rendered\nfor.\n\nThe `Buffer` type is just a Lua table with the following keys:\n\n```lua\nBuffer = {\n -- The buffer's order in the bufferline (1 for the first buffer, 2 for the\n -- second one, etc.).\n index = int,\n\n -- The buffer's internal number as reported by `:ls`.\n number = int,\n\n ---@type boolean\n is_focused = false,\n\n ---@type boolean\n is_modified = false,\n\n ---@type boolean\n is_readonly = false,\n\n -- The buffer is the first visible buffer in the tab bar\n ---@type boolean\n is_first = false,\n\n -- The buffer is the last visible buffer in the tab bar\n ---@type boolean\n is_last = false,\n\n -- The mouse is hovering over the current component in the buffer\n -- This is a special variable in that it will only be true for the hovered *component*\n -- on render. This is to allow components to respond to hover events individually without managing\n -- component state.\n ---@type boolean\n is_hovered = false,\n\n -- The mouse is hovering over the buffer (true for all components)\n ---@type boolean\n buf_hovered = false,\n\n -- The buffer's type as reported by `:echo &buftype`.\n ---@type string\n ---@type string\n type = '',\n\n -- The buffer's filetype as reported by `:echo &filetype`.\n ---@type string\n filetype = '',\n\n -- The buffer's full path.\n ---@type string\n path = '',\n\n -- The buffer's filename.\n ---@type string\n filename = 'string',\n\n -- A unique prefix used to distinguish buffers with the same filename\n -- stored in different directories. For example, if we have two files\n -- `bar/foo.md` and `baz/foo.md`, then the first will have `bar/` as its\n -- unique prefix and the second one will have `baz/`.\n ---@type string\n unique_prefix = '',\n\n -- The letter that is displayed when picking a buffer to either focus or\n -- close it.\n ---@type string\n pick_letter = 'char',\n\n -- This needs the `kyazdani42/nvim-web-devicons` plugin to be installed.\n devicon = {\n -- An icon representing the buffer's filetype.\n ---@type string\n icon = 'string',\n\n -- The colors of the devicon in hexadecimal format (useful to be passed\n -- to a component's `fg` field (see the `Components` section).\n color = '#rrggbb',\n },\n\n -- The values in this table are the ones reported by Neovim's built in\n -- LSP interface.\n diagnostics = {\n ---@type integer\n errors = 0,\n ---@type integer\n warnings = 0,\n ---@type integer\n infos = 0,\n ---@type integer\n hints = 0,\n },\n}\n```\n\nIt also has methods that can be used in component event handlers:\n\n```lua\n---@param self Buffer\n---Deletes the buffer\nfunction Buffer:delete() end\n\n---@param self Buffer\n---Focuses the buffer\nfunction Buffer:focus() end\n\n---@param self Buffer\n---@return number\n---Returns the number of lines in the buffer\nfunction Buffer:lines() end\n\n---@param self Buffer\n---@return string[]\n---Returns the buffer's lines\nfunction Buffer:text() end\n\n---@param buf Buffer\n---@return boolean\n---Returns true if the buffer is valid\nfunction Buffer:is_valid() end\n```\n\n### What about [`TabPage`](https://github.com/willothy/nvim-cokeline/wiki/TabPage)s?\n\nEach method on a tab component is passed a `TabPage` object as an argument.\n\n`TabPage`, like `Buffer`, is simply a Lua table with some relevant data attached.\n\n```lua\nTabPage = {\n -- The tabpage number, as reported by `nvim_list_tabpages`\n ---@type integer\n number = 0,\n -- A list of Window objects contained in the TabPage (see wiki for more info)\n ---@type Window[]\n windows = {},\n -- The currently focused window in the TabPage\n ---@type Window\n focused = nil,\n -- True if the TabPage is the current TabPage\n ---@type boolean\n is_active = true,\n -- True if the TabPage is first in the list\n ---@type boolean\n is_first = false,\n -- True if the TabPage is last in the list\n ---@type boolean\n is_last = false\n}\n```\n\n### And [`components`](https://github.com/willothy/nvim-cokeline/wiki/Component)?\n\nYou can configure what each buffer in your bufferline will be composed of by\npassing a list of components to the `setup` function.\n\nFor example, let's imagine we want to construct a very minimal bufferline\nwhere the only things we're displaying for each buffer are its index, its\nfilename and a close button.\n\nThen in our `setup` function we'd have:\n\n```lua\nrequire('cokeline').setup({\n -- ...\n components = {\n {\n text = function(buffer) return ' ' .. buffer.index end,\n },\n {\n text = function(buffer) return ' ' .. buffer.filename .. ' ' end,\n },\n {\n text = '󰅖',\n on_click = function(_, _, _, _, buffer)\n buffer:delete()\n end\n },\n {\n text = ' ',\n }\n }\n})\n```\n\nin this case every buffer would be composed of four components: the first\ndisplaying a space followed by the buffer index, the second one the filename\npadded by a space on each side, then a close button that allows us to\n`:bdelete` the buffer by left-clicking on it, and finally an extra space.\n\nThis way of dividing each buffer into distinct components, combined with the\nability to define every component's text and color depending on some property\nof the buffer we're rendering, allows for great customizability.\n\nEvery component passed to the `components` list has to be a table of the form:\n\n```lua\n{\n\n ---@type string | fun(buffer: Buffer): string\n text = \"\",\n\n -- The foreground, backgrond and style of the component\n ---@type nil | string | fun(buffer: Buffer): string\n fg = '#rrggbb',\n ---@type nil | string | fun(buffer: Buffer): string\n bg = '#rrggbb',\n ---@type nil | string | fun(buffer: Buffer): string\n sp = '#rrggbb',\n ---@type nil | boolean | fun(buffer: Buffer): boolean\n bold = false,\n ---@type nil | boolean | fun(buffer: Buffer): boolean\n italic = false,\n ---@type nil | boolean | fun(buffer: Buffer): boolean\n underline = false,\n ---@type nil | boolean | fun(buffer: Buffer): boolean\n undercurl = false,\n ---@type nil | boolean | fun(buffer: Buffer): boolean\n strikethrough = false,\n\n -- Or, alternatively, the name of the highlight group\n ---@type nil | string | fun(buffer: Buffer): string\n highlight = nil,\n\n -- If `true` the buffer will be deleted when this component is\n -- left-clicked (usually used to implement close buttons, overrides `on_click`).\n -- deprecated, it is recommended to use the Buffer:delete() method in an on_click event\n -- to implement close buttons instead.\n ---@type boolean\n delete_buffer_on_left_click = false,\n\n -- Handles click event for a component\n -- If not set, component will have the default click behavior\n -- buffer is a Buffer object, not a bufnr\n ---@type nil | fun(idx: integer, clicks: integer, button: string, mods: string, buffer: Buffer)\n on_click = nil,\n\n -- Called on a component when hovered\n ---@type nil | function(buffer: Buffer, mouse_col: integer)\n on_mouse_enter = nil,\n\n -- Called on a component when unhovered\n ---@type nil | function(buffer: Buffer, mouse_col: integer)\n on_mouse_leave = nil,\n\n truncation = {\n -- default: index of the component in the `components` table (1 for the\n -- first component, 2 for the second, etc.).\n ---@type integer\n priority = 1,\n\n -- default: `right`.\n ---@type 'left' | 'middle' | 'right'\n direction = 'left' | 'middle' | 'right',\n },\n}\n```\n\nthe `text` key is the only one that has to be set, all the others are optional\nand can be omitted.\n\nThe `truncation` table controls what happens when a buffer is too long to be\ndisplayed in its entirety.\n\nMore specifically, if a buffer's width (given by the sum of the widths of all\nits components) is bigger than the `rendering.max_buffer_width` config option,\nthe buffer will be truncated.\n\nThe default behaviour is truncate the buffer by dropping components from right\nto left, with the text of the last component that's included also being\nshortened from right to left. This can be modified by changing the values of\nthe `truncation.priority` and `truncation.direction` keys.\n\nThe `truncation.priority` controls the order in which components are dropped:\nthe first component to be dropped will be the one with the lowest priority. If\nthat's still not enough to bring the width of the buffer within the\n`rendering.max_buffer_width` limit, the component with the second lowest\npriority will be dropped, and so on. Note that a higher priority means a\nsmaller integer value: a component with a priority of 5 will be dropped\n_after_ a component with a priority of 6, even though 6 > 5.\n\nThe `truncation.direction` key simply controls from which direction a component\nis shortened. For example, you might want to set the `truncation.direction` of\na component displaying a filename to `'middle'` or `'left'`, so that if\nthe filename has to be shortened you'll still be able to see its extension,\nlike in the following example (where it's set to `'left'`):\n\n\n\n![buffer-truncation](https://user-images.githubusercontent.com/38540736/226447798-6aee2e0f-f957-42ab-96dd-3618e78ba4ba.png)\n\n\n\n#### What about [`history`](https://github.com/willothy/nvim-cokeline/wiki/History)?\n\nThe History keeps track of the buffers you access using a ringbuffer, and provides\nan API for accessing Buffer objects from the history.\n\nYou can access the history using `require(\"cokeline.history\")`, or through the global `_G.cokeline.history`.\n\nThe `History` object provides these methods:\n\n```lua\nHistory = {}\n\n---Adds a Buffer object to the history\n---@type bufnr integer\nfunction History:push(bufnr)\nend\n\n---Removes and returns the oldest Buffer object in the history\n---@return Buffer?\nfunction History:pop()\nend\n\n---Returns a list of Buffer objects in the history,\n---ordered from oldest to newest\n---@return Buffer[]\nfunction History:list()\nend\n\n---Returns an iterator of Buffer objects in the history,\n---ordered from oldest to newest\n---@return fun(): Buffer?\nfunction History:iter()\nend\n\n---Get a Buffer object by history index\n---@param idx integer\n---@return Buffer?\nfunction History:get(idx)\nend\n\n---Get a Buffer object representing the last-accessed buffer (before the current one)\n---@return Buffer?\nfunction History:last()\nend\n\n---Returns true if the history is empty\n---@return boolean\nfunction History:is_empty()\nend\n\n---Returns the maximum number of buffers that can be stored in the history\n---@return integer\nfunction History:capacity()\nend\n\n---Returns true if the history contains the given buffer\n---@param bufnr integer\n---@return boolean\nfunction History:contains(bufnr)\nend\n\n---Returns the number of buffers in the history\n---@return integer\nfunction History:len()\nend\n```\n\n## :musical_keyboard: Mappings\n\nYou can use the `mappings` module to create mappings from Lua:\n\n```lua\nvim.keymap.set(\"n\", \"bp\", function()\n require('cokeline.mappings').pick(\"focus\")\nend, { desc = \"Pick a buffer to focus\" })\n```\n\nAlternatively, we expose the following `` mappings which can be used as the right hand\nside of other mappings:\n\n```\n-- Focus the previous/next buffer\n(cokeline-focus-prev)\n(cokeline-focus-next)\n\n-- Switch the position of the current buffer with the previous/next buffer.\n(cokeline-switch-prev)\n(cokeline-switch-next)\n\n-- Focuses the buffer with index `i`.\n(cokeline-focus-i)\n\n-- Switches the position of the current buffer with the buffer of index `i`.\n(cokeline-switch-i)\n\n-- Focus a buffer by its `pick_letter`.\n(cokeline-pick-focus)\n\n-- Close a buffer by its `pick_letter`.\n(cokeline-pick-close)\n```\n\nA possible configuration could be:\n\n```lua\nlocal map = vim.api.nvim_set_keymap\n\nmap(\"n\", \"\", \"(cokeline-focus-prev)\", { silent = true })\nmap(\"n\", \"\", \"(cokeline-focus-next)\", { silent = true })\nmap(\"n\", \"p\", \"(cokeline-switch-prev)\", { silent = true })\nmap(\"n\", \"n\", \"(cokeline-switch-next)\", { silent = true })\n\nfor i = 1, 9 do\n map(\n \"n\",\n (\"\"):format(i),\n (\"(cokeline-focus-%s)\"):format(i),\n { silent = true }\n )\n map(\n \"n\",\n (\"%s\"):format(i),\n (\"(cokeline-switch-%s)\"):format(i),\n { silent = true }\n )\nend\n\n```\n","dotfyleShieldAddedAt":null,"stars":429,"lastSyncedAt":"2023-12-01T02:25:48.219Z","addedLastWeek":0}}}]}}]