### Bufferline User Configuration Example

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/types.md

Example of a UserConfig object passed to the setup function. It includes options for behavior and custom highlight definitions.

```lua
local config = {
  options = { mode = "buffers" },
  highlights = {}
}
```

--------------------------------

### Complete Bufferline.nvim Configuration Example

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/configuration.md

This snippet shows a full example of how to configure bufferline.nvim using the setup function. It covers a wide range of options including display, behavior, sorting, appearance, icons, diagnostics, and custom groups and offsets. Use this as a reference for customizing your bufferline.

```lua
require("bufferline").setup({
  options = {
    mode = "buffers",
    style_preset = "default",
    themable = true,
    
    -- Display
    show_buffer_icons = true,
    show_buffer_close_icons = true,
    show_close_icon = true,
    show_tab_indicators = true,
    color_icons = true,
    
    -- Behavior
    always_show_bufferline = false,
    auto_toggle_bufferline = true,
    move_wraps_at_ends = false,
    
    -- Sorting and filtering
    sort_by = "insert_at_end",
    persist_buffer_sort = true,
    duplicates_across_groups = false,
    
    -- Appearance
    separator_style = "slant",
    tab_size = 18,
    max_name_length = 18,
    max_prefix_length = 15,
    truncate_names = false,
    
    -- Icons
    buffer_close_icon = "󰅖",
    modified_icon = "●",
    close_icon = "󰅖",
    left_trunc_marker = "  ",
    right_trunc_marker = " ",
    
    -- Numbers
    numbers = "none",
    
    -- Mouse
    left_mouse_command = "buffer %d",
    right_mouse_command = "bdelete! %d",
    middle_mouse_command = nil,
    close_command = "bdelete! %d",
    
    -- Diagnostics
    diagnostics = "nvim_lsp",
    diagnostics_update_on_event = true,
    
    -- Indicator
    indicator = {
      icon = "▎",
      style = "icon"
    },
    
    -- Groups
    groups = {
      items = {
        {
          name = "Tests",
          icon = "",
          matcher = function(buf) return buf.name:match("%_test%.lua$") end,
          priority = 2
        }
      },
      options = {
        toggle_hidden_on_enter = true
      }
    },
    
    -- Offsets
    offsets = {
      {
        filetype = "NvimTree",
        text = "File Explorer",
        highlight = "Directory"
      }
    },
    
    -- Hover
    hover = {
      enabled = true,
      delay = 200,
      reveal = {"close"}
    }
  },
  
  highlights = {
    buffer_selected = {
      fg = "#ffffff",
      bg = "#0000ff",
      bold = true
    },
    fill = {
      bg = "#222222"
    }
  }
})

```

--------------------------------

### Configuring Bufferline Style Preset

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/main-module.md

Example of how to apply a style preset, such as 'minimal', using the setup function. This configures the bufferline's appearance.

```lua
require("bufferline").setup({
  options = {
    style_preset = require("bufferline").style_preset.minimal
  }
})
```

--------------------------------

### Initialization & Setup

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/README.md

Initializes the bufferline plugin with specified options and highlights. This is the primary setup function.

```APIDOC
## Initialization & Setup

### Description
Initializes the bufferline plugin with specified options and highlights. This is the primary setup function.

### Function Signature
`require("bufferline").setup({options = {...}, highlights = {...}})

### Parameters
- **options** (table) - Optional. Configuration options for bufferline.
- **highlights** (table) - Optional. Custom highlight groups for the bufferline.
```

--------------------------------

### Initialize Bufferline Plugin

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/README.md

Call the setup function to initialize the plugin with custom options and highlights. Refer to the Main Module and Configuration guides for details.

```lua
require("bufferline").setup({options = {...}, highlights = {...}})
```

--------------------------------

### Complete Bufferline.nvim Example

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/buffers.md

A comprehensive example demonstrating how to get all visible buffers, iterate through them, display their status (current, visible, modified), and access specific buffer properties like name, path, and diagnostics.

```lua
local state = require("bufferline.state")
local buffers = require("bufferline.buffers")
local config = require("bufferline.config")

-- Get all visible buffers
local buffer_list = buffers.get_components(state)

-- Iterate and display
for i, buf in ipairs(buffer_list) do
  local status = ""
  if buf:current() then status = "[CURRENT]" end
  if buf:visible() then status = status .. "[VISIBLE]" end
  if buf.modified then status = status .. "[MODIFIED]" end
  
  print(string.format("%d. %s %s", i, buf.name, status))
end

-- Access specific buffer properties
if #buffer_list > 0 then
  local first = buffer_list[1]
  print("First buffer:")
  print("  Name:", first.name)
  print("  Path:", first.path)
  print("  Modified:", first.modified)
  print("  Icon:", first.icon)
  print("  Type:", first.buftype)
  print("  Diagnostics:", first.diagnostics)
end
```

--------------------------------

### Setup

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/INDEX.md

Initializes the bufferline plugin with specified options.

```APIDOC
## Setup

### Description
Initializes the bufferline plugin with specified options.

### Method
`require("bufferline").setup(options)

### Parameters
- **options** (table) - Configuration table for bufferline.

### Request Example
```lua
require("bufferline").setup({options = {...}})
```
```

--------------------------------

### Setup bufferline.nvim

Source: https://github.com/akinsho/bufferline.nvim/blob/main/doc/bufferline.txt

Basic setup for bufferline.nvim. Ensure `termguicolors` is enabled for best results, especially with custom color schemes.

```vim
set termguicolors
    " In your init.vim or init.lua
    lua require"bufferline".setup()
```

--------------------------------

### Initialize bufferline.nvim with Setup

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/main-module.md

Use the `setup` function to initialize bufferline.nvim. Pass a configuration object to customize options and highlights. This function applies user settings, resets highlights, sets up group management, registers autocommands and user commands, and configures diagnostic handlers and hover events.

```lua
require("bufferline").setup({
  options = { /* ... */ },
  highlights = { /* ... */ }
})
```

```lua
vim.opt.termguicolors = true

require("bufferline").setup({
  options = {
    mode = "buffers",
    themable = true,
    diagnostics = "nvim_lsp",
    show_buffer_icons = true,
    show_buffer_close_icons = true,
    always_show_bufferline = false,
  },
  highlights = require("bufferline.themes.catppuccin")
})
```

--------------------------------

### Configure Bufferline Groups

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/groups.md

Example configuration for bufferline.nvim, demonstrating how to define custom groups with specific matchers, icons, and priorities. This setup includes options for automatically closing groups and toggling hidden groups on enter.

```lua
require("bufferline").setup({
  options = {
    groups = {
      items = {
        -- Tests group: matches files ending with _test.lua
        {
          name = "Tests",
          icon = "",
          priority = 2,
          matcher = function(buf)
            return buf.name:match("%_test%.lua$")
          end,
          separator = {
            left = "▎",
            right = ""
          }
        },
        -- Documentation group: matches .md files
        {
          name = "Docs",
          icon = "",
          priority = 3,
          matcher = function(buf)
            return buf.name:match("%.md$")
          end
        },
        -- Config group: matches setup/config files
        {
          name = "Config",
          icon = "",
          priority = 1,
          matcher = function(buf)
            return buf.path:match("config") or buf.path:match("setup")
          end,
          auto_close = true
        }
      },
      options = {
        toggle_hidden_on_enter = true  -- reopen hidden groups when entering
      }
    }
  }
})
```

--------------------------------

### Bufferline.nvim Setup and Commands

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/INDEX.md

Use this snippet to set up bufferline.nvim and execute common commands for buffer management. Ensure bufferline is required before calling setup.

```lua
-- Setup
require("bufferline").setup({options = {...}})

-- Navigation
require("bufferline").go_to(2)
require("bufferline").cycle(1)

-- Reordering
require("bufferline").move(1)
require("bufferline").move_to(3)

-- Sorting
require("bufferline").sort_by("extension")

-- Picking
require("bufferline").pick()

-- Closing
require("bufferline").close_others()
require("bufferline").close_in_direction("left")

-- Groups
require("bufferline.groups").toggle_pin()

-- Info
require("bufferline").get_elements()
```

--------------------------------

### Minimal Bufferline.nvim Setup

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/README.md

This is the most basic way to set up bufferline.nvim. It requires no arguments.

```lua
require("bufferline").setup{}
```

--------------------------------

### Setup Function

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/main-module.md

Initializes and configures bufferline.nvim with optional user-defined settings. This function is the primary way to integrate bufferline into your Neovim setup.

```APIDOC
## setup(conf: bufferline.UserConfig?)

### Description
Initialize and configure bufferline.nvim with optional user configuration.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **conf** (bufferline.UserConfig?) - Optional - User configuration object containing options and highlights.

### Request Example
```lua
require("bufferline").setup({
  options = {
    mode = "buffers",
    themable = true,
    diagnostics = "nvim_lsp",
    show_buffer_icons = true,
    show_buffer_close_icons = true,
    always_show_bufferline = false,
  },
  highlights = require("bufferline.themes.catppuccin")
})
```

### Response
#### Success Response (200)
This function does not return a value, but applies configuration and sets up internal systems.

#### Response Example
None
```

--------------------------------

### Iterate and Display Diagnostics

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/diagnostics.md

Example of how to iterate through the diagnostics data returned by the `get` function and display formatted information for each buffer. Assumes `config.options` is already set.

```lua
local config = require("bufferline.config")
local diagnostics = require("bufferline.diagnostics").get(config.options)

for buffer_id, diag in pairs(diagnostics) do
  print(string.format("Buffer %d: %s (%d issues)",
    buffer_id, diag.level, diag.count))
end
```

--------------------------------

### Install bufferline.nvim with lazy.nvim

Source: https://github.com/akinsho/bufferline.nvim/blob/main/README.md

Use this snippet to install bufferline.nvim with lazy.nvim. Specify a version for dependency management.

```lua
{'akinsho/bufferline.nvim', version = "*", dependencies = 'nvim-tree/nvim-web-devicons'}
```

--------------------------------

### Install bufferline.nvim with packer.nvim

Source: https://github.com/akinsho/bufferline.nvim/blob/main/README.md

Use this snippet to install bufferline.nvim with packer.nvim. Specify a tag for version control.

```lua
use {'akinsho/bufferline.nvim', tag = "*", requires = 'nvim-tree/nvim-web-devicons'}
```

--------------------------------

### Initialize Bufferline Groups Setup

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/groups.md

Call this function during bufferline setup to initialize the groups system with user-defined configurations, including custom group items and matchers. It must be called before the configuration is fully applied.

```lua
require("bufferline.groups").setup({
  options = {
    groups = {
      items = {
        {
          name = "tests",
          icon = "",
          matcher = function(buf) return buf.name:match("%_test%.lua$") end,
          priority = 2
        }
      }
    }
  }
})
```

--------------------------------

### Bufferline Highlight Link Example

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/types.md

Example demonstrating how to link a custom highlight group's attribute (foreground color) to an existing highlight group ('Normal').

```lua
highlights = {
  buffer_selected = {
    fg = { attribute = "fg", highlight = "Normal" }
  }
}
```

--------------------------------

### Setup Bufferline with Custom Highlights

Source: https://github.com/akinsho/bufferline.nvim/blob/main/doc/bufferline.txt

This is the main setup function for bufferline.nvim, demonstrating how to configure various highlight groups including fill, background, tab, selected tab, separators, close buttons, buffer visibility, numbers, and diagnostics. Color values can be specified directly or by referencing other highlight groups.

```lua
require('bufferline').setup({
    highlights = {
        fill = {
            fg = '<colour-value-here>',
            bg = '<colour-value-here>',
        },
        background = {
            fg = '<colour-value-here>',
            bg = '<colour-value-here>',
        },
        tab = {
            fg = '<colour-value-here>',
            bg = '<colour-value-here>',
        },
        tab_selected = {
            fg = '<colour-value-here>',
            bg = '<colour-value-here>',
        },
        tab_separator = {
          fg = '<colour-value-here>',
          bg = '<colour-value-here>',
        },
        tab_separator_selected = {
          fg = '<colour-value-here>',
          bg = '<colour-value-here>',
          sp = '<colour-value-here>',
          underline = '<colour-value-here>',
        },
        tab_close = {
            fg = '<colour-value-here>',
            bg = '<colour-value-here>',
        },
        close_button = {
            fg = '<colour-value-here>',
            bg = '<colour-value-here>',
        },
        close_button_visible = {
            fg = '<colour-value-here>',
            bg = '<colour-value-here>',
        },
        close_button_selected = {
            fg = '<colour-value-here>',
            bg = '<colour-value-here>',
        },
        buffer_visible = {
            fg = '<colour-value-here>',
            bg = '<colour-value-here>',
        },
        buffer_selected = {
            fg = '<colour-value-here>',
            bg = '<colour-value-here>',
            bold = true,
            italic = true,
        },
        numbers = {
            fg = '<colour-value-here>',
            bg = '<colour-value-here>',
        },
        numbers_visible = {
            fg = '<colour-value-here>',
            bg = '<colour-value-here>',
        },
        numbers_selected = {
            fg = '<colour-value-here>',
            bg = '<colour-value-here>',
            bold = true,
            italic = true,
        },
        diagnostic = {
            fg = '<colour-value-here>',
            bg = '<colour-value-here>',
        },
        diagnostic_visible = {
            fg = '<colour-value-here>',
            bg = '<colour-value-here>',
        },
        diagnostic_selected = {
            fg = '<colour-value-here>',
            bg = '<colour-value-here>',
            bold = true,
            italic = true,
        },
        hint = {
            fg = '<colour-value-here>',
            sp = '<colour-value-here>',
            bg = '<colour-value-here>',
        },
        hint_visible = {
            fg = '<colour-value-here>',
            bg = '<colour-value-here>',
        },
        hint_selected = {
            fg = '<colour-value-here>',
            bg = '<colour-value-here>',
            sp = '<colour-value-here>',
            bold = true,
            italic = true,
        },
        hint_diagnostic = {
            fg = '<colour-value-here>',
            sp = '<colour-value-here>',
            bg = '<colour-value-here>',
        },
        hint_diagnostic_visible = {
            fg = '<colour-value-here>',
            bg = '<colour-value-here>',
        },
        hint_diagnostic_selected = {
            fg = '<colour-value-here>',
            bg = '<colour-value-here>',
            sp = '<colour-value-here>',
            bold = true,
            italic = true,
        },
        info = {
            fg = '<colour-value-here>',

```

--------------------------------

### Basic bufferline.nvim Setup

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/configuration.md

Initializes bufferline.nvim with default or custom options and highlights. This is the primary function to call for configuration.

```lua
require("bufferline").setup({
  options = {
    -- options configuration
  },
  highlights = {
    -- highlight configuration
  }
})
```

--------------------------------

### Complete Color Palette Example

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/colors-highlights.md

This example demonstrates a comprehensive approach to creating a color palette by extracting primary colors, detecting background brightness, and deriving various shades and accent colors. The resulting palette is then used to define highlight groups for bufferline.nvim.

```lua
local colors = require("bufferline.colors")

-- Extract primary colors from current colorscheme
local primary = {
  normal_fg = colors.get_color({
    name = "Normal",
    attribute = "fg"
  }),
  normal_bg = colors.get_color({
    name = "Normal",
    attribute = "bg"
  }),
  error = colors.get_color({
    name = "DiagnosticError",
    attribute = "fg",
    fallback = { name = "Error", attribute = "fg" }
  })
}

-- Detect background brightness
local bright_bg = colors.color_is_bright(primary.normal_bg)
local shading_amount = bright_bg and -15 or -35

-- Create color palette
local palette = {
  -- Base colors
  primary_fg = primary.normal_fg,
  primary_bg = primary.normal_bg,
  
  -- Derived colors
  dim_fg = colors.shade_color(primary.normal_fg, -30),
  dim_bg = colors.shade_color(primary.normal_bg, shading_amount),
  
  -- Accent colors
  error = primary.error,
  error_dim = colors.shade_color(primary.error, -25)
}

-- Use palette for highlights
return {
  buffer_selected = {
    fg = palette.primary_fg,
    bg = palette.primary_bg
  },
  buffer = {
    fg = palette.dim_fg,
    bg = palette.dim_bg
  },
  error_selected = {
    fg = palette.error,
    bg = palette.primary_bg
  },
  error = {
    fg = palette.error_dim,
    bg = palette.dim_bg
  }
}
```

--------------------------------

### Install bufferline.nvim with Vimscript (vim-plug)

Source: https://github.com/akinsho/bufferline.nvim/blob/main/README.md

Use this snippet to install bufferline.nvim with vim-plug. It includes an optional dependency for colored icons.

```vimscript
Plug 'nvim-tree/nvim-web-devicons' " Recommended (for coloured icons)
" Plug 'ryanoasis/vim-devicons' Icons without colours
Plug 'akinsho/bufferline.nvim', { 'tag': '*' }
```

--------------------------------

### Setup Groups System

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/groups.md

Initializes the groups system with user-defined configurations for group items and their matching logic.

```APIDOC
## setup(conf: bufferline.UserConfig)

### Description
Initialize the groups system with user configuration.

### Parameters
- `conf` (bufferline.UserConfig) - Required - Configuration object with groups definition

### Behavior
- Called internally during bufferline setup
- Initializes group state and matchers
- Must be called before config is applied

### Example
```lua
require("bufferline.groups").setup({
  options = {
    groups = {
      items = {
        {
          name = "tests",
          icon = "",
          matcher = function(buf) return buf.name:match("%_test%.lua$") end,
          priority = 2
        }
      }
    }
  }
})
```
```

--------------------------------

### Tab Rendering Example Output

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/tabpages.md

An example of the structure for segments returned by the render function, used for displaying tab information.

```lua
[
  { highlight = "separator_hl", text = "▌" },
  { highlight = "tab_selected_hl", text = " 1 " },
  { highlight = "separator_hl", text = "▌" }
]
```

--------------------------------

### Setup bufferline.nvim with Lua

Source: https://github.com/akinsho/bufferline.nvim/blob/main/README.md

Configure bufferline.nvim using Lua. Ensure `termguicolors` is enabled for accurate color display.

```lua
vim.opt.termguicolors = true
require("bufferline").setup{}
```

--------------------------------

### Bufferline Models Complete Example

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/models.md

Demonstrates the creation and usage of Buffer and Tabpage models, including checking buffer properties, tab visibility, ancestor paths, and buffer position.

```lua
local models = require("bufferline.models")

-- Create a buffer model
local buffer = models.Buffer:new({
  path = "/home/user/project/src/main.lua",
  id = 5,
  ordinal = 1,
  diagnostics = {}
})

print("Buffer name:", buffer.name)           -- "main.lua"
print("Extension:", buffer.extension)       -- "lua"
print("Is current?", buffer:current())      -- true or false

-- Create a tab model
local tab = models.Tabpage:new({
  id = 1,
  path = "/home/user/project/README.md",
  buf = 2,
  buffers = {2, 3, 4}
})

print("Tab name:", tab.name)                 -- "1" or custom name
print("Modified?", tab.modified)            -- true or false

-- Check visibility
local vis = buffer:visibility()
if vis == 1 then
  print("Buffer is selected")
elseif vis == 2 then
  print("Buffer is visible in another window")
else
  print("Buffer is hidden")
end

-- Get ancestor path
local ancestor = buffer:ancestor(2)
print("Ancestor path:", ancestor)           -- "src/"

-- Find position in state
local state = require("bufferline.state")
local index = buffer:find_index(state)
if index then
  print("Buffer at position:", index)
end
```

--------------------------------

### Setup bufferline.nvim with Vimscript

Source: https://github.com/akinsho/bufferline.nvim/blob/main/README.md

Configure bufferline.nvim using Vimscript. Ensure `termguicolors` is set for proper color rendering.

```vimscript
" In your init.lua or init.vim
set termguicolors
lua << EOF
require("bufferline").setup{}
EOF
```

--------------------------------

### Bufferline.nvim Setup with LSP Diagnostics

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/README.md

Configure bufferline.nvim to display LSP diagnostics. It enables diagnostics and sets the update event.

```lua
require("bufferline").setup({
  options = {
    diagnostics = "nvim_lsp",
    diagnostics_update_on_event = true
  }
})
```

--------------------------------

### Complete Buffer Rendering Example

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/ui.md

Demonstrates the complete process of rendering a buffer using the UI module. This includes creating a buffer model, wrapping it with UI elements, setting up rendering context, and printing the final tabline string.

```lua
local ui = require("bufferline.ui")
local models = require("bufferline.models")
local state = require("bufferline.state")

-- Create a buffer
local buffer = models.Buffer:new({
  path = "/path/to/file.lua",
  id = 5,
  ordinal = 1
})

-- Wrap with UI rendering
local ui_buffer = ui.element(state, buffer)

-- Create context for rendering
local ctx = require("bufferline.ui").Context:new({
  tab = buffer,
  preferences = config,
  current_highlights = highlights
})

-- Render components with tabline
local components = {ui_buffer}
local result = ui.tabline(components, {}) 

-- Use rendered output
print(result.str)  -- Display in tabline
-- result.segments contains click handler data
-- result.visible_components filtered from components
```

--------------------------------

### bufferline.UserConfig

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/types.md

The top-level configuration object passed to the setup() function in bufferline.nvim. It allows for defining general options and custom highlight groups.

```APIDOC
## bufferline.UserConfig

### Description
The top-level configuration object passed to `setup()`.

### Fields
- **options** (`bufferline.Options?`) - Behavior and appearance settings
- **highlights** (`bufferline.Highlights | fun(BufferlineHighlights): bufferline.Highlights?`) - Highlight group definitions

### Example
```lua
local config = {
  options = { mode = "buffers" },
  highlights = {}
}
```
```

--------------------------------

### Style Presets

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/main-module.md

Enumeration of available style presets for bufferline appearance. These can be applied during setup.

```APIDOC
## Style Presets

### `style_preset` table

Enumeration of available style presets for bufferline appearance.

```lua
local presets = require("bufferline").style_preset
-- {
--   default = 1,
--   minimal = 2,
--   no_bold = 3,
--   no_italic = 4,
-- }
```

Use with `setup()`:

```lua
require("bufferline").setup({
  options = {
    style_preset = require("bufferline").style_preset.minimal
  }
})
```

**Available Presets**:
- `default` (1): Standard bufferline appearance
- `minimal` (2): Minimalist styling
- `no_bold` (3): Default without bold text
- `no_italic` (4): Default without italic text
```

--------------------------------

### Set Keymap for `pick()`

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/main-module.md

Example of setting a keymap to trigger the `pick()` function, allowing users to launch pick mode with a keyboard shortcut.

```lua
-- In init.lua
vim.keymap.set('n', '<leader>bp', require('bufferline').pick)
```

--------------------------------

### Example Tabline Output with Click Handlers

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/ui.md

Illustrates how click handlers are embedded within the tabline output to enable mouse interaction with buffers.

```vim
%5T%#BufferSelected#buffer 5%#Normal#
  └─ %5T: Click handler for tab/buffer 5
         %#BufferSelected#: Start highlight group
         buffer 5: Display text
         %#Normal#: End highlight group
```

--------------------------------

### Main Module API

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/DOCUMENTATION_SUMMARY.md

Provides core functionalities for bufferline.nvim, including setup, buffer navigation, reordering, sorting, selection, closing, renaming, and information retrieval.

```APIDOC
## Main Module API

### Description
Core functionalities for bufferline.nvim.

### Functions
- `setup()`: Initializes the plugin.
- `go_to(target)`: Navigates to a buffer.
- `cycle(direction)`: Cycles through buffers.
- `move(direction)`: Moves the current buffer.
- `move_to(target)`: Moves the current buffer to a specific position.
- `sort_by(strategy)`: Sorts buffers by a given strategy.
- `pick()`: Picks a buffer.
- `close()`: Closes the current buffer.
- `rename_tab(name)`: Renames the current tab.
- `get_elements()`: Retrieves buffer elements.
- `exec(command)`: Executes a command.
- `add_group(group_config)`: Adds a group.
- `remove_group(group_id)`: Removes a group.
- `set_style(preset)`: Applies a style preset.
- Deprecated functions are also available.
```

--------------------------------

### Configure Bufferline Highlights

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/configuration.md

Customize the appearance of bufferline elements by mapping highlight group names to specific styles. This example sets the selected buffer's foreground and background colors.

```lua
require("bufferline").setup({
  highlights = {
    buffer_selected = {
      fg = "#ff0000",
      bg = "#ffffff",
      bold = true,
      italic = true
    }
  }
})
```

--------------------------------

### Configure Highlight Links

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/configuration.md

Link custom highlight definitions to existing highlight groups for inheritance. This example links the foreground and background of 'buffer_selected' to 'Normal' and 'TabLineSel' respectively.

```lua
highlights = {
  buffer_selected = {
    fg = { attribute = "fg", highlight = "Normal" },
    bg = { attribute = "bg", highlight = "TabLineSel" }
  }
}
```

--------------------------------

### Get All Open Buffers as Components

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/buffers.md

Retrieves all valid open buffers, applying filters and sorting, and prepares them as UI-ready components. Use this to display the list of buffers in the bufferline.

```lua
local buffers = require("bufferline.buffers").get_components(state)

for i, buffer in ipairs(buffers) do
  print(i, buffer.name, buffer.id)
end
```

```lua
local state = require("bufferline.state")
local buffers_module = require("bufferline.buffers")

local buffers = buffers_module.get_components(state)
print(string.format("Found %d buffers", #buffers))

for _, buf in ipairs(buffers) do
  print(string.format("  - %s (%s) [%d]", buf.name, buf.path, buf.id))
end
```

--------------------------------

### Setup Bufferline with Diagnostics Enabled

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/diagnostics.md

Configure bufferline to display diagnostics. You can choose between 'nvim_lsp', 'coc', or disable it. The `diagnostics_update_on_event` option ensures timely updates. A custom `diagnostics_indicator` function can be provided for formatting.

```lua
require("bufferline").setup({
  options = {
    diagnostics = "nvim_lsp",  -- or "coc", or false to disable
    diagnostics_update_on_event = true,
    diagnostics_indicator = function(count, level, diagnostics_dict, context)
      -- Custom formatting
      return string.format(" %s %d", level:sub(1,1):upper(), count)
    end
  }
})
```

--------------------------------

### Bufferline.nvim Setup with Custom Buffer Group

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/README.md

Define a custom buffer group named 'Tests' that matches buffer names ending in '_test.lua'. This group has a priority of 2.

```lua
require("bufferline").setup({
  options = {
    groups = {
      items = {
        {
          name = "Tests",
          icon = "",
          matcher = function(buf)
            return buf.name:match("_test%.lua$")
          end,
          priority = 2
        }
      }
    }
  }
})
```

--------------------------------

### get

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/diagnostics.md

Fetches all diagnostics for open buffers. This function integrates with Neovim's LSP and CoC to retrieve error and warning data, providing a structured table of diagnostic information for each buffer.

```APIDOC
## get(options: bufferline.Options): table<number, table>

### Description
Fetch all diagnostics for open buffers. This function integrates with Neovim's LSP and CoC to retrieve error and warning data, providing a structured table of diagnostic information for each buffer.

### Method
`require("bufferline.diagnostics").get(options)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **options** (`bufferline.Options`): Required - Configuration with diagnostics mode.

### Returns
- Table mapping buffer IDs to diagnostic data. Each entry contains `count` (total issues), `level` (highest severity), and `errors` (a table with counts for each severity level).

### Example
```lua
local config = require("bufferline.config")
local diagnostics = require("bufferline.diagnostics").get(config.options)

for buffer_id, diag in pairs(diagnostics) do
  print(string.format("Buffer %d: %s (%d issues)",
    buffer_id, diag.level, diag.count))
end
```

### Diagnostic Data Structure
Each buffer's diagnostic entry contains:
```lua
{
  count = 5,              -- Total diagnostic count
  level = "error",        -- Highest severity ("error"|"warning"|"info"|"hint")
  errors = {
    error = 3,            -- Error count
    warning = 2,          -- Warning count
    info = 0,             -- Info count
    hint = 0              -- Hint count
  }
}
```
```

--------------------------------

### Get Valid Buffer Numbers

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/buffers.md

Retrieves a list of valid, open buffer numbers. Excludes temporary and unlisted buffers. Use this as a starting point for buffer manipulation.

```lua
local buf_nums = utils.get_valid_buffers()
-- Returns: number[] - all open buffer numbers
```

--------------------------------

### Advanced Bufferline Customization

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/README.md

Implement custom logic for icons, diagnostics display, buffer names, and grouping using provided callback functions within the options. Consult the Configuration Guide and module documentation.

```lua
-- Custom icons
options.get_element_icon = function(opts)
  -- opts: {path, extension, filetype, directory}
  return icon, highlight_group
end

-- Custom diagnostics display
options.diagnostics_indicator = function(count, level, dict, ctx)
  return formatted_string
end

-- Custom buffer names
options.name_formatter = function(buf)
  return display_name
end

-- Custom grouping
options.groups = {
  items = {
    {name = "Tests", matcher = function(buf) end}
  }
}
```

--------------------------------

### Bufferline Navigation Keybindings

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/README.md

Set up keybindings for navigating between buffers using bufferline.nvim. Includes cycling forward/backward and picking a buffer.

```lua
local bufferline = require("bufferline")

-- Navigation
vim.keymap.set('n', '<leader>bn', bufferline.cycle(1))
vim.keymap.set('n', '<leader>bp', bufferline.cycle(-1))
vim.keymap.set('n', '<leader>b/', bufferline.pick)
```

--------------------------------

### Get All Groups

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/groups.md

Retrieves all user-defined groups and their associated metadata.

```APIDOC
## get_all()

### Description
Get all defined user groups.

### Returns
- Table mapping group names to group definitions.

### Behavior
- Returns only user-defined groups (not including ungrouped elements).
- Each group includes all metadata (name, matcher, priority, highlight, etc.).

### Example
```lua
local all_groups = require("bufferline.groups").get_all()
for group_name, group in pairs(all_groups) do
  print("Group:", group_name, "Priority:", group.priority)
end
```
```

--------------------------------

### Get Tab Metadata

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/tabpages.md

Retrieves metadata for all existing tabpages.

```APIDOC
## get

### Description
Retrieves metadata for all existing tabpages.

### Usage
```lua
local metadata = require("bufferline.tabpages").get()
```

### Returns
* `metadata` (table) - A table containing metadata for each tab, including its ID and associated windows.
```

--------------------------------

### Tabpage:ancestor

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/models.md

Gets the ancestor path of the active buffer at a specified depth.

```APIDOC
## Tabpage:ancestor

### Description
Get ancestor path of active buffer at specified depth.

### Method
`ancestor(depth: integer, formatter: function?): string`

### Parameters
#### Path Parameters
- **depth** (integer) - Required - The depth of the ancestor path to retrieve.
- **formatter** (function) - Optional - A custom formatter function.

### Returns
Ancestor path string
```

--------------------------------

### Get Group by ID

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/groups.md

Retrieves a specific group using its unique identifier.

```APIDOC
## get_by_id(id: string): bufferline.Group?

### Description
Get a group by its ID.

### Parameters
#### Path Parameters
- **id** (string) - Required - Group identifier

### Returns
- `bufferline.Group` if found, `nil` otherwise

### Example
```lua
local group = require("bufferline.groups").get_by_id("my_group_id")
if group then
  print("Found group:", group.name)
end
```
```

--------------------------------

### Create Component Instance

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/models.md

Instantiate a new component with specified attributes. Ensure 'type' is always provided.

```lua
local comp = Component:new({
  type = "buffer",
  length = 10,
  focusable = true,
  component = function() return {...} end
})
```

--------------------------------

### Get Valid Tabs

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/tabpages.md

Filters the list of all tabs to include only those considered valid.

```lua
local valid = get_valid_tabs()
-- Filters to only valid tabpages
```

--------------------------------

### complete

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/groups.md

Provides command-line completion suggestions for buffer group names.

```APIDOC
## complete(arg_lead: string, cmd_line: string, cursor_pos: number): string[]

### Description
Command-line completion for group names (used by BufferLineGroupClose/Toggle commands).

### Parameters
#### Path Parameters
- **arg_lead** (string) - Required - Argument lead (user input)
- **cmd_line** (string) - Required - Full command line
- **cursor_pos** (number) - Required - Cursor position in command line

### Returns
- Array of matching group names for completion

### Behavior
- Called automatically by Neovim command completion
- Returns available group names matching the current input
```

--------------------------------

### Get Buffer Name

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/tabpages.md

Retrieves the display name for a buffer, defaulting to '[No Name]' if not found.

```lua
local name = get_buffer_name(buf)
-- Gets display name for tab (from buffer or "[No Name]")
```

--------------------------------

### Configure Bufferline Options and Highlights

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/README.md

Set plugin options such as buffer display mode, style preset, diagnostics integration, sorting behavior, and icon visibility. Also configure custom highlight groups.

```lua
require("bufferline").setup({
  options = {
    mode = "buffers",                    -- or "tabs"
    style_preset = "minimal",            -- or "default", "no_bold", "no_italic"
    diagnostics = "nvim_lsp",            -- or "coc" or false
    sort_by = "insert_at_end",           -- or extension, directory, custom function
    show_buffer_icons = true,
    show_close_icon = true,
    always_show_bufferline = false,
    persist_buffer_sort = true,
    custom_filter = function(buf, bufs) end,
    diagnostics_indicator = function(...) end,
    -- ... more options
  },
  highlights = {
    buffer_selected = {fg = "#fff", bg = "#000"},
    -- ... more highlights
  }
})
```

--------------------------------

### Get Buffer Diagnostics

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/buffers.md

Fetch diagnostics for a buffer. This is used when creating a Buffer model.

```lua
local all_diagnostics = diagnostics.get(options)
local buf = Buffer:new({
  diagnostics = all_diagnostics[buf_id]
})
```

--------------------------------

### bufferline.Separators

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/types.md

Defines the structure for group separator definitions, specifying start and end segments.

```APIDOC
## bufferline.Separators

### Description
Group separator definitions.

### Fields
- `sep_start` (bufferline.Segment[]) - An array of segments defining the start separator.
- `sep_end` (bufferline.Segment[]) - An array of segments defining the end separator.
```

--------------------------------

### Configuration Options

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/README.md

Details the available options for configuring bufferline.nvim's appearance and behavior.

```APIDOC
## Configuration Options

### Description
Details the available options for configuring bufferline.nvim's appearance and behavior.

### `options` Table
- **mode** (string): 'buffers' or 'tabs'.
- **style_preset** (string): 'minimal', 'default', 'no_bold', 'no_italic'.
- **diagnostics** (string | boolean): 'nvim_lsp', 'coc', or `false`.
- **sort_by** (string | function): 'insert_at_end', 'extension', 'directory', or a custom function.
- **show_buffer_icons** (boolean): Whether to show buffer icons.
- **show_close_icon** (boolean): Whether to show the close icon.
- **always_show_bufferline** (boolean): Whether to always display the bufferline.
- **persist_buffer_sort** (boolean): Whether to persist buffer sorting across sessions.
- **custom_filter** (function): A custom function to filter buffers.
- **diagnostics_indicator** (function): A function to customize the diagnostics indicator display.
- **get_element_icon** (function): A function to customize buffer icons.
- **name_formatter** (function): A function to customize buffer names.
- **groups** (table): Configuration for buffer grouping.
```

--------------------------------

### Get Tab Components

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/tabpages.md

Retrieves all tab components, providing access to their properties and associated buffers.

```APIDOC
## get_components

### Description
Retrieves all tab components, providing access to their properties and associated buffers.

### Usage
```lua
local state = require("bufferline.state")
local tabs = require("bufferline.tabpages").get_components(state)
```

### Parameters
* `state` (table) - The current state of bufferline.
```

--------------------------------

### Get Active Buffer for Tab

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/tabpages.md

Fetches the buffer associated with the active window of a specified tab.

```lua
local buf = get_active_buf_for_tab(tab_num)
-- Gets the buffer in the active window of the tab
```

--------------------------------

### get

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/tabpages.md

Retrieves metadata for all tabpages without rendering them, including their IDs and associated window IDs.

```APIDOC
## get()

### Description
Get tabpage metadata without rendering.

### Returns
```lua
{
  {
    component = bufferline.Segment[],  -- Rendered segments
    id = number,                       -- Tab number
    windows = number[]                 -- Window IDs in tab
  },
  ...
}
```

### Behavior
- Calls `vim.fn.gettabinfo()` for tab metadata
- Renders each tab's visual representation
- Returns structured data with render output

### Example
```lua
local tab_info = require("bufferline.tabpages").get()

for _, info in ipairs(tab_info) do
  print(info.id, info.windows)
end
```
```

--------------------------------

### Sort Buffers with Options

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/sorters.md

Demonstrates sorting buffer components using various options like sort_by, current_index, prev_components, and custom_sort.

```lua
local sorters = require("bufferline.sorters")

local sorted = sorters.sort(components, {
  sort_by = "extension",
  current_index = 2,
  prev_components = old_components,
  custom_sort = {1, 3, 2}  -- buffer IDs in order
})
```

--------------------------------

### Launch Pick Mode with `pick()`

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/main-module.md

Launches pick mode to interactively select a buffer or tab. Displays letter indicators for each buffer and waits for user input. Automatically exits on selection or interrupt.

```lua
require("bufferline").pick()
```

--------------------------------

### Picking

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/INDEX.md

Opens a picker to select and switch to a buffer.

```APIDOC
## Picking

### Description
Opens a picker to select and switch to a buffer.

### Method
`require("bufferline").pick()`

### Request Example
```lua
require("bufferline").pick()
```
```

--------------------------------

### Bufferline Separators Type

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/types.md

Defines the structure for group separator definitions in bufferline. Includes start and end segments.

```lua
---@class bufferline.Separators
---@field sep_start bufferline.Segment[]
---@field sep_end bufferline.Segment[]
```

--------------------------------

### Initialize Context Object

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/ui.md

Create a new context object for component rendering. Pass the tab, configuration preferences, and current highlights.

```lua
local ctx = Context:new({
  tab = buffer_element,
  preferences = config,
  current_highlights = highlights_table
})
```

--------------------------------

### Get Tab Information

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/tabpages.md

Retrieves information about all open tabs in Neovim. This includes tab number, associated windows, and variables.

```lua
local tabs = vim.fn.gettabinfo()
-- Returns: tab info from Neovim with tabnr, windows, variables
```

--------------------------------

### Enter and Exit Pick Mode

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/state.md

Demonstrates how to programmatically enter and exit pick mode using the `state.set` function. Pick mode typically displays selection letters for buffers.

```lua
local state = require("bufferline.state")

state.set({ is_picking = true })
-- UI renders with pick letters
-- User presses a key
state.set({ is_picking = false })
```

--------------------------------

### Bufferline Sorting Keybindings

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/README.md

Set up keybindings to trigger buffer sorting by extension or directory using bufferline.nvim. These keybindings call the `sort_by` function with specific arguments.

```lua
local bufferline = require("bufferline")

-- Sorting
vim.keymap.set('n', '<leader>bse', function() bufferline.sort_by("extension") end)
vim.keymap.set('n', '<leader>bsd', function() bufferline.sort_by("directory") end)
```

--------------------------------

### Get Visible Component at Specific Position

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/state.md

Fetches a component from the `visible_components` list at a given position. This list is updated after truncation during rendering.

```lua
local state = require("bufferline.state")

local pos = 5
local component = state.visible_components[pos]
if component then
  print("Component at pos", pos, "is", component.name)
end
```

--------------------------------

### Custom Left Mouse Click Command

Source: https://github.com/akinsho/bufferline.nvim/blob/main/doc/bufferline.txt

Configure a custom function for left-clicking a buffer tab, for example, to use bufdelete.nvim to close the buffer.

```lua
left_mouse_command = function(bufnum)
    require('bufdelete').bufdelete(bufnum, true)
end
```

--------------------------------

### UI Module API

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/DOCUMENTATION_SUMMARY.md

Handles the user interface rendering and interactions for bufferline.nvim.

```APIDOC
## UI Module API

### Description
Handles UI rendering and interactions.

### Functions
- `refresh()`: Triggers a UI update.
- `on_hover_over(handler)`: Sets a handler for hover over events.
- `on_hover_out(handler)`: Sets a handler for hover out events.
- Provides access to rendering context, component rendering, hover event integration, styling, and mouse interaction.
```

--------------------------------

### Create New Buffer Instance

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/api-reference/models.md

Use the `new` constructor to create a Buffer instance. Provide required attributes like path, id, and ordinal. Optional attributes include diagnostics and a custom name formatter.

```lua
local buf = models.Buffer:new({
  path = "/path/to/file.lua",
  id = 5,
  ordinal = 2,
  diagnostics = { error = 2, warning = 1 }
})
```

--------------------------------

### Get Bufferline Elements in Lua

Source: https://github.com/akinsho/bufferline.nvim/blob/main/doc/bufferline.txt

Retrieve information about currently open buffers, excluding those filtered out by bufferline. This data can be used for custom functionalities.

```lua
{
    mode = "tabs" -- depends on your config setting for mode
    elements = {
        {id = 1, name = "hi.txt", path = "/tmp/folder/hi.txt"},
        -- and so on for all open buffers
    }
}
```

--------------------------------

### Bufferline Closing Keybindings

Source: https://github.com/akinsho/bufferline.nvim/blob/main/_autodocs/README.md

Set up keybindings for closing buffers using bufferline.nvim. Includes options to close the current buffer with a pick menu or close all other buffers.

```lua
local bufferline = require("bufferline")

-- Closing
vim.keymap.set('n', '<leader>bc', bufferline.close_with_pick)
vim.keymap.set('n', '<leader>bo', bufferline.close_others)
```