### setup(opts)

Source: https://context7.com/kevinhwang91/nvim-hlslens/llms.txt

Initializes nvim-hlslens with configuration options. This function should be called once during Neovim startup. If `auto_enable` is not set to `false`, the plugin will be automatically enabled after setup. All configuration keys are optional and will use default values if omitted.

```APIDOC
## `require('hlslens').setup(opts)`

### Description
Initializes nvim-hlslens with the provided configuration table. Must be called once during Neovim startup. If `auto_enable` is not `false`, the plugin is automatically enabled immediately after setup. All configuration keys are optional; omitted keys fall back to their defaults.

### Parameters
#### Options Table (`opts`)
- **auto_enable** (boolean) - Optional - Automatically enable hlslens on startup (default: `true`).
- **enable_incsearch** (boolean) - Optional - Show lens for current match while typing in incremental search (default: `true`). Requires `nvim_parse_cmd` (Neovim >= 0.8.0).
- **calm_down** (boolean) - Optional - When true, clear all lenses and highlighting if the cursor leaves the matched range or any text is modified (default: `false`).
- **nearest_only** (boolean) - Optional - Only render a lens for the nearest match; skip all other visible matches (default: `false`).
- **nearest_float_when** (string) - Optional - When to use a floating window instead of virtual text for the nearest lens. Options: `'auto'` (default, floating window only when the line has no room for virtual text), `'always'` (always use floating window), `'never'` (never use floating window; always use virtual text).
- **float_shadow_blend** (number) - Optional - `winblend` value for the nearest floating window (0–100, default: 50).
- **virt_priority** (number) - Optional - `extmark` priority for virtual text; lower values let other plugins overlay on top (default: 100).
- **build_position_cb** (function) - Optional - Callback invoked after match positions are computed. Signature: `function(info, bufnr, changedtick, pattern)`. `info.startPos` / `info.endPos` are (1,1)-indexed `{lnum, col}` lists. (default: `nil`).
- **override_lens** (function) - Optional - Fully replace the default lens renderer with a custom function (default: `nil`). See override_lens documentation below for the full signature.

### Example
```lua
require('hlslens').setup({
    auto_enable = true,
    enable_incsearch = true,
    calm_down = false,
    nearest_only = false,
    nearest_float_when = 'auto',
    float_shadow_blend = 50,
    virt_priority = 100,
    build_position_cb = nil,
    override_lens = nil,
})
```
```

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

### Install nvim-hlslens with Packer.nvim

Source: https://github.com/kevinhwang91/nvim-hlslens/blob/main/README.md

Use this snippet to install the nvim-hlslens plugin using the Packer.nvim package manager.

```lua
use {'kevinhwang91/nvim-hlslens'}
```

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

### Setup nvim-hlslens Configuration

Source: https://context7.com/kevinhwang91/nvim-hlslens/llms.txt

Initializes nvim-hlslens with custom options. Call this once during Neovim startup. Omitted keys use default values.

```lua
require('hlslens').setup({
    -- Automatically enable hlslens on startup (default: true)
    auto_enable = true,

    -- Show lens for current match while typing in incremental search (default: true)
    -- Requires nvim_parse_cmd (Neovim >= 0.8.0)
    enable_incsearch = true,

    -- When true: clear all lenses and highlighting if the cursor leaves the matched
    -- range or any text is modified (default: false)
    calm_down = false,

    -- Only render a lens for the nearest match; skip all other visible matches (default: false)
    nearest_only = false,

    -- When to use a floating window instead of virtual text for the nearest lens:
    --   'auto'   – floating window only when the line has no room for virtual text (default)
    --   'always' – always use floating window
    --   'never'  – never use floating window; always use virtual text
    nearest_float_when = 'auto',

    -- winblend value for the nearest floating window (0–100, default: 50)
    float_shadow_blend = 50,

    -- extmark priority for virtual text; lower values let other plugins overlay on top (default: 100)
    virt_priority = 100,

    -- Optional callback invoked after match positions are computed.
    -- Signature: function(info, bufnr, changedtick, pattern)
    --   info.startPos / info.endPos – (1,1)-indexed {lnum, col} lists
    -- (default: nil)
    build_position_cb = nil,

    -- Fully replace the default lens renderer with a custom function (default: nil)
    -- See override_lens documentation below for the full signature.
    override_lens = nil,
})
```

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

### Basic Setup and Keymap Configuration for nvim-hlslens

Source: https://github.com/kevinhwang91/nvim-hlslens/blob/main/README.md

Configures nvim-hlslens with specific options like `calm_down` and `nearest_only`. It also sets up a keymap for toggling search results to the quickfix list.

```lua
require('hlslens').setup({
    calm_down = true,
    nearest_only = true,
    nearest_float_when = 'always'
})

-- run `:nohlsearch` and export results to quickfix
-- if Neovim is 0.8.0 before, remap yourself.
vim.keymap.set({'n', 'x'}, '<Leader>L', function()
    vim.schedule(function()
        if require('hlslens').exportLastSearchToQuickfix() then
            vim.cmd('cw')
        end
    end)
    return ':noh<CR>'
end, {expr = true})
```

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

### start()

Source: https://context7.com/kevinhwang91/nvim-hlslens/llms.txt

Triggers an immediate render pass for the current buffer. This function should be called after any keymap that moves to a new match (e.g., `n`, `N`, `*`, `#`) to ensure the lens display is updated. It returns `true` if hlslens is currently enabled, and `false` otherwise.

```APIDOC
## `require('hlslens').start()`

### Description
Triggers an immediate render pass for the current buffer. Call this after any keymap that moves to a new match (`n`, `N`, `*`, `#`, etc.) so hlslens knows to update the lens display. Returns `true` if hlslens is enabled, `false` otherwise.

### Example
```lua
local kopts = {noremap = true, silent = true}

-- Standard n/N remaps that invoke hlslens after each jump
vim.api.nvim_set_keymap('n', 'n',
    [[<Cmd>execute('normal! ' . v:count1 . 'n')<CR><Cmd>lua require('hlslens').start()<CR>]],
    kopts)
vim.api.nvim_set_keymap('n', 'N',
    [[<Cmd>execute('normal! ' . v:count1 . 'N')<CR><Cmd>lua require('hlslens').start()<CR>]],
    kopts)

-- Star / hash searches
vim.api.nvim_set_keymap('n', '*',  [[*<Cmd>lua  require('hlslens').start()<CR>]], kopts)
vim.api.nvim_set_keymap('n', '#',  [[#<Cmd>lua  require('hlslens').start()<CR>]], kopts)
vim.api.nvim_set_keymap('n', 'g*', [[g*<Cmd>lua require('hlslens').start()<CR>]], kopts)
vim.api.nvim_set_keymap('n', 'g#', [[g#<Cmd>lua require('hlslens').start()<CR>]], kopts)
```
```

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

### Configure vim-asterisk with nvim-hlslens

Source: https://github.com/kevinhwang91/nvim-hlslens/blob/main/README.md

Integrates vim-asterisk search functionality with nvim-hlslens. Requires the vim-asterisk plugin to be installed.

```lua
-- packer
use 'haya14busa/vim-asterisk'

vim.api.nvim_set_keymap('n', '*', [[<Plug>(asterisk-z*)<Cmd>lua require('hlslens').start()<CR>]], {})
vim.api.nvim_set_keymap('n', '#', [[<Plug>(asterisk-z#)<Cmd>lua require('hlslens').start()<CR>]], {})
vim.api.nvim_set_keymap('n', 'g*', [[<Plug>(asterisk-gz*)<Cmd>lua require('hlslens').start()<CR>]], {})
vim.api.nvim_set_keymap('n', 'g#', [[<Plug>(asterisk-gz#)<Cmd>lua require('hlslens').start()<CR>]], {})

vim.api.nvim_set_keymap('x', '*', [[<Plug>(asterisk-z*)<Cmd>lua require('hlslens').start()<CR>]], {})
vim.api.nvim_set_keymap('x', '#', [[<Plug>(asterisk-z#)<Cmd>lua require('hlslens').start()<CR>]], {})
vim.api.nvim_set_keymap('x', 'g*', [[<Plug>(asterisk-gz*)<Cmd>lua require('hlslens').start()<CR>]], {})
vim.api.nvim_set_keymap('x', 'g#', [[<Plug>(asterisk-gz#)<Cmd>lua require('hlslens').start()<CR>]], {})
```

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

### Start nvim-hlslens Rendering

Source: https://context7.com/kevinhwang91/nvim-hlslens/llms.txt

Triggers an immediate render pass for the current buffer. Call this after search keymaps to update the lens display. Returns true if enabled, false otherwise.

```lua
local kopts = {noremap = true, silent = true}

-- Standard n/N remaps that invoke hlslens after each jump
vim.api.nvim_set_keymap('n', 'n',
    [[<Cmd>execute('normal! ' . v:count1 . 'n')<CR><Cmd>lua require('hlslens').start()<CR>]],
    kopts)
vim.api.nvim_set_keymap('n', 'N',
    [[<Cmd>execute('normal! ' . v:count1 . 'N')<CR><Cmd>lua require('hlslens').start()<CR>]],
    kopts)

-- Star / hash searches
vim.api.nvim_set_keymap('n', '*',  [[*<Cmd>lua  require('hlslens').start()<CR>]], kopts)
vim.api.nvim_set_keymap('n', '#',  [[#<Cmd>lua  require('hlslens').start()<CR>]], kopts)
vim.api.nvim_set_keymap('n', 'g*', [[g*<Cmd>lua require('hlslens').start()<CR>]], kopts)
vim.api.nvim_set_keymap('n', 'g#', [[g#<Cmd>lua require('hlslens').start()<CR>]], kopts)
```

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

### Stop and Resume nvim-hlslens

Source: https://context7.com/kevinhwang91/nvim-hlslens/llms.txt

Clears active lenses and highlighting without disabling the plugin. Call `start()` to resume rendering. Useful for temporary disabling.

```lua
-- Clear lenses with <Leader>l without fully disabling the plugin
vim.api.nvim_set_keymap('n', '<Leader>l', '<Cmd>noh<CR>', {noremap = true, silent = true})

-- Programmatic stop/start cycle
local hlslens = require('hlslens')
hlslens.stop()
-- … do some work that should not show lenses …
hlslens.start()
```

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

### Configure nvim-ufo with nvim-hlslens

Source: https://github.com/kevinhwang91/nvim-hlslens/blob/main/README.md

Adapts nvim-hlslens to work with nvim-ufo's folding mechanism. Ensure both plugins and 'kevinhwang91/promise-async' are installed. This configuration remaps 'n' and 'N' to peek at folded lines.

```lua
-- packer
use {'kevinhwang91/nvim-ufo', requires = 'kevinhwang91/promise-async'}

-- if Neovim is 0.8.0 before, remap yourself.
local function nN(char)
    local ok, winid = hlslens.nNPeekWithUFO(char)
    if ok and winid then
        -- Safe to override buffer scope keymaps remapped by ufo,
        -- ufo will restore previous buffer keymaps before closing preview window
        -- Type <CR> will switch to preview window and fire `trace` action
        vim.keymap.set('n', '<CR>', function()
            return '<Tab><CR>'
        end, {buffer = true, remap = true, expr = true})
    end
end

vim.keymap.set({'n', 'x'}, 'n', function() nN('n') end)
vim.keymap.set({'n', 'x'}, 'N', function() nN('N') end)
```

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

### stop()

Source: https://context7.com/kevinhwang91/nvim-hlslens/llms.txt

Clears all active lenses and highlighting without disabling the plugin. The next call to `start()` will resume rendering. It returns `true` if hlslens was enabled at the time of the call, and `false` otherwise.

```APIDOC
## `require('hlslens').stop()`

### Description
Clears all active lenses and highlighting without disabling the plugin. The next call to `start()` will resume rendering. Returns `true` if hlslens was enabled at call time, `false` otherwise.

### Example
```lua
-- Clear lenses with <Leader>l without fully disabling the plugin
vim.api.nvim_set_keymap('n', '<Leader>l', '<Cmd>noh<CR>', {noremap = true, silent = true})

-- Programmatic stop/start cycle
local hlslens = require('hlslens')
hlslens.stop()
-- … do some work that should not show lenses …
hlslens.start()
```
```

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

### Minimal nvim-hlslens Configuration

Source: https://github.com/kevinhwang91/nvim-hlslens/blob/main/README.md

This is a minimal configuration for nvim-hlslens. It sets up the plugin and defines key mappings for navigation and starting/stopping hlslens. Ensure 'incsearch' is enabled for dynamic search result display.

```lua
require('hlslens').setup()

local kopts = {noremap = true, silent = true}

vim.api.nvim_set_keymap('n', 'n',
    [[<Cmd>execute('normal! ' . v:count1 . 'n')<CR><Cmd>lua require('hlslens').start()<CR>]],
    kopts)
vim.api.nvim_set_keymap('n', 'N',
    [[<Cmd>execute('normal! ' . v:count1 . 'N')<CR><Cmd>lua require('hlslens').start()<CR>]],
    kopts)
vim.api.nvim_set_keymap('n', '*', [[*<Cmd>lua require('hlslens').start()<CR>]], kopts)
vim.api.nvim_set_keymap('n', '#', [[#<Cmd>lua require('hlslens').start()<CR>]], kopts)
vim.api.nvim_set_keymap('n', 'g*', [[g*<Cmd>lua require('hlslens').start()<CR>]], kopts)
vim.api.nvim_set_keymap('n', 'g#', [[g#<Cmd>lua require('hlslens').start()<CR>]], kopts)

vim.api.nvim_set_keymap('n', '<Leader>l', '<Cmd>noh<CR>', kopts)
```

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

### Lifecycle Control: enable(), disable(), isEnabled(), toggle()

Source: https://context7.com/kevinhwang91/nvim-hlslens/llms.txt

Manage the lifecycle of nvim-hlslens. Use enable() to register autocmds and initialize state, disable() to clean up, isEnabled() to check the current state, and toggle() to switch between enabled and disabled states.

```lua
local hlslens = require('hlslens')

-- Check state
print(hlslens.isEnabled())   -- true / false

-- Disable temporarily (e.g., during a macro recording)
if hlslens.isEnabled() then
    hlslens.disable()
end

-- Re-enable
hlslens.enable()

-- Toggle with a keybinding
vim.keymap.set('n', '<Leader>hl', function()
    hlslens.toggle()   -- prints "Enable nvim-hlslens" or "Disable nvim-hlslens"
end)
```

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

### nvim-ufo Integration for Folded Match Preview

Source: https://context7.com/kevinhwang91/nvim-hlslens/llms.txt

Integrates with nvim-ufo to preview folded matches when navigating with 'n' or 'N'. Wraps the motion with `ufo.peekFoldedLinesUnderCursor()` and calls `hlslens.start()`. Returns `(enabled: boolean, winid: number)`.

```lua
-- packer.nvim setup for nvim-ufo + nvim-hlslens
use {'kevinhwang91/nvim-ufo', requires = 'kevinhwang91/promise-async'}

local hlslens = require('hlslens')

local function nN(char)
    local ok, winid = hlslens.nNPeekWithUFO(char)
    if ok and winid then
        -- Inside the preview window <CR> switches to it and fires the 'trace' action
        vim.keymap.set('n', '<CR>', function()
            return '<Tab><CR>'
        end, {buffer = true, remap = true, expr = true})
    end
end

vim.keymap.set({'n', 'x'}, 'n', function() nN('n') end)
vim.keymap.set({'n', 'x'}, 'N', function() nN('N') end)
```

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

### Integration with vim-asterisk

Source: https://context7.com/kevinhwang91/nvim-hlslens/llms.txt

Configure nvim-hlslens to work with vim-asterisk for seamless updates after asterisk motions. This involves setting keymaps that call hlslens.start() after the asterisk command.

```lua
-- packer
use 'haya14busa/vim-asterisk'

local kopts = {}
-- Normal mode
vim.api.nvim_set_keymap('n', '*',  [[<Plug>(asterisk-z*)<Cmd>lua require('hlslens').start()<CR>]], kopts)
vim.api.nvim_set_keymap('n', '#',  [[<Plug>(asterisk-z#)<Cmd>lua require('hlslens').start()<CR>]], kopts)
vim.api.nvim_set_keymap('n', 'g*', [[<Plug>(asterisk-gz*)<Cmd>lua require('hlslens').start()<CR>]], kopts)
vim.api.nvim_set_keymap('n', 'g#', [[<Plug>(asterisk-gz#)<Cmd>lua require('hlslens').start()<CR>]], kopts)

-- Visual mode
vim.api.nvim_set_keymap('x', '*',  [[<Plug>(asterisk-z*)<Cmd>lua require('hlslens').start()<CR>]], kopts)
vim.api.nvim_set_keymap('x', '#',  [[<Plug>(asterisk-z#)<Cmd>lua require('hlslens').start()<CR>]], kopts)
vim.api.nvim_set_keymap('x', 'g*', [[<Plug>(asterisk-gz*)<Cmd>lua require('hlslens').start()<CR>]], kopts)
vim.api.nvim_set_keymap('x', 'g#', [[<Plug>(asterisk-gz#)<Cmd>lua require('hlslens').start()<CR>]], kopts)
```

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

### Bind Toggle Command to Key

Source: https://context7.com/kevinhwang91/nvim-hlslens/llms.txt

Map the HlSearchLensToggle Ex command to a key in normal mode for quick access.

```lua
vim.keymap.set('n', '<F4>', '<Cmd>HlSearchLensToggle<CR>', {silent = true})
```

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

### nvim-ufo Integration: nNPeekWithUFO

Source: https://context7.com/kevinhwang91/nvim-hlslens/llms.txt

Helper function for integrating with nvim-ufo to preview folded matches when using the 'n' and 'N' motions.

```APIDOC
## `require('hlslens').nNPeekWithUFO(char, ...)`

### Description
Integration helper for nvim-ufo. Wraps the `n`/`N` motion with `ufo.peekFoldedLinesUnderCursor()` to allow previewing folded matches. After previewing, it calls `hlslens.start()`.

### Parameters
* `char` (string) - The motion character ('n' or 'N').
* `...` - Additional arguments to be forwarded to `ufo.peekFoldedLinesUnderCursor()`.

### Returns
* `(enabled: boolean, winid: number)` - A tuple indicating if the operation was enabled and the window ID if applicable.
```

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

### Export Last Search to Quickfix/Location List

Source: https://context7.com/kevinhwang91/nvim-hlslens/llms.txt

Export match positions from the last search to the quickfix or location list. Subsequent calls for the same pattern update the existing entry. Use `exportLastSearchToQuickfix(true)` for the location list.

```lua
-- Export to quickfix then open the quickfix window
vim.keymap.set({'n', 'x'}, '<Leader>L', function()
    vim.schedule(function()
        if require('hlslens').exportLastSearchToQuickfix() then
            vim.cmd('cw')
        end
    end)
    return ':noh<CR>'
end, {expr = true})

-- Export to location list instead
vim.keymap.set('n', '<Leader>LL', function()
    if require('hlslens').exportLastSearchToQuickfix(true) then
        vim.cmd('lopen')
    end
end)
```

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

### Lifecycle Control: enable(), disable(), isEnabled(), toggle()

Source: https://context7.com/kevinhwang91/nvim-hlslens/llms.txt

Functions to manage the lifecycle of nvim-hlslens. `enable()` initializes the plugin, `disable()` cleans up resources, `isEnabled()` checks the current state, and `toggle()` switches between enabled and disabled states.

```APIDOC
## Lifecycle Control Functions

### `require('hlslens').enable()`

Initializes internal state and registers all necessary autocmds.

### `require('hlslens').disable()`

Disposes of all resources and removes all extmarks.

### `require('hlslens').isEnabled()`

Returns the current boolean state of the plugin (true if enabled, false otherwise).

### `require('hlslens').toggle()`

Switches between the enabled and disabled states and emits a vim notification.
```

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

### Integration with vim-visual-multi

Source: https://context7.com/kevinhwang91/nvim-hlslens/llms.txt

Synchronize nvim-hlslens highlight groups with vim-visual-multi's multi-cursor sessions. This involves overriding the lens renderer during visual_multi_start and restoring it on visual_multi_exit.

```lua
use 'mg979/vim-visual-multi'

local hlslens = require('hlslens')
if hlslens then
    local overrideLens = function(render, posList, nearest, idx, relIdx)
        local _ = relIdx
        local lnum, col = unpack(posList[idx])
        local text, chunks
        if nearest then
            text   = ('[%d/%d]'):format(idx, #posList)
            chunks = {{' ', 'Ignore'}, {text, 'VM_Extend'}}
        else
            text   = ('[%d]'):format(idx)
            chunks = {{' ', 'Ignore'}, {text, 'HlSearchLens'}}
        end
        render.setVirt(0, lnum - 1, col - 1, chunks, nearest)
    end

    local lensBak
    local config = require('hlslens.config')
    local gid = vim.api.nvim_create_augroup('VMlens', { clear = true })
    vim.api.nvim_create_autocmd('User', {
        pattern  = {'visual_multi_start', 'visual_multi_exit'},
        group    = gid,
        callback = function(ev)
            if ev.match == 'visual_multi_start' then
                lensBak = config.override_lens
                config.override_lens = overrideLens
            else
                config.override_lens = lensBak
            end
            hlslens.start()
        end,
    })
end
```

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

### Default Configuration Options for nvim-hlslens

Source: https://github.com/kevinhwang91/nvim-hlslens/blob/main/README.md

Defines the default configuration options for nvim-hlslens, including auto-enabling, incsearch integration, and virtual text priority. These options control the plugin's behavior and appearance.

```lua
{
    auto_enable = {
        description = [[Enable nvim-hlslens automatically]],
        default = true
    },
    enable_incsearch = {
        description = [[When `incsearch` option is on and enable_incsearch is true, add lens
            for the current matched instance]],
        default = true
    },
    calm_down = {
        description = [[If calm_down is true, clear all lens and highlighting When the cursor is
            out of the position range of the matched instance or any texts are changed]],
        default = false,
    },
    nearest_only = {
        description = [[Only add lens for the nearest matched instance and ignore others]],
        default = false
    },
    nearest_float_when = {
        description = [[When to open the floating window for the nearest lens.
            'auto': floating window will be opened if room isn't enough for virtual text;
            'always': always use floating window instead of virtual text;
            'never': never use floating window for the nearest lens]],
        default = 'auto',
    },
    float_shadow_blend = {
        description = [[Winblend of the nearest floating window. `:h winbl` for more details]],
        default = 50,
    },
    virt_priority = {
        description = [[Priority of virtual text, set it lower to overlay others.
        `:h nvim_buf_set_extmark` for more details]],
        default = 100,
    },
    override_lens  = {
        description = [[Hackable function for customizing the lens. If you like hacking, you
            should search `override_lens` and inspect the corresponding source code.
            There's no guarantee that this function will not be changed in the future. If it is
            changed, it will be listed in the CHANGES file.
            @param render table an inner module for hlslens, use `setVirt` to set virtual text
            @param splist table (1,1)-indexed position
            @param nearest boolean whether nearest lens
            @param idx number nearest index in the plist
            @param relIdx number relative index, negative means before current position,
                                  positive means after
        ]],
        default = nil
    },
}
```

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

### Configure vim-visual-multi with nvim-hlslens

Source: https://github.com/kevinhwang91/nvim-hlslens/blob/main/README.md

Customizes nvim-hlslens to work with vim-visual-multi for enhanced visual selection highlighting. This configuration overrides the lens rendering to display visual-multi specific information.

```lua
-- packer
use 'mg979/vim-visual-multi'

local hlslens = require('hlslens')
if hlslens then
    local overrideLens = function(render, posList, nearest, idx, relIdx)
        local _ = relIdx
        local lnum, col = unpack(posList[idx])

        local text, chunks
        if nearest then
            text = ('[%d/%d]'):format(idx, #posList)
            chunks = {{' ', 'Ignore'}, {text, 'VM_Extend'}}
        else
            text = ('[%d]'):format(idx)
            chunks = {{' ', 'Ignore'}, {text, 'HlSearchLens'}}
        end
        render.setVirt(0, lnum - 1, col - 1, chunks, nearest)
    end
    local lensBak
    local config = require('hlslens.config')
    local gid = vim.api.nvim_create_augroup('VMlens', {})
    vim.api.nvim_create_autocmd('User', {
        pattern = {'visual_multi_start', 'visual_multi_exit'},
        group = gid,
        callback = function(ev)
            if ev.match == 'visual_multi_start' then
                lensBak = config.override_lens
                config.override_lens = overrideLens
            else
                config.override_lens = lensBak
            end
            hlslens.start()
        end
    })
end
```

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

### nvim-hlslens Ex Commands

Source: https://context7.com/kevinhwang91/nvim-hlslens/llms.txt

Control the enable/disable state of nvim-hlslens using Ex commands. These can be used directly in the command line or mapped to keys.

```vim
" Toggle enable/disable
:HlSearchLensToggle

" Explicitly enable
:HlSearchLensEnable

" Explicitly disable
:HlSearchLensDisable
```

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

### Configuration: build_position_cb

Source: https://context7.com/kevinhwang91/nvim-hlslens/llms.txt

A callback function that is executed every time match positions are computed for a buffer.

```APIDOC
## `config.build_position_cb` — Position Computed Callback

### Description
A callback fired every time match positions are freshly computed for a buffer. It receives the position info table, the buffer number, the buffer's changedtick, and the search pattern. This is useful for custom highlighting or external integrations.

### Parameters for `build_position_cb` function:
* `info` - A table containing match position information, with `startPos` and `endPos` (lists of `(1,1)`-indexed `{lnum, col}` arrays).
* `bufnr` - The buffer number for which positions were computed.
* `changedtick` - The changedtick value of the buffer when positions were computed.
* `pattern` - The search pattern used.
```

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

### Export Last Search to Quickfix/Location List

Source: https://context7.com/kevinhwang91/nvim-hlslens/llms.txt

Exports match positions from the last search to the quickfix or location list. Useful for navigating search results.

```APIDOC
## `require('hlslens').exportLastSearchToQuickfix(isLocation?)`

### Description
Exports all match positions from the last search in the current buffer to the quickfix list. If `isLocation` is set to `true`, it exports to the location list of the current window instead. Returns `true` on success. Subsequent calls with the same search pattern will replace the previous entry.

### Parameters
* `isLocation` (boolean) - Optional - If `true`, exports to the location list; otherwise, exports to the quickfix list.

### Returns
* `boolean` - `true` on success, `false` otherwise.
```

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

### Customizing Virtual Text Display in nvim-hlslens

Source: https://github.com/kevinhwang91/nvim-hlslens/blob/main/README.md

Provides a custom function for `override_lens` to control the appearance of virtual text, including indicators for relative position and counts. This allows for detailed visual feedback on search matches.

```lua
require('hlslens').setup({
    override_lens = function(render, posList, nearest, idx, relIdx)
        local sfw = vim.v.searchforward == 1
        local indicator, text, chunks
        local absRelIdx = math.abs(relIdx)
        if absRelIdx > 1 then
            indicator = ('%d%s'):format(absRelIdx, sfw ~= (relIdx > 1) and '▲' or '▼')
        elseif absRelIdx == 1 then
            indicator = sfw ~= (relIdx == 1) and '▲' or '▼'
        else
            indicator = ''
        end

        local lnum, col = unpack(posList[idx])
        if nearest then
            local cnt = #posList
            if indicator ~= '' then
                text = ('[%s %d/%d]'):format(indicator, idx, cnt)
            else
                text = ('[%d/%d]'):format(idx, cnt)
            end
            chunks = {{' '}, {text, 'HlSearchLensNear'}}
        else
            text = ('[%s %d]'):format(indicator, idx)
            chunks = {{' '}, {text, 'HlSearchLens'}}
        end
        render.setVirt(0, lnum - 1, col - 1, chunks, nearest)
    end
})
```

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

### Custom Highlight Groups for nvim-hlslens

Source: https://context7.com/kevinhwang91/nvim-hlslens/llms.txt

Override default highlight groups to customize the appearance of search lenses. This can be done directly or by linking to existing highlight groups.

```lua
vim.api.nvim_set_hl(0, 'HlSearchNear',     {fg = '#ffffff', bg = '#e06c75', bold = true})
vim.api.nvim_set_hl(0, 'HlSearchLens',     {fg = '#abb2bf', bg = '#3e4452', italic = true})
vim.api.nvim_set_hl(0, 'HlSearchLensNear', {fg = '#ffffff', bg = '#61afef', bold = true})
```

```lua
vim.api.nvim_set_hl(0, 'HlSearchLens',     {link = 'Comment'})
vim.api.nvim_set_hl(0, 'HlSearchLensNear', {link = 'Search'})
```

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

### Custom Lens Renderer with override_lens

Source: https://context7.com/kevinhwang91/nvim-hlslens/llms.txt

Replace the default virtual text rendering with a custom function. The function receives internal render modules, match position lists, and nearest match information. Use `render.setVirt()` to place custom chunks.

```lua
-- Custom lens that shows directional arrows and a compact "[▲ 3/12]" style indicator
require('hlslens').setup({
    override_lens = function(render, posList, nearest, idx, relIdx)
        local sfw = vim.v.searchforward == 1
        local indicator, text, chunks
        local absRelIdx = math.abs(relIdx)

        -- Build a direction indicator (▲ = earlier in file, ▼ = later in file)
        if absRelIdx > 1 then
            indicator = ('%d%s'):format(absRelIdx, sfw ~= (relIdx > 1) and '▲' or '▼')
        elseif absRelIdx == 1 then
            indicator = sfw ~= (relIdx == 1) and '▲' or '▼'
        else
            indicator = ''
        end

        local lnum, col = unpack(posList[idx])
        if nearest then
            local cnt = #posList
            text = indicator ~= ''
                and ('[%s %d/%d]'):format(indicator, idx, cnt)
                or  ('[%d/%d]'):format(idx, cnt)
            chunks = {{' '}, {text, 'HlSearchLensNear'}}
        else
            text = ('[%s %d]'):format(indicator, idx)
            chunks = {{' '}, {text, 'HlSearchLens'}}
        end

        -- render.setVirt(bufnr, row_0indexed, col_0indexed, chunks, nearest)
        render.setVirt(0, lnum - 1, col - 1, chunks, nearest)
    end,
})
```

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

### Configuration: override_lens

Source: https://context7.com/kevinhwang91/nvim-hlslens/llms.txt

Allows customization of the virtual text displayed for each match, enabling custom rendering logic.

```APIDOC
## `config.override_lens` — Custom Lens Renderer

### Description
Replace the default `[idx/total]` virtual text with any custom rendering by supplying a function to `override_lens` in `setup()`. The function receives the internal render module, a list of all match positions (1-indexed), and information about the nearest match. Use `render.setVirt()` to place chunks at any position.

### Parameters for `override_lens` function:
* `render` - The internal render module, providing methods like `setVirt()`.
* `posList` - A list of all match positions, where each position is a `(1,1)`-indexed `{lnum, col}` array.
* `nearest` - Information about the nearest match, or `nil` if no nearest match.
* `idx` - The 1-indexed position of the current match being rendered.
* `relIdx` - The relative index of the current match to the nearest match.
```

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

### Position Computed Callback with build_position_cb

Source: https://context7.com/kevinhwang91/nvim-hlslens/llms.txt

A callback function executed after match positions are computed for a buffer. It receives position info, buffer number, changedtick, and the search pattern. Useful for custom highlighting or external integrations.

```lua
require('hlslens').setup({
    build_position_cb = function(info, bufnr, changedtick, pattern)
        -- info.startPos  – list of (1,1)-indexed {lnum, col} match start positions
        -- info.endPos    – list of (1,1)-indexed {lnum, col} match end   positions
        vim.notify(
            ('hlslens: %d matches for /%s/ in buf %d'):format(
                #info.startPos, pattern, bufnr),
            vim.log.levels.INFO
        )
    end,
})
```

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

### Highlight Group Definitions for nvim-hlslens

Source: https://github.com/kevinhwang91/nvim-hlslens/blob/main/README.md

Defines highlight groups for nvim-hlslens, including `HlSearchLensNear`, `HlSearchLens`, and `HlSearchNear`. These groups control the visual appearance of search highlights and virtual text.

```vim
hi default link HlSearchNear CurSearch
hi default link HlSearchLens WildMenu
hi default link HlSearchLensNear CurSearch
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.